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
2 changes: 1 addition & 1 deletion PRODUCT.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,7 @@ in REST:ACT the API's clients deploy it, it runs as each caller, and it is charg

## Evidence on Hand

- The draft and its companion documents (presentation verbs, registries), rendered under `/spec/`.
- The draft and its companion documents (the extension drafts, registries), rendered under `/spec/`.
- Interactive explanations: `AnatomyDemo.astro` (four requests against `notes/42`), `ResolutionWalk.astro`.
- Real behaviour from restactd: status codes 408/429/507, default limits, the `/.well-known/restact` document,
verbatim shell sessions.
Expand Down
7 changes: 4 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,8 @@ the hub, the page descriptions) is still checked. Meta descriptions are always c

## The specification pages

`/spec/`, `/spec/draft/`, `/spec/presentation-verbs/` and `/spec/registries/` are rendered at build
`/spec/`, `/spec/draft/`, the extension drafts (`/spec/objects/`, `/spec/events/`, `/spec/delegation/`,
`/spec/connectors/`, `/spec/mcp/`, `/spec/http-verbs/` and `/spec/presentation-verbs/`) and `/spec/registries/` are rendered at build
time from copies of the sources in `stackumi/restact` (the specification repository), committed
under `src/content/spec/` (the Cloudflare build needs no sibling checkout).
`SOURCE.json` there records the source commit. When the specification changes, a person runs
Expand All @@ -43,7 +44,7 @@ corepack pnpm sync:spec [path-to-spec-checkout] # default ../restact
corepack pnpm verify
```

and commits the result. The sync vendors both drafts (the protocol draft and the presentation draft) and keeps only the `ins:` line of each draft's `author:` list (any
and commits the result. The sync vendors all eight drafts (the protocol draft and the seven extension drafts) and keeps only the `ins:` line of each draft's `author:` list (any
other key there is dropped), stops with an error if a draft has no front matter, and scans every
copied file for an email address, deleting its output and failing if it finds one. No address
enters this repository. `src/lib/specmd.ts` turns the kramdown-rfc drafts and the plain
Expand Down Expand Up @@ -83,7 +84,7 @@ the site keeps its own.
| `src/layouts/Docs.astro` | docs page: side nav, article, on-this-page list, prev/next |
| `src/layouts/MdPage.astro` | maps MDX frontmatter onto `Docs.astro` |
| `src/components/` | Shell: Header, Tagline, ThemeToggle, Footer. Building blocks: CodeBlock, Tabs, Callout, MethodTag, InRestactd, ReaderGroups, SpecBody, SpecSideNav. Figures and demos: AnatomyDemo, Venn, BudgetFigure, UiMock, UiDocumentDemo, NodeFamilies, ResolutionWalk |
| `src/pages/spec/` | the specification hub, the draft, presentation verbs and registries pages |
| `src/pages/spec/` | the specification hub, the draft, the extension drafts and registries pages |
| `scripts/` | `sync-spec.mjs` (vendor the specification sources), `sync-docs.mjs` (vendor the restactd docs), `check-site.mjs` (content checks), `vendored.mjs` (their shared scans) |
| `src/lib/term.ts` | markup helper for hand-coloured terminal and JSON blocks |
| `src/lib/shiki-theme.mjs` | the highlighting theme, built from the CSS tokens |
Expand Down
10 changes: 5 additions & 5 deletions scripts/check-site.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@
// their own 404 page and agree with INDEXABLE on noindex; the page rules above skip them
import { readFileSync, statSync, existsSync } from 'node:fs';
import { join, relative } from 'node:path';
import { EMAIL, FORBIDDEN, scanText, treeHash, walk } from './vendored.mjs';
import { FORBIDDEN, findEmail, scanText, treeHash, walk } from './vendored.mjs';

const DIST = new URL('../dist/', import.meta.url).pathname;
const CONFIG = new URL('../src/site.config.ts', import.meta.url).pathname;
Expand Down Expand Up @@ -61,8 +61,8 @@ const SPEC_SRC = new URL('../src/content/spec/', import.meta.url).pathname;
if (existsSync(SPEC_SRC)) {
for (const f of walk(SPEC_SRC)) {
if (!f.endsWith('.md')) continue;
const m = readFileSync(f, 'utf8').match(EMAIL);
if (m) err(relative(SPEC_SRC, f), `email address "${m[0]}" in a vendored specification file`);
const m = findEmail(readFileSync(f, 'utf8'));
if (m) err(relative(SPEC_SRC, f), `email address "${m}" in a vendored specification file`);
}
}

Expand Down Expand Up @@ -106,8 +106,8 @@ for (const file of pages) {
if (m) err(page, `banned wording "${m[0]}"`);
}
// (b) emails, anywhere in the markup (scripts and styles excluded)
const em = noScripts.match(EMAIL);
if (em) err(page, `email address "${em[0]}"`);
const em = findEmail(noScripts);
if (em) err(page, `email address "${em}"`);
// (c) forbidden names and hosts, anywhere including code
for (const [re, label] of FORBIDDEN) if (re.test(noScripts)) err(page, `contains ${label}`);
// (d) noindex while not indexable
Expand Down
23 changes: 13 additions & 10 deletions scripts/sync-spec.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -4,21 +4,25 @@
//
// corepack pnpm sync:spec [path-to-spec-checkout] (default: ../restact)
//
// The vendored copies are not edited, with one exception: each draft's front matter (the protocol
// draft and the presentation draft) keeps only the `ins:` line of its author list, so no address enters this repository (a scan of every copied .md
// The vendored copies are not edited, with one exception: each draft's front matter keeps only the `ins:` line of its author list, so no address enters this repository (a scan of every copied .md
// file for an address then fails the sync as a second guard). The author stays
// `ins: N. Byrd`. SOURCE.json records the commit the copies came from.
import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
import { execFileSync } from 'node:child_process';
import { join, resolve } from 'node:path';
import { findEmail } from './vendored.mjs';

const root = new URL('..', import.meta.url).pathname;
const src = resolve(process.argv[2] ?? join(root, '..', 'restact'));
const out = join(root, 'src', 'content', 'spec');

const DRAFT = 'draft-byrd-restact-protocol-00.md';
const PRESENTATION = 'draft-byrd-restact-presentation-00.md';
for (const f of [DRAFT, PRESENTATION]) {
// The extension drafts, vendored with the same treatment as the protocol draft.
const EXTENSIONS = ['objects', 'events', 'delegation', 'connectors', 'mcp', 'http-verbs', 'presentation'].map(
(n) => `draft-byrd-restact-${n}-00.md`,
);
const ALL = [DRAFT, ...EXTENSIONS];
for (const f of ALL) {
if (!existsSync(join(src, f))) {
console.error(`sync-spec: ${join(src, f)} not found. Pass the path to a checkout of stackumi/restact.`);
process.exit(2);
Expand All @@ -28,7 +32,7 @@ for (const f of [DRAFT, PRESENTATION]) {
const git = (...args) => execFileSync('git', ['-C', src, ...args], { encoding: 'utf8' }).trim();
const commit = git('rev-parse', 'HEAD');
const date = git('log', '-1', '--format=%cI');
if (git('status', '--porcelain', '--', DRAFT, PRESENTATION, 'registries')) {
if (git('status', '--porcelain', '--', ...ALL, 'registries')) {
console.error('sync-spec: the source checkout has uncommitted changes in the spec files; commit or stash them first.');
process.exit(2);
}
Expand Down Expand Up @@ -63,7 +67,7 @@ function stripAuthor(file) {
.join('\n');
return front + draft.slice(end);
}
const drafts = [DRAFT, PRESENTATION].map((f) => [f, stripAuthor(f)]);
const drafts = ALL.map((f) => [f, stripAuthor(f)]);

rmSync(out, { recursive: true, force: true });
mkdirSync(join(out, 'registries'), { recursive: true });
Expand All @@ -72,16 +76,15 @@ for (const f of readdirSync(join(src, 'registries')).filter((f) => f.endsWith('.
cpSync(join(src, 'registries', f), join(out, 'registries', f));
}

// Guard: no vendored file may contain an email address (the same pattern check-site uses).
const EMAIL = /[\w.+-]+@[\w-]+(?:\.[\w-]+)*\.[A-Za-z]{2,}\b/;
// Guard: no vendored file may contain an email address (the same check check-site uses; a URL's userinfo is not an address).
const scan = (dir) => {
for (const e of readdirSync(dir, { withFileTypes: true })) {
const p = join(dir, e.name);
if (e.isDirectory()) scan(p);
else if (e.name.endsWith('.md')) {
const hit = readFileSync(p, 'utf8').match(EMAIL);
const hit = findEmail(readFileSync(p, 'utf8'));
if (hit) {
console.error(`sync-spec: ${p} contains an email address ("${hit[0]}"); removed the output. Strip it at the source or extend the filter.`);
console.error(`sync-spec: ${p} contains an email address ("${hit}"); removed the output. Strip it at the source or extend the filter.`);
rmSync(out, { recursive: true, force: true });
process.exit(1);
}
Expand Down
6 changes: 3 additions & 3 deletions scripts/vendored.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -30,9 +30,9 @@ export function* walk(dir) {
// as Pagefind's, is not ours to remove).
const TEXT = /\.(?:html|txt|xml|json|js|mjs|css|svg|md|webmanifest)$/;
const CODE = /\.(?:js|mjs|css)$/;
// `scheme://user:password@host` is a URL's userinfo, such as a placeholder connection string, not
// an address.
const USERINFO = /[a-z][a-z0-9+.-]*:\/\/[^\s/@]*:$/i;
// `scheme://user@host` and `scheme://user:password@host` are a URL's userinfo, such as a
// placeholder connection string, not an address.
const USERINFO = /[a-z][a-z0-9+.-]*:\/\/(?:[^\s/@]*:)?$/i;

/** The first email address in `s`, ignoring URL userinfo, or null. */
export const findEmail = (s) => {
Expand Down
Loading
Loading