Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,8 @@ install; an older one of the same major fails it, saying so.
The site and the blog (blog.spinbox.dev, where the reasons and the failures live) describe the same
project, and hold it to the same rules. The site says what Spinbox is and how to use it; the blog
says why it is built that way and what went wrong. Link to a post where a page would explain a
reason, instead of restating it.
reason, instead of restating it: `[why](<post:the-slug>)`, a slug of `src/data/posts.json` (the
published posts; a draft's slug is private and goes nowhere here).

- **What a workspace is comes first; the sandbox follows from it.** A workspace is a whole machine,
built from parts Linux and QEMU already have, made for a person to work in. That is what makes it
Expand Down
6 changes: 6 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,12 @@ that is not one task (`taskgate`).
build points it at the row's area on the status page (`src/lib/feature-links.mjs`) and fails on
a row the board does not have; `task reference:check` also fails on a row that is not built.
The board is `src/data/features.json`, written by `task reference`.
- **Why it is built that way is the blog's**, and a page links the post that says it:
`[why](<post:the-slug>)`. The build points it at the post on blog.spinbox.dev
(`src/lib/post-links.mjs`) and fails on a slug the blog has not published:
`src/data/posts.json`, which `task posts` (`tools/posts`) writes from the blog's feed, and the
daily sync rewrites. A draft is private, so its slug goes nowhere here. The build reads the file,
not the feed; a feed that cannot be read keeps the file as it is.
- **What Spinbox does and no page says** is `tools/refgen/unsaid.txt`: the built rows of the board
that no hand-written page links, one a line. It may shrink. `task reference:check` fails on a
built row that is neither linked nor listed - a feature spin ships reaches a page, or is written
Expand Down
15 changes: 13 additions & 2 deletions Taskfile.yml
Original file line number Diff line number Diff line change
Expand Up @@ -31,10 +31,11 @@ tasks:
- go run ./tools/sources spin spin-terraform-aws brand

sources:bump:
desc: Move the pins to the newest releases - spin only to one that holds the commit pinned, brand to its main - and fetch them, and rewrite the prices. Then task reference.
desc: Move the pins to the newest releases - spin only to one that holds the commit pinned, brand to its main - and fetch them, and rewrite the prices and the blog's posts. Then task reference.
cmds:
- go run ./tools/sources -bump spin spin-terraform-aws brand
- task: pricing
- task: posts

# The cost page's numbers: generated, dated, and refused by reference:check once they are a
# month old or of other machines than the module starts, so a figure on the page is never
Expand All @@ -44,6 +45,14 @@ tasks:
cmds:
- go run ./tools/pricing -terraform {{.TERRAFORM}} -out src/data/pricing.json

# The posts a page may link, [why](<post:the-slug>): what the blog's feed lists, so a draft's
# slug never reaches this public site. The build reads the file and never the feed, and a feed
# that cannot be read keeps it. The sync rewrites it every day.
posts:
desc: Write src/data/posts.json - the posts the blog has published, from its feed (tools/posts).
cmds:
- go run ./tools/posts -out src/data/posts.json

sync:pr:
desc: Commit what sources:bump and reference changed to branch sync/sources as the sync App (SYNC_TOKEN, BOT its login), and open its one pull request or update it. sync.yml runs it.
cmds:
Expand Down Expand Up @@ -102,7 +111,7 @@ tasks:
- go run ./tools/linkcheck -external dist

gate:
desc: What CI runs - every install through the firewall and every workflow step a task, the install, vet and the tools' tests, the reference against the public sources, the build, and every link.
desc: What CI runs - every install through the firewall and every workflow step a task, the install, vet and the tools' tests and the build's, the reference against the public sources, the build, and every link.
cmds:
- sfw check
# The Task running this one, which taskgate asks for the task names a workflow step runs.
Expand All @@ -113,6 +122,8 @@ tasks:
- task: install
- go vet ./...
- go test ./...
# The few rules the build keeps in JavaScript, with node's own runner: no dependency.
- node --test 'src/lib/*.test.mjs'
- task: reference:public
- task: build
- task: links
Expand Down
3 changes: 2 additions & 1 deletion astro.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ import starlight from '@astrojs/starlight';
import { defineConfig } from 'astro/config';
import { rehypeBaseLinks } from './src/lib/base-links.mjs';
import { rehypeFeatureLinks } from './src/lib/feature-links.mjs';
import { rehypePostLinks } from './src/lib/post-links.mjs';
import starlightImageZoom from 'starlight-image-zoom';
import starlightSidebarTopics from 'starlight-sidebar-topics';
import { sidebarTopics } from './src/lib/nav.mjs';
Expand All @@ -16,7 +17,7 @@ export default defineConfig({
site,
base,
trailingSlash: 'always',
markdown: { rehypePlugins: [rehypeFeatureLinks, [rehypeBaseLinks, { base }]] },
markdown: { rehypePlugins: [rehypeFeatureLinks, rehypePostLinks, [rehypeBaseLinks, { base }]] },
integrations: [
starlight({
title: 'Spinbox',
Expand Down
5 changes: 5 additions & 0 deletions src/data/posts.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"generated": "2026-11-19",
"blog": "https://blog.spinbox.dev",
"posts": []
}
3 changes: 3 additions & 0 deletions src/lib/pages.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ import { value } from './constants';
import { experimentalMarkdown } from './experimental';
import { featureHref } from './feature-links.mjs';
import { nav } from './nav.mjs';
import { postHref } from './post-links.mjs';
import figures from '../data/figures.json';
import { output } from './output';
import { generated, published, scenariosMarkdown } from './pricing';
Expand Down Expand Up @@ -129,6 +130,8 @@ export function toMarkdown(d: Doc, base: string): string {
// The target is in angle brackets, so a row's name may hold a parenthesis; a < or > of the name is
// written percent-encoded, as in any link.
body = body.replace(/\]\(<feature:([^>]+)>\)/g, (_, name: string) => `](${featureHref(decodeURIComponent(name)).href})`);
// A reason's link to the blog is the post's address there.
body = body.replace(/\]\(<post:([^>]+)>\)/g, (_, slug: string) => `](${postHref(slug).href})`);
body = links(body, base);
body = body.replace(/\n{3,}/g, '\n\n');
untranslated(d, body);
Expand Down
25 changes: 25 additions & 0 deletions src/lib/post-links.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
// A page that would explain why Spinbox is built a way links the blog post that does instead:
// [why](<post:the-slug>). This points it at the post on the blog, with its title as the link's,
// and fails the build on a slug the blog has not published: src/data/posts.json, which `task
// posts` writes from the blog's feed. A draft is private, and its slug may still change.
import { visit } from 'unist-util-visit';
import record from '../data/posts.json' with { type: 'json' };

/** The blog's address of a published post: slug, as a page writes it; record, posts.json. */
export function postHref(slug, { blog, posts } = record) {
const post = posts.find((p) => p.slug === slug);
if (!post) throw new Error(`post: the blog has published no post ${JSON.stringify(slug)} (src/data/posts.json; task posts reads the feed)`);
return { href: `${blog}/posts/${slug}/`, post };
}

export function rehypePostLinks() {
return (tree) => {
visit(tree, 'element', (node) => {
const href = node.tagName === 'a' ? node.properties?.href : undefined;
if (typeof href !== 'string' || !href.startsWith('post:')) return;
const { href: to, post } = postHref(href.slice('post:'.length));
node.properties.href = to;
node.properties.title = post.title;
});
};
}
25 changes: 25 additions & 0 deletions src/lib/post-links.test.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
// node --test: a post link resolves to the post on the blog, and a slug the blog has not
// published fails. The posts here are made up; posts.json holds the blog's.
import assert from 'node:assert/strict';
import { test } from 'node:test';
import published from '../data/posts.json' with { type: 'json' };
import { postHref } from './post-links.mjs';

const record = { blog: 'https://blog.example', posts: [{ slug: 'a-post', title: 'A post', date: '2026-11-24' }] };

test('a published post is its address on the blog', () => {
assert.deepEqual(postHref('a-post', record), { href: 'https://blog.example/posts/a-post/', post: record.posts[0] });
});

for (const [name, slug] of [
['a slug the blog has not published', 'a-draft'],
['a slug written with its path', '/posts/a-post/'],
['no slug', ''],
]) {
test(`${name} fails`, () => assert.throws(() => postHref(slug, record), /has published no post/));
}

test('posts.json is a record the links can read', () => {
assert.match(published.blog, /^https:\/\/[^/]+$/);
for (const p of published.posts) assert.equal(postHref(p.slug).href, `${published.blog}/posts/${p.slug}/`);
});
132 changes: 132 additions & 0 deletions tools/posts/posts.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,132 @@
// Command posts writes src/data/posts.json: the posts the blog has published, read from its
// public feed. A page links a post as [why](<post:the-slug>), and the build fails on a slug this
// list does not have (src/lib/post-links.mjs), so a page never links a post that is still a
// draft, nor one renamed or gone. The build reads the file, never the feed: it needs no network.
//
// A feed that cannot be read - the blog not live yet, or down for the day - keeps the file as it
// is, and writes one with no posts where there is none: the posts already linked stay linkable,
// and nothing is linkable that was not read.
package main

import (
"encoding/json"
"encoding/xml"
"flag"
"fmt"
"io"
"net/http"
"os"
"regexp"
"sort"
"strings"
"time"
)

// Record is src/data/posts.json.
type Record struct {
// Generated is the day the feed was last read, UTC; empty until it first is.
Generated string `json:"generated"`
// Blog is the blog's address: a post is at Blog + /posts/<slug>/.
Blog string `json:"blog"`
Posts []Post `json:"posts"`
}

// Post is one published post, the oldest first.
type Post struct {
Slug string `json:"slug"`
Title string `json:"title"`
Date string `json:"date"`
}

func main() {
if err := run(os.Args[1:], os.Stdout); err != nil {
fmt.Fprintln(os.Stderr, "posts:", err)
os.Exit(1)
}
}

func run(args []string, stdout io.Writer) error {
fs := flag.NewFlagSet("posts", flag.ContinueOnError)
blog := fs.String("blog", "https://blog.spinbox.dev", "the blog's address; its feed is /rss.xml")
out := fs.String("out", "src/data/posts.json", "the record")
if err := fs.Parse(args); err != nil {
return err
}
*blog = strings.TrimSuffix(*blog, "/")
feed, err := fetch(*blog + "/rss.xml")
if err != nil {
fmt.Fprintf(stdout, "posts: %v; %s kept as it is\n", err, *out)
if _, statErr := os.Stat(*out); statErr == nil {
return nil
}
return write(*out, Record{Blog: *blog, Posts: []Post{}})
}
posts, err := parse(feed, *blog)
if err != nil {
return err
}
if err := write(*out, Record{Generated: time.Now().UTC().Format(time.DateOnly), Blog: *blog, Posts: posts}); err != nil {
return err
}
fmt.Fprintf(stdout, "posts: %d published\n", len(posts))
return nil
}

// fetch reads the feed. Any failure to reach it is an error the caller keeps the file over; what
// it says once read is parse's to refuse.
func fetch(url string) ([]byte, error) {
c := &http.Client{Timeout: 30 * time.Second}
resp, err := c.Get(url) //nolint:noctx // a command's one request
if err != nil {
return nil, fmt.Errorf("the feed cannot be read: %w", err)
}
defer resp.Body.Close()
if resp.StatusCode != http.StatusOK {
return nil, fmt.Errorf("the feed cannot be read: %s answered %s", url, resp.Status)
}
return io.ReadAll(resp.Body)
}

// postPath is a post's address on the blog, as the feed links it: /posts/<slug>/.
var postPath = regexp.MustCompile(`^/posts/([a-z0-9-]+)/$`)

// parse reads the feed's items as the blog writes them (src/pages/rss.xml.ts there): a link to
// the post, its title and its date. An item that is not a post of the blog's fails: the feed's
// shape changed, and a list read from it wrong would pass links it should not. A feed with no
// items is the blog before its first post: a list nothing may link.
func parse(feed []byte, blog string) ([]Post, error) {
var rss struct {
Items []struct {
Title string `xml:"title"`
Link string `xml:"link"`
PubDate string `xml:"pubDate"`
} `xml:"channel>item"`
}
if err := xml.Unmarshal(feed, &rss); err != nil {
return nil, fmt.Errorf("the feed: %w", err)
}
posts := []Post{}
for _, it := range rss.Items {
m := postPath.FindStringSubmatch(strings.TrimPrefix(it.Link, blog))
if m == nil || !strings.HasPrefix(it.Link, blog+"/") {
return nil, fmt.Errorf("the feed links %q, which is no post of %s", it.Link, blog)
}
date, err := time.Parse(time.RFC1123, it.PubDate)
if err != nil {
if date, err = time.Parse(time.RFC1123Z, it.PubDate); err != nil {
return nil, fmt.Errorf("the feed dates %s %q: %w", m[1], it.PubDate, err)
}
}
posts = append(posts, Post{Slug: m[1], Title: it.Title, Date: date.UTC().Format(time.DateOnly)})
}
sort.SliceStable(posts, func(i, j int) bool { return posts[i].Date < posts[j].Date })
return posts, nil
}

func write(path string, r Record) error {
b, err := json.MarshalIndent(r, "", "\t")
if err != nil {
return err
}
return os.WriteFile(path, append(b, '\n'), 0o644) //nolint:gosec // the site's data file
}
Loading