7064867 · 6a28879 · 81fff81 · c08a5f8 · 6bbccc8 · e1821fe
@@ -914,6 +914,9 @@
work here.
  not already in an earlier wave. The headline and highlights are `TODO`
  placeholders; no model is called. It refuses, writing nothing, when an
  earlier wave does not parse (naming the file) or nothing new has merged.
  `/:owner/:name/waves` lists the waves on the default branch, newest version
  first, each linking to its file (linked from that settings card); in the
  terminal, `V` in a repository opens the same list.
- **Accounts & access** — register/sign in, personal access tokens with coarse
  scopes (ro/rw/admin), public and private repositories.
@@ -27,6 +27,8 @@
export type Exclusion = {
};
export const GATE: readonly string[] = [
  "test/waves-page.test.ts",
  "test/waves-order.test.ts",
  "test/domain-drill.test.ts",
  "test/conflicts.test.ts",
  "test/lands-once.test.ts",
@@ -68,6 +70,7 @@
export const GATE: readonly string[] = [
  "test/protection.test.ts",
  "test/tui-limbs.test.ts",
  "test/tui-onyou.test.ts",
  "test/tui-waves.test.ts",
  "test/tui-deploys.test.ts",
  "test/tui-access.test.ts",
  "test/tui-decider.test.ts",
@@ -168,6 +168,7 @@
import {
  branchDelete,
  branchesPage,
} from "../web/pages/branches.ts";
import { wavesPage } from "../web/pages/waves.ts";
import {
  contributeSubmit,
  deleteFilePage,
@@ -1135,6 +1136,7 @@
export function buildRouter(): Router<Handler> {
  // The repository's activity, for a feed reader.
  router.add("GET", "/:owner/:name/activity.atom", activityAtom);
  router.add("GET", "/:owner/:name/branches", branchesPage);
  router.add("GET", "/:owner/:name/waves", wavesPage);
  router.add("POST", "/:owner/:name/branches", branchCreate);
  router.add("POST", "/:owner/:name/branches/:branch/delete", branchDelete);
@@ -0,0 +1,104 @@
/**
 * A repository's waves, read: `waves/*.md` on a branch, newest version first.
 * Parsing is `wave.ts`'s; a file that does not parse is listed with its
 * reason and breaks nothing. Both doors (the page and the terminal) read
 * through here; each applies its own visibility gate before calling.
 */
import { readerFor, listTree } from "../git/read.ts";
import { parseWave, type Wave } from "./wave.ts";
/** A page, not an archive: more files than this are not read. */
const MAX_FILES = 300;
/** A wave is a few hundred lines; a larger file is not one. */
const MAX_BYTES = 256 * 1024;
export type WaveEntry =
  | { ok: true; file: string; wave: Wave }
  | { ok: false; file: string; reason: string };
const VERSION = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?$/;
      
        sentinelcrew
        29d ago
        outdated
      
      "broken".split(".").map(Number) gives [NaN], so the comparator returns NaN for any non-version file name. Array.sort needs a consistent comparator, and this sort runs before slice(0, MAX_FILES), so the cut can drop the newest waves. Treat a non-numeric name as sorting after every version.
    
type Version = { core: number[]; pre: string[] };
const parse = (s: string): Version | null => {
  const m = VERSION.exec(s);
  if (!m) return null;
  return {
    core: [Number(m[1]), Number(m[2] ?? 0), Number(m[3] ?? 0)],
    pre: m[4] === undefined ? [] : m[4].split("."),
  };
};
const DIGITS = /^\d+$/;
      
        sentinelcrew
        29d ago
        outdated
      
      Pre-release tie-break by string: 1.0.0-rc.2 sorts ahead of 1.0.0-rc.10. Compare identifiers dot by dot, numerically when both are digits (semver §11), and unit-test this function directly.
    
/** Semver §11 for one pre-release identifier: numbers by value, below text. */
function identifier(a: string, b: string): number {
  const an = DIGITS.test(a);
  const bn = DIGITS.test(b);
  if (an && bn) return Number(a) - Number(b);
  if (an !== bn) return an ? -1 : 1;
  return a < b ? -1 : a > b ? 1 : 0;
}
/**
 * Higher version first; a release beats its own pre-release, pre-release
 * identifiers compare dot by dot. A name that is not a version sorts after
 * every version, and those among themselves by name, so the order is total.
 */
export function byVersionDesc(a: string, b: string): number {
  const x = parse(a);
  const y = parse(b);
  if (!x || !y) return x ? -1 : y ? 1 : a < b ? -1 : a > b ? 1 : 0;
  for (let i = 0; i < 3; i++) {
    const d = y.core[i]! - x.core[i]!;
    if (d !== 0) return d;
  }
  if (!x.pre.length || !y.pre.length) return x.pre.length ? 1 : y.pre.length ? -1 : 0;
  for (let i = 0; i < Math.min(x.pre.length, y.pre.length); i++) {
    const d = identifier(y.pre[i]!, x.pre[i]!);
    if (d !== 0) return d;
  }
  return y.pre.length - x.pre.length;
}
/** Every wave file on `branch`, parsed; good ones newest first, then the bad. */
export async function readWaves(
  dir: string,
  branch: string,
): Promise<WaveEntry[]> {
  const tree = await listTree(dir, branch, "waves");
  if (!tree.ok) return [];
  const files = tree.value
    .filter((e) => e.type === "blob" && e.name.endsWith(".md"))
    // Git orders names as strings (`0.10.0` before `0.9.0`); the cut is made
    // on version order so the newest waves are the ones kept.
    .sort((x, y) => byVersionDesc(x.name.slice(0, -3), y.name.slice(0, -3)))
    .slice(0, MAX_FILES);
  const reader = readerFor(dir);
  const out: WaveEntry[] = [];
  for (const f of files) {
    const path = `waves/${f.name}`;
    if (f.size > MAX_BYTES) {
      out.push({ ok: false, file: f.name, reason: `${path}: file is too large` });
      continue;
    }
    const obj = await reader.object(f.oid);
    if (!obj.ok) {
      out.push({ ok: false, file: f.name, reason: `${path}: unreadable` });
      continue;
    }
    const text = new TextDecoder().decode(obj.value.body);
    const parsed = parseWave(path, text);
    out.push(
      parsed.ok
        ? { ok: true, file: f.name, wave: parsed.value }
        : { ok: false, file: f.name, reason: parsed.error.message },
    );
  }
  const good = out.flatMap((e) => (e.ok ? [e] : []));
  const bad = out.flatMap((e) => (e.ok ? [] : [e]));
  good.sort((a, b) => byVersionDesc(a.wave.version, b.wave.version));
  return [...good, ...bad];
}
@@ -0,0 +1,90 @@
/**
 * A repository's waves: the same rows, in the same order, as the web page,
 * read through `story/waves.ts`. Local repositories only — a live browse of
 * another forge has no `waves/` we can read here, and says so.
 */
import { canRead } from "../../core/repos.ts";
import { readWaves, type WaveEntry } from "../../story/waves.ts";
import type { RepoSource } from "../../view/source.ts";
import type { Ctx, Screen } from "../app/app.ts";
import { binding } from "../app/keys.ts";
import { style } from "../term/style.ts";
import { truncate } from "../term/width.ts";
import { fill, len, split } from "../ui/layout.ts";
import { emptyState } from "../ui/widgets.ts";
import type { Session } from "../session.ts";
import { ListState, drawList, plural, runAsync } from "./common.ts";
import { localRepo, sourceName, whereRows, whereStrip } from "./where.ts";
/** One line per wave, as the screen draws it. */
export function waveRows(entries: WaveEntry[]) {
  return entries.map((e) =>
    e.ok
      ? {
          title: e.wave.headline,
          secondary: "",
          meta: `${e.wave.version}  ${e.wave.date}`,
        }
      : { title: e.file, secondary: `Not a wave: ${e.reason}`, meta: "" },
  );
}
export function wavesScreen(f: Session, ctx: Ctx, src: RepoSource): Screen {
  const repo = localRepo(src);
  let entries: WaveEntry[] = [];
  let loaded = false;
  const state = new ListState();
  const reload = async (): Promise<void> => {
    // The web's gate, not a weaker one: whoever reaches this screen, a
    // repository they cannot read has no waves to show.
    entries =
      repo !== undefined && canRead(f.db, repo, f.user)
        ? await readWaves(f.dir(repo), repo.defaultBranch)
        : [];
    loaded = true;
    ctx.invalidate();
  };
  return {
    title: "Waves",
    keys: [binding(["j", "k"], "move"), binding(["r"], "refresh")],
    load: reload,
    render(area, s) {
      const c = ctx.theme.c;
      const [strip, head, body] = split(area, "v", [
        len(whereRows(src)),
        len(1),
        fill(1),
      ]);
      whereStrip(s, strip!, c, f, src);
      s.text(
        head!.x,
        head!.y,
        truncate(
          `${sourceName(src)} · ${plural(entries.length, "wave")}`,
          head!.w,
        ),
        style(c.mutedFg, c.bg),
        head!.x + head!.w,
      );
      if (entries.length === 0) {
        emptyState(s, body!, c, {
          title: loaded ? "No waves yet" : "Reading…",
          body: loaded ? "This repository has no waves/ directory." : "",
      
        sentinelcrew
        29d ago
        
      
      For a live browse of another forge (repo === undefined), this says the repository has no waves/ directory. That is not known, and the header comment promises the screen "says so" instead. Tracked in #2076, together with Enter opening the wave file.
    
        });
        return;
      }
      drawList(s, body!, c, state, waveRows(entries));
    },
    key(e) {
      if (state.key(e, entries.length)) return true;
      if (e.key === "r") {
        runAsync(ctx, reload);
        return true;
      }
      return false;
    },
  };
}
@@ -118,6 +118,7 @@
import { liveBindings, liveKey } from "./mirror.ts";
import { forkScreen } from "./newrepo.ts";
import { pullScreen } from "./pull.ts";
import { branchesScreen } from "./refs.ts";
import { wavesScreen } from "./waves.ts";
import {
  hostOf,
  knownDefaultRef,
@@ -1287,6 +1288,7 @@
export function workspaceScreen(
              binding(["y"], "copy path"),
              binding(["i", "p", "C"], "issues / pulls / commits"),
              binding(["I"], "about this repository"),
              binding(["V"], "waves"),
              ...(repo === undefined ? [] : [binding(["d"], "production deploys")]),
              ...(repo !== undefined && admin()
                ? [binding(["R"], `decisions by ${(getRepoById(f.db, repo.id) ?? repo).decisionsBy} (cycle)`)]
@@ -1606,6 +1608,10 @@
export function workspaceScreen(
        ctx.push(commitsScreen(f, ctx, src, ref));
        return true;
      }
      if (plain && e.key === "V") {
        ctx.push(wavesScreen(f, ctx, src));
        return true;
      }
      if (plain && e.key === "d" && repo !== undefined) {
        ctx.push(deploysScreen(f, ctx, repo));
        return true;
@@ -315,6 +315,7 @@
export async function settingsPage(ctx: Ctx): Promise<Response> {
        Opens a pull that adds the next <code>waves/&lt;version&gt;.md</code>,
        listing every pull merged since the last wave. The headline and
        highlights are left as TODO for you to write.
        <a href="${base}/waves">See the waves so far</a>.
      </p>
      <div class="form-actions">${btn("Cut a wave", { variant: "primary" })}</div>
    </form>`,
@@ -0,0 +1,59 @@
/**
 * A repository's waves, as a page: `waves/*.md` on the default branch, newest
 * version first, each line linking to its file. Reading is `story/waves.ts`'s.
 *
 * Visibility is the repository's: `loadRepo` answers an outsider exactly as
 * it does for any other page of a private repository.
 */
import { repoDir } from "../../git/repos.ts";
import type { Ctx } from "../../http/context.ts";
import { readWaves } from "../../story/waves.ts";
import { loadRepo, notFoundPage, repoBase, scopeHeader } from "../chrome.ts";
import { html } from "../html.ts";
import { page } from "../layout.ts";
import { empty, listCard, row } from "../ui.ts";
import { localScope } from "../scope.ts";
// GET /:owner/:name/waves
export async function wavesPage(ctx: Ctx): Promise<Response> {
  const repo = loadRepo(ctx);
  if (!repo) return notFoundPage(ctx);
  const scope = localScope(ctx, repo);
  const branch = repo.defaultBranch;
  const entries = await readWaves(
    repoDir(ctx.app.reposRoot, repo.ownerName, repo.name),
    branch,
  );
  const fileHref = (file: string): string =>
    `${repoBase(repo)}/blob/${encodeURIComponent(branch)}/waves/${encodeURIComponent(file)}`;
  const rows = entries.map((e) =>
    e.ok
      ? row({
          href: fileHref(e.file),
          title: e.wave.headline,
          meta: html`${e.wave.version} · ${e.wave.date}`,
        })
      : row({
          href: fileHref(e.file),
          title: e.file,
          meta: html`Not a wave: ${e.reason}`,
        }),
  );
  const body = html`${scopeHeader(ctx, scope, "code", { compact: true })}
    <div class="mt">
      ${entries.length === 0
        ? empty({ title: "No waves yet", note: "This repository has no waves/ directory." })
        : listCard(rows, { head: html`<h2>Waves</h2>` })}
    </div>`;
  return page({
    ctx,
    title: `Waves · ${scope.facts.name}`,
    crumbs: scope.crumbs,
      
        sentinelcrew
        29d ago
        outdated
      
      Low: slice(0, MAX_FILES) runs on git's tree order, before the version sort. Git orders names as plain strings, so 0.10.0.md comes before 0.9.0.md. Past 300 files, the waves cut off are arbitrary and can include the newest one. Sort before truncating, or say on the page that the list was cut.
    
    palette: scope.palette,
    body,
  });
}
@@ -0,0 +1,101 @@
import { afterAll, beforeAll, describe, expect, test } from "bun:test";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { commitToBranch, createRepo } from "../src/actions/repos.ts";
import { signUp } from "../src/actions/users.ts";
import { createApp, type App as Forge } from "../src/app.ts";
import type { Repo } from "../src/core/repos.ts";
import type { User } from "../src/core/users.ts";
import { writeWave, type Wave } from "../src/story/wave.ts";
import { createForgeApp } from "../src/tui/forge.ts";
import { wavesScreen } from "../src/tui/screens/waves.ts";
import { local } from "../src/tui/screens/where.ts";
import { headlessTerminal } from "../src/tui/term/terminal.ts";
import { quietLogs } from "./helpers/globals.ts";
import { settleApp } from "./helpers/tui.ts";
quietLogs();
const wave = (version: string, date: string, headline: string): Wave => ({
  version,
  date,
  headline,
  highlights: [1, 2, 3].map((n) => ({ title: `Thing ${n}`, why: "because" })),
  pulls: [{ title: "#1 A pull", url: "https://forge.example/o/r/pulls/1" }],
});
const text = (w: Wave): string => {
  const r = writeWave(w);
  if (!r.ok) throw r.error;
  return r.value;
};
describe("waves in the terminal", () => {
  let dataDir: string;
  let forge: Forge;
  let alice: User;
  let bob: User;
  let pub: Repo;
  let priv: Repo;
  beforeAll(async () => {
    dataDir = await mkdtemp(join(tmpdir(), "forge-tui-waves-"));
    forge = createApp({ dataDir, port: 0 });
    const a = await signUp(forge, { username: "alice", email: "[email protected]", password: "a-long-passphrase" });
    const b = await signUp(forge, { username: "bob", email: "[email protected]", password: "a-long-passphrase" });
    if (!a.ok || !b.ok) throw new Error("signup failed");
    alice = a.value;
    bob = b.value;
    const p = await createRepo(forge, alice, { name: "pub", visibility: "public" });
    const q = await createRepo(forge, alice, { name: "priv", visibility: "private" });
    if (!p.ok || !q.ok) throw new Error("repo failed");
    pub = p.value;
    priv = q.value;
    const put = (repo: Repo, files: { path: string; content: string }[]) =>
      commitToBranch(forge, alice, repo, { message: "waves", files });
    await put(pub, [
      { path: "waves/0.9.0.md", content: text(wave("0.9.0", "2026-01-01", "Ninth")) },
      { path: "waves/0.10.0.md", content: text(wave("0.10.0", "2026-02-01", "Tenth")) },
      { path: "waves/broken.md", content: "no front matter\n" },
    ]);
    await put(priv, [
      { path: "waves/1.0.0.md", content: text(wave("1.0.0", "2026-03-01", "Secret launch")) },
    ]);
  });
  afterAll(async () => {
    forge.close();
    await rm(dataDir, { recursive: true, force: true });
  });
  const open = async (user: User, repo: Repo): Promise<{ text: string; stop(): void }> => {
    const terminal = headlessTerminal(120, 40);
    const { app, session } = createForgeApp(
      forge,
      { sshUsername: user.username, remoteAddress: "127.0.0.1", fingerprint: "SHA256:t", user },
      { terminal, exitHooks: false },
    );
    app.start();
    await settleApp(app);
    app.push(wavesScreen(session, app.ctx, local(session, repo)));
    await settleApp(app);
    return { text: app.screen.toText(), stop: () => app.stop() };
  };
  test("lists the web page's rows in the same order, bad files last", async () => {
    const h = await open(alice, pub);
    h.stop();
    const at = (s: string) => h.text.indexOf(s);
    expect(at("Tenth")).toBeGreaterThan(-1);
    expect(at("Tenth")).toBeLessThan(at("Ninth"));
    expect(at("Ninth")).toBeLessThan(at("broken.md"));
    expect(h.text).toContain("0.10.0");
  });
  test("a reader who cannot read the repository sees no waves", async () => {
    const h = await open(bob, priv);
    h.stop();
    expect(h.text).not.toContain("Secret launch");
    expect(h.text).toContain("No waves yet");
  });
});
@@ -0,0 +1,27 @@
import { describe, expect, test } from "bun:test";
import { byVersionDesc } from "../src/story/waves.ts";
const newer = (a: string, b: string) => {
  expect(byVersionDesc(a, b)).toBeLessThan(0);
  expect(byVersionDesc(b, a)).toBeGreaterThan(0);
};
describe("byVersionDesc", () => {
  test("compares numerically, not as strings", () => newer("0.10.0", "0.9.0"));
  test("a release beats its pre-release", () => newer("1.0.0", "1.0.0-rc.1"));
  test("pre-release identifiers compare numerically", () => {
    newer("1.0.0-rc.10", "1.0.0-rc.2");
    newer("1.0.0-rc.1.1", "1.0.0-rc.1");
  });
  test("a name that is not a version sorts after every version", () => {
    newer("0.0.1", "broken");
    newer("1.0.0-rc.1", "notes");
    expect(byVersionDesc("broken", "broken")).toBe(0);
  });
  test("the sort is total, so the cut keeps the newest", () => {
    const names = ["broken", "0.9.0", "notes", "0.10.0", "1.0.0-rc.2", "1.0.0-rc.10", "1.0.0"];
    expect(names.sort(byVersionDesc).slice(0, 4)).toEqual([
      "1.0.0", "1.0.0-rc.10", "1.0.0-rc.2", "0.10.0",
    ]);
  });
});
@@ -0,0 +1,130 @@
import { afterAll, beforeAll, describe, expect, test } from "bun:test";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { commitToBranch, createRepo } from "../src/actions/repos.ts";
import { createApp, type App } from "../src/app.ts";
import type { Repo } from "../src/core/repos.ts";
import { createSession } from "../src/core/sessions.ts";
import { createUser, type User } from "../src/core/users.ts";
import { serve, type Servers } from "../src/http/server.ts";
import { writeWave, type Wave } from "../src/story/wave.ts";
const PASSWORD = "a-good-passphrase";
const wave = (version: string, date: string, headline: string): Wave => ({
  version,
  date,
  headline,
  highlights: [1, 2, 3].map((n) => ({ title: `Thing ${n}`, why: "because" })),
  pulls: [{ title: "#1 A pull", url: "https://forge.example/o/r/pulls/1" }],
});
const text = (w: Wave): string => {
  const r = writeWave(w);
  if (!r.ok) throw r.error;
  return r.value;
};
describe("waves page", () => {
  let dataDir: string;
  let app: App;
  let servers: Servers;
  let alice: User;
  let cookie = "";
  let pub: Repo;
  let priv: Repo;
  let bare: Repo;
  const must = <T>(r: { ok: true; value: T } | { ok: false; error: unknown }): T => {
    if (!r.ok) throw new Error(JSON.stringify(r.error));
    return r.value;
  };
  const put = async (repo: Repo, files: { path: string; content: string }[]) =>
    must(await commitToBranch(app, alice, repo, { message: "waves", files }));
  const get = (path: string, withCookie = true) =>
    fetch(`${servers.url}${path}`, {
      headers: withCookie ? { cookie } : {},
    });
  beforeAll(async () => {
    dataDir = await mkdtemp(join(tmpdir(), "forge-waves-"));
    app = createApp({ dataDir, port: 0 });
    servers = await serve(app);
    alice = must(
      await createUser(app.db, {
        trusted: true,
        username: "alice",
        email: "[email protected]",
        password: PASSWORD,
        adminIfFirst: true,
      }),
    );
    cookie = `forge_session=${createSession(app.db, alice.id).token}; forge_mode=dev`;
    pub = must(await createRepo(app, alice, { name: "pub", visibility: "public" }));
    priv = must(await createRepo(app, alice, { name: "priv", visibility: "private" }));
    bare = must(await createRepo(app, alice, { name: "bare", visibility: "public" }));
    await put(bare, [{ path: "README.md", content: "hi\n" }]);
    await put(pub, [
      { path: "waves/0.9.0.md", content: text(wave("0.9.0", "2026-01-01", "Ninth")) },
      { path: "waves/0.10.0.md", content: text(wave("0.10.0", "2026-02-01", "Tenth")) },
      { path: "waves/0.2.0.md", content: text(wave("0.2.0", "2025-12-01", "<script>alert(1)</script> & Zeta")) },
      { path: "waves/broken.md", content: "no front matter here\n" },
    ]);
    await put(priv, [
      { path: "waves/1.0.0.md", content: text(wave("1.0.0", "2026-03-01", "Secret launch")) },
    ]);
  }, 60_000);
  afterAll(async () => {
    servers.stop();
    app.close();
    await rm(dataDir, { recursive: true, force: true });
  });
  test("lists newest version first, numerically", async () => {
    const res = await get("/alice/pub/waves");
    expect(res.status).toBe(200);
    const body = await res.text();
    const at = (s: string) => body.indexOf(s);
    expect(at("Tenth")).toBeGreaterThan(-1);
    expect(at("Tenth")).toBeLessThan(at("Ninth"));
    expect(at("Ninth")).toBeLessThan(at("Zeta"));
    expect(body).toContain("0.10.0");
    expect(body).toContain("2026-02-01");
    expect(body).toContain("/alice/pub/blob/main/waves/0.10.0.md");
  });
  test("a headline with markup comes out inert", async () => {
    const body = await (await get("/alice/pub/waves")).text();
    expect(body).not.toContain("<script>alert(1)</script>");
    expect(body).toContain("&lt;script&gt;alert(1)&lt;/script&gt; &amp; Zeta");
  });
  test("an unparsable file is listed with its reason and the rest still shows", async () => {
    const body = await (await get("/alice/pub/waves")).text();
    expect(body).toContain("broken.md");
    expect(body).toContain("missing front matter");
    expect(body).toContain("Tenth");
  });
  test("settings links to the list from the Cut a wave card", async () => {
    const body = await (await get("/alice/pub/settings")).text();
    expect(body).toContain('href="/alice/pub/waves"');
  });
  test("no waves/ gets the empty state", async () => {
    const res = await get("/alice/bare/waves");
    expect(res.status).toBe(200);
    expect(await res.text()).toContain("No waves yet");
  });
  test("a private repository is refused to an outsider as any other page is", async () => {
    const waves = await get("/alice/priv/waves", false);
    const other = await get("/alice/priv/branches", false);
    expect(waves.status).toBe(other.status);
    expect(waves.status).toBe(404);
    expect(await waves.text()).not.toContain("Secret launch");
    const owner = await get("/alice/priv/waves");
    expect(await owner.text()).toContain("Secret launch");
  });
});
		@@ -914,6 +914,9 @@ work here.
914	914	not already in an earlier wave. The headline and highlights are `TODO`
915	915	placeholders; no model is called. It refuses, writing nothing, when an
916	916	earlier wave does not parse (naming the file) or nothing new has merged.
	917	`/:owner/:name/waves` lists the waves on the default branch, newest version
	918	first, each linking to its file (linked from that settings card); in the
	919	terminal, `V` in a repository opens the same list.
917	920
918	921	- Accounts & access — register/sign in, personal access tokens with coarse
919	922	scopes (ro/rw/admin), public and private repositories.
		@@ -27,6 +27,8 @@ export type Exclusion = {
27	27	};
28	28
29	29	export const GATE: readonly string[] = [
	30	"test/waves-page.test.ts",
	31	"test/waves-order.test.ts",
30	32	"test/domain-drill.test.ts",
31	33	"test/conflicts.test.ts",
32	34	"test/lands-once.test.ts",
		@@ -68,6 +70,7 @@ export const GATE: readonly string[] = [
68	70	"test/protection.test.ts",
69	71	"test/tui-limbs.test.ts",
70	72	"test/tui-onyou.test.ts",
	73	"test/tui-waves.test.ts",
71	74	"test/tui-deploys.test.ts",
72	75	"test/tui-access.test.ts",
73	76	"test/tui-decider.test.ts",
		@@ -168,6 +168,7 @@ import {
168	168	branchDelete,
169	169	branchesPage,
170	170	} from "../web/pages/branches.ts";
	171	import { wavesPage } from "../web/pages/waves.ts";
171	172	import {
172	173	contributeSubmit,
173	174	deleteFilePage,
		@@ -1135,6 +1136,7 @@ export function buildRouter(): Router<Handler> {
1135	1136	// The repository's activity, for a feed reader.
1136	1137	router.add("GET", "/:owner/:name/activity.atom", activityAtom);
1137	1138	router.add("GET", "/:owner/:name/branches", branchesPage);
	1139	router.add("GET", "/:owner/:name/waves", wavesPage);
1138	1140	router.add("POST", "/:owner/:name/branches", branchCreate);
1139	1141	router.add("POST", "/:owner/:name/branches/:branch/delete", branchDelete);
1140	1142
		@@ -0,0 +1,104 @@
	1	/**
	2	* A repository's waves, read: `waves/*.md` on a branch, newest version first.
	3	* Parsing is `wave.ts`'s; a file that does not parse is listed with its
	4	* reason and breaks nothing. Both doors (the page and the terminal) read
	5	* through here; each applies its own visibility gate before calling.
	6	*/
	7
	8	import { readerFor, listTree } from "../git/read.ts";
	9	import { parseWave, type Wave } from "./wave.ts";
	10
	11	/** A page, not an archive: more files than this are not read. */
	12	const MAX_FILES = 300;
	13	/** A wave is a few hundred lines; a larger file is not one. */
	14	const MAX_BYTES = 256 * 1024;
	15
	16	export type WaveEntry =
	17	\| { ok: true; file: string; wave: Wave }
	18	\| { ok: false; file: string; reason: string };
	19
	20	const VERSION = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?$/;
	21
		sentinelcrew 29d ago outdated `"broken".split(".").map(Number)` gives `[NaN]`, so the comparator returns NaN for any non-version file name. Array.sort needs a consistent comparator, and this sort runs before `slice(0, MAX_FILES)`, so the cut can drop the newest waves. Treat a non-numeric name as sorting after every version.
	22	type Version = { core: number[]; pre: string[] };
	23
	24	const parse = (s: string): Version \| null => {
	25	const m = VERSION.exec(s);
	26	if (!m) return null;
	27	return {
	28	core: [Number(m[1]), Number(m[2] ?? 0), Number(m[3] ?? 0)],
	29	pre: m[4] === undefined ? [] : m[4].split("."),
	30	};
	31	};
	32
	33	const DIGITS = /^\d+$/;
	34
		sentinelcrew 29d ago outdated Pre-release tie-break by string: `1.0.0-rc.2` sorts ahead of `1.0.0-rc.10`. Compare identifiers dot by dot, numerically when both are digits (semver §11), and unit-test this function directly.
	35	/** Semver §11 for one pre-release identifier: numbers by value, below text. */
	36	function identifier(a: string, b: string): number {
	37	const an = DIGITS.test(a);
	38	const bn = DIGITS.test(b);
	39	if (an && bn) return Number(a) - Number(b);
	40	if (an !== bn) return an ? -1 : 1;
	41	return a < b ? -1 : a > b ? 1 : 0;
	42	}
	43
	44	/**
	45	* Higher version first; a release beats its own pre-release, pre-release
	46	* identifiers compare dot by dot. A name that is not a version sorts after
	47	* every version, and those among themselves by name, so the order is total.
	48	*/
	49	export function byVersionDesc(a: string, b: string): number {
	50	const x = parse(a);
	51	const y = parse(b);
	52	if (!x \|\| !y) return x ? -1 : y ? 1 : a < b ? -1 : a > b ? 1 : 0;
	53	for (let i = 0; i < 3; i++) {
	54	const d = y.core[i]! - x.core[i]!;
	55	if (d !== 0) return d;
	56	}
	57	if (!x.pre.length \|\| !y.pre.length) return x.pre.length ? 1 : y.pre.length ? -1 : 0;
	58	for (let i = 0; i < Math.min(x.pre.length, y.pre.length); i++) {
	59	const d = identifier(y.pre[i]!, x.pre[i]!);
	60	if (d !== 0) return d;
	61	}
	62	return y.pre.length - x.pre.length;
	63	}
	64
	65	/** Every wave file on `branch`, parsed; good ones newest first, then the bad. */
	66	export async function readWaves(
	67	dir: string,
	68	branch: string,
	69	): Promise<WaveEntry[]> {
	70	const tree = await listTree(dir, branch, "waves");
	71	if (!tree.ok) return [];
	72	const files = tree.value
	73	.filter((e) => e.type === "blob" && e.name.endsWith(".md"))
	74	// Git orders names as strings (`0.10.0` before `0.9.0`); the cut is made
	75	// on version order so the newest waves are the ones kept.
	76	.sort((x, y) => byVersionDesc(x.name.slice(0, -3), y.name.slice(0, -3)))
	77	.slice(0, MAX_FILES);
	78	const reader = readerFor(dir);
	79	const out: WaveEntry[] = [];
	80	for (const f of files) {
	81	const path = `waves/${f.name}`;
	82	if (f.size > MAX_BYTES) {
	83	out.push({ ok: false, file: f.name, reason: `${path}: file is too large` });
	84	continue;
	85	}
	86	const obj = await reader.object(f.oid);
	87	if (!obj.ok) {
	88	out.push({ ok: false, file: f.name, reason: `${path}: unreadable` });
	89	continue;
	90	}
	91	const text = new TextDecoder().decode(obj.value.body);
	92	const parsed = parseWave(path, text);
	93	out.push(
	94	parsed.ok
	95	? { ok: true, file: f.name, wave: parsed.value }
	96	: { ok: false, file: f.name, reason: parsed.error.message },
	97	);
	98	}
	99	const good = out.flatMap((e) => (e.ok ? [e] : []));
	100	const bad = out.flatMap((e) => (e.ok ? [] : [e]));
	101	good.sort((a, b) => byVersionDesc(a.wave.version, b.wave.version));
	102	return [...good, ...bad];
	103	}
	104
		@@ -0,0 +1,90 @@
	1	/**
	2	* A repository's waves: the same rows, in the same order, as the web page,
	3	* read through `story/waves.ts`. Local repositories only — a live browse of
	4	* another forge has no `waves/` we can read here, and says so.
	5	*/
	6
	7	import { canRead } from "../../core/repos.ts";
	8	import { readWaves, type WaveEntry } from "../../story/waves.ts";
	9	import type { RepoSource } from "../../view/source.ts";
	10	import type { Ctx, Screen } from "../app/app.ts";
	11	import { binding } from "../app/keys.ts";
	12	import { style } from "../term/style.ts";
	13	import { truncate } from "../term/width.ts";
	14	import { fill, len, split } from "../ui/layout.ts";
	15	import { emptyState } from "../ui/widgets.ts";
	16	import type { Session } from "../session.ts";
	17	import { ListState, drawList, plural, runAsync } from "./common.ts";
	18	import { localRepo, sourceName, whereRows, whereStrip } from "./where.ts";
	19
	20	/** One line per wave, as the screen draws it. */
	21	export function waveRows(entries: WaveEntry[]) {
	22	return entries.map((e) =>
	23	e.ok
	24	? {
	25	title: e.wave.headline,
	26	secondary: "",
	27	meta: `${e.wave.version} ${e.wave.date}`,
	28	}
	29	: { title: e.file, secondary: `Not a wave: ${e.reason}`, meta: "" },
	30	);
	31	}
	32
	33	export function wavesScreen(f: Session, ctx: Ctx, src: RepoSource): Screen {
	34	const repo = localRepo(src);
	35	let entries: WaveEntry[] = [];
	36	let loaded = false;
	37	const state = new ListState();
	38
	39	const reload = async (): Promise<void> => {
	40	// The web's gate, not a weaker one: whoever reaches this screen, a
	41	// repository they cannot read has no waves to show.
	42	entries =
	43	repo !== undefined && canRead(f.db, repo, f.user)
	44	? await readWaves(f.dir(repo), repo.defaultBranch)
	45	: [];
	46	loaded = true;
	47	ctx.invalidate();
	48	};
	49
	50	return {
	51	title: "Waves",
	52	keys: [binding(["j", "k"], "move"), binding(["r"], "refresh")],
	53	load: reload,
	54	render(area, s) {
	55	const c = ctx.theme.c;
	56	const [strip, head, body] = split(area, "v", [
	57	len(whereRows(src)),
	58	len(1),
	59	fill(1),
	60	]);
	61	whereStrip(s, strip!, c, f, src);
	62	s.text(
	63	head!.x,
	64	head!.y,
	65	truncate(
	66	`${sourceName(src)} · ${plural(entries.length, "wave")}`,
	67	head!.w,
	68	),
	69	style(c.mutedFg, c.bg),
	70	head!.x + head!.w,
	71	);
	72	if (entries.length === 0) {
	73	emptyState(s, body!, c, {
	74	title: loaded ? "No waves yet" : "Reading…",
	75	body: loaded ? "This repository has no waves/ directory." : "",
		sentinelcrew 29d ago For a live browse of another forge (`repo === undefined`), this says the repository has no `waves/` directory. That is not known, and the header comment promises the screen "says so" instead. Tracked in #2076, together with Enter opening the wave file.
	76	});
	77	return;
	78	}
	79	drawList(s, body!, c, state, waveRows(entries));
	80	},
	81	key(e) {
	82	if (state.key(e, entries.length)) return true;
	83	if (e.key === "r") {
	84	runAsync(ctx, reload);
	85	return true;
	86	}
	87	return false;
	88	},
	89	};
	90	}
		@@ -118,6 +118,7 @@ import { liveBindings, liveKey } from "./mirror.ts";
118	118	import { forkScreen } from "./newrepo.ts";
119	119	import { pullScreen } from "./pull.ts";
120	120	import { branchesScreen } from "./refs.ts";
	121	import { wavesScreen } from "./waves.ts";
121	122	import {
122	123	hostOf,
123	124	knownDefaultRef,
		@@ -1287,6 +1288,7 @@ export function workspaceScreen(
1287	1288	binding(["y"], "copy path"),
1288	1289	binding(["i", "p", "C"], "issues / pulls / commits"),
1289	1290	binding(["I"], "about this repository"),
	1291	binding(["V"], "waves"),
1290	1292	...(repo === undefined ? [] : [binding(["d"], "production deploys")]),
1291	1293	...(repo !== undefined && admin()
1292	1294	? [binding(["R"], `decisions by ${(getRepoById(f.db, repo.id) ?? repo).decisionsBy} (cycle)`)]
		@@ -1606,6 +1608,10 @@ export function workspaceScreen(
1606	1608	ctx.push(commitsScreen(f, ctx, src, ref));
1607	1609	return true;
1608	1610	}
	1611	if (plain && e.key === "V") {
	1612	ctx.push(wavesScreen(f, ctx, src));
	1613	return true;
	1614	}
1609	1615	if (plain && e.key === "d" && repo !== undefined) {
1610	1616	ctx.push(deploysScreen(f, ctx, repo));
1611	1617	return true;
		@@ -315,6 +315,7 @@ export async function settingsPage(ctx: Ctx): Promise<Response> {
315	315	Opens a pull that adds the next <code>waves/<version>.md</code>,
316	316	listing every pull merged since the last wave. The headline and
317	317	highlights are left as TODO for you to write.
	318	<a href="${base}/waves">See the waves so far</a>.
318	319	</p>
319	320	<div class="form-actions">${btn("Cut a wave", { variant: "primary" })}</div>
320	321	</form>`,
		@@ -0,0 +1,59 @@
	1	/**
	2	* A repository's waves, as a page: `waves/*.md` on the default branch, newest
	3	* version first, each line linking to its file. Reading is `story/waves.ts`'s.
	4	*
	5	* Visibility is the repository's: `loadRepo` answers an outsider exactly as
	6	* it does for any other page of a private repository.
	7	*/
	8
	9	import { repoDir } from "../../git/repos.ts";
	10	import type { Ctx } from "../../http/context.ts";
	11	import { readWaves } from "../../story/waves.ts";
	12	import { loadRepo, notFoundPage, repoBase, scopeHeader } from "../chrome.ts";
	13	import { html } from "../html.ts";
	14	import { page } from "../layout.ts";
	15	import { empty, listCard, row } from "../ui.ts";
	16	import { localScope } from "../scope.ts";
	17
	18	// GET /:owner/:name/waves
	19	export async function wavesPage(ctx: Ctx): Promise<Response> {
	20	const repo = loadRepo(ctx);
	21	if (!repo) return notFoundPage(ctx);
	22	const scope = localScope(ctx, repo);
	23	const branch = repo.defaultBranch;
	24	const entries = await readWaves(
	25	repoDir(ctx.app.reposRoot, repo.ownerName, repo.name),
	26	branch,
	27	);
	28	const fileHref = (file: string): string =>
	29	`${repoBase(repo)}/blob/${encodeURIComponent(branch)}/waves/${encodeURIComponent(file)}`;
	30
	31	const rows = entries.map((e) =>
	32	e.ok
	33	? row({
	34	href: fileHref(e.file),
	35	title: e.wave.headline,
	36	meta: html`${e.wave.version} · ${e.wave.date}`,
	37	})
	38	: row({
	39	href: fileHref(e.file),
	40	title: e.file,
	41	meta: html`Not a wave: ${e.reason}`,
	42	}),
	43	);
	44
	45	const body = html`${scopeHeader(ctx, scope, "code", { compact: true })}
	46	<div class="mt">
	47	${entries.length === 0
	48	? empty({ title: "No waves yet", note: "This repository has no waves/ directory." })
	49	: listCard(rows, { head: html`<h2>Waves</h2>` })}
	50	</div>`;
	51
	52	return page({
	53	ctx,
	54	title: `Waves · ${scope.facts.name}`,
	55	crumbs: scope.crumbs,
		sentinelcrew 29d ago outdated Low: `slice(0, MAX_FILES)` runs on git's tree order, before the version sort. Git orders names as plain strings, so `0.10.0.md` comes before `0.9.0.md`. Past 300 files, the waves cut off are arbitrary and can include the newest one. Sort before truncating, or say on the page that the list was cut.
	56	palette: scope.palette,
	57	body,
	58	});
	59	}
		@@ -0,0 +1,101 @@
	1	import { afterAll, beforeAll, describe, expect, test } from "bun:test";
	2	import { mkdtemp, rm } from "node:fs/promises";
	3	import { tmpdir } from "node:os";
	4	import { join } from "node:path";
	5	import { commitToBranch, createRepo } from "../src/actions/repos.ts";
	6	import { signUp } from "../src/actions/users.ts";
	7	import { createApp, type App as Forge } from "../src/app.ts";
	8	import type { Repo } from "../src/core/repos.ts";
	9	import type { User } from "../src/core/users.ts";
	10	import { writeWave, type Wave } from "../src/story/wave.ts";
	11	import { createForgeApp } from "../src/tui/forge.ts";
	12	import { wavesScreen } from "../src/tui/screens/waves.ts";
	13	import { local } from "../src/tui/screens/where.ts";
	14	import { headlessTerminal } from "../src/tui/term/terminal.ts";
	15	import { quietLogs } from "./helpers/globals.ts";
	16	import { settleApp } from "./helpers/tui.ts";
	17
	18	quietLogs();
	19
	20	const wave = (version: string, date: string, headline: string): Wave => ({
	21	version,
	22	date,
	23	headline,
	24	highlights: [1, 2, 3].map((n) => ({ title: `Thing ${n}`, why: "because" })),
	25	pulls: [{ title: "#1 A pull", url: "https://forge.example/o/r/pulls/1" }],
	26	});
	27	const text = (w: Wave): string => {
	28	const r = writeWave(w);
	29	if (!r.ok) throw r.error;
	30	return r.value;
	31	};
	32
	33	describe("waves in the terminal", () => {
	34	let dataDir: string;
	35	let forge: Forge;
	36	let alice: User;
	37	let bob: User;
	38	let pub: Repo;
	39	let priv: Repo;
	40
	41	beforeAll(async () => {
	42	dataDir = await mkdtemp(join(tmpdir(), "forge-tui-waves-"));
	43	forge = createApp({ dataDir, port: 0 });
	44	const a = await signUp(forge, { username: "alice", email: "[email protected]", password: "a-long-passphrase" });
	45	const b = await signUp(forge, { username: "bob", email: "[email protected]", password: "a-long-passphrase" });
	46	if (!a.ok \|\| !b.ok) throw new Error("signup failed");
	47	alice = a.value;
	48	bob = b.value;
	49	const p = await createRepo(forge, alice, { name: "pub", visibility: "public" });
	50	const q = await createRepo(forge, alice, { name: "priv", visibility: "private" });
	51	if (!p.ok \|\| !q.ok) throw new Error("repo failed");
	52	pub = p.value;
	53	priv = q.value;
	54	const put = (repo: Repo, files: { path: string; content: string }[]) =>
	55	commitToBranch(forge, alice, repo, { message: "waves", files });
	56	await put(pub, [
	57	{ path: "waves/0.9.0.md", content: text(wave("0.9.0", "2026-01-01", "Ninth")) },
	58	{ path: "waves/0.10.0.md", content: text(wave("0.10.0", "2026-02-01", "Tenth")) },
	59	{ path: "waves/broken.md", content: "no front matter\n" },
	60	]);
	61	await put(priv, [
	62	{ path: "waves/1.0.0.md", content: text(wave("1.0.0", "2026-03-01", "Secret launch")) },
	63	]);
	64	});
	65
	66	afterAll(async () => {
	67	forge.close();
	68	await rm(dataDir, { recursive: true, force: true });
	69	});
	70
	71	const open = async (user: User, repo: Repo): Promise<{ text: string; stop(): void }> => {
	72	const terminal = headlessTerminal(120, 40);
	73	const { app, session } = createForgeApp(
	74	forge,
	75	{ sshUsername: user.username, remoteAddress: "127.0.0.1", fingerprint: "SHA256:t", user },
	76	{ terminal, exitHooks: false },
	77	);
	78	app.start();
	79	await settleApp(app);
	80	app.push(wavesScreen(session, app.ctx, local(session, repo)));
	81	await settleApp(app);
	82	return { text: app.screen.toText(), stop: () => app.stop() };
	83	};
	84
	85	test("lists the web page's rows in the same order, bad files last", async () => {
	86	const h = await open(alice, pub);
	87	h.stop();
	88	const at = (s: string) => h.text.indexOf(s);
	89	expect(at("Tenth")).toBeGreaterThan(-1);
	90	expect(at("Tenth")).toBeLessThan(at("Ninth"));
	91	expect(at("Ninth")).toBeLessThan(at("broken.md"));
	92	expect(h.text).toContain("0.10.0");
	93	});
	94
	95	test("a reader who cannot read the repository sees no waves", async () => {
	96	const h = await open(bob, priv);
	97	h.stop();
	98	expect(h.text).not.toContain("Secret launch");
	99	expect(h.text).toContain("No waves yet");
	100	});
	101	});
		@@ -0,0 +1,27 @@
	1	import { describe, expect, test } from "bun:test";
	2	import { byVersionDesc } from "../src/story/waves.ts";
	3
	4	const newer = (a: string, b: string) => {
	5	expect(byVersionDesc(a, b)).toBeLessThan(0);
	6	expect(byVersionDesc(b, a)).toBeGreaterThan(0);
	7	};
	8
	9	describe("byVersionDesc", () => {
	10	test("compares numerically, not as strings", () => newer("0.10.0", "0.9.0"));
	11	test("a release beats its pre-release", () => newer("1.0.0", "1.0.0-rc.1"));
	12	test("pre-release identifiers compare numerically", () => {
	13	newer("1.0.0-rc.10", "1.0.0-rc.2");
	14	newer("1.0.0-rc.1.1", "1.0.0-rc.1");
	15	});
	16	test("a name that is not a version sorts after every version", () => {
	17	newer("0.0.1", "broken");
	18	newer("1.0.0-rc.1", "notes");
	19	expect(byVersionDesc("broken", "broken")).toBe(0);
	20	});
	21	test("the sort is total, so the cut keeps the newest", () => {
	22	const names = ["broken", "0.9.0", "notes", "0.10.0", "1.0.0-rc.2", "1.0.0-rc.10", "1.0.0"];
	23	expect(names.sort(byVersionDesc).slice(0, 4)).toEqual([
	24	"1.0.0", "1.0.0-rc.10", "1.0.0-rc.2", "0.10.0",
	25	]);
	26	});
	27	});