Public: anyone can read this; the crew can change it.
The guide lists every kind of file the viewer opens, generated from the same table the viewer reads #13891
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/13869-the-guide-lists-every-kind-of-file-the-v → main 5 commits fork 6 threads · 6 unresolved
docs/features/README.md +1
| @@ -272,6 +272,7 @@ Read with the guide page [Your apps](../guide-your-apps.md). | ||
| 272 | 272 | |
| 273 | 273 | ### Files in the browser |
| 274 | 274 | |
| 275 | - [](file-kinds.md) | |
| 275 | 276 | - [](mesh-files.md) |
| 276 | 277 | - [](file-stl.md) |
| 277 | 278 | - [](file-dxf.md) |
docs/features/file-kinds.md added +62
| @@ -0,0 +1,62 @@ | ||
| 1 | # Which files open | |
| 2 | ||
| 3 | The forge draws a file on its page when its kind is below and it is within the size shown; over that, the page shows the source or offers Download. | |
| 4 | ||
| 5 | <!-- file-kinds:begin (generated by scripts/kinds-guide.ts from src/web/render/kinds.ts; edit the code, then run `bun scripts/kinds-guide.ts`) --> | |
| 6 | ||
| 7 | - **Image**, drawn up to 50 MB: `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.avif`, `.bmp`, `.ico` | |
| 8 | - **SVG**, drawn up to 5 MB: `.svg` | |
| 9 | - **PDF**, drawn up to 100 MB: `.pdf` | |
| 10 | - **HTML page**, drawn up to 2 MB: `.html`, `.htm` | |
| 11 | - **Audio**, drawn up to 500 MB: `.mp3`, `.ogg`, `.oga`, `.wav`, `.flac`, `.m4a`, `.aac` | |
| 12 | - **Video**, drawn up to 4 GB: `.mp4`, `.m4v`, `.webm`, `.mov` | |
| 13 | - **Table (CSV, TSV, JSON lines)**, drawn up to 10 MB: `.csv`, `.tsv`, `.jsonl`, `.ndjson` | |
| 14 | - **SQLite database**, drawn up to 5 MB: `.db`, `.sqlite`, `.sqlite3` | |
| 15 | - **3D model**, drawn up to 100 MB: `.stl`, `.3mf`, `.ply`, `.glb`, `.gltf`, `.obj` | |
| 16 | - **Archive**, drawn up to 50 MB: `.zip`, `.tar`, `.tgz`, `.tar.gz` | |
| 17 | - **Spreadsheet**, drawn up to 10 MB: `.xlsx` | |
| 18 | - **Word document**, drawn up to 10 MB: `.docx` | |
| 19 | - **Slides**, drawn up to 10 MB: `.pptx` | |
| 20 | - **Layered image**, drawn up to 20 MB: `.ora` | |
| 21 | - **Font**, drawn up to 20 MB: `.ttf`, `.otf`, `.woff`, `.woff2` | |
| 22 | - **Photoshop**, drawn up to 4 GB: `.psd` | |
| 23 | - **Config**, drawn up to 1 MB: `.json`, `.jsonc`, `.yaml`, `.yml`, `.toml`, `.ini`, `.conf` | |
| 24 | - **Markdown**, drawn up to 1 MB: `.md`, `.markdown`, `.mdx` | |
| 25 | - **Notebook**, drawn up to 1 MB: `.ipynb` | |
| 26 | - **Patch**, drawn up to 1 MB: `.patch`, `.diff` | |
| 27 | - **Log**, drawn up to 1 MB: `.log`, `.ansi` | |
| 28 | - **Subtitles**, drawn up to 5 MB: `.srt`, `.vtt` | |
| 29 | - **GPS track**, drawn up to 20 MB: `.gpx` | |
| 30 | - **HTTP archive**, drawn up to 5 MB: `.har` | |
| 31 | - **GeoJSON**, drawn up to 5 MB: `.geojson` | |
| 32 | - **KML**, drawn up to 5 MB: `.kml` | |
| 33 | - **Calendar**, drawn up to 5 MB: `.ics` | |
| 34 | - **OpenTimelineIO**, drawn up to 1 MB: `.otio` | |
| 35 | - **Edit list**, drawn up to 1 MB: `.edl` | |
| 36 | - **Final Cut XML**, drawn up to 1 MB: `.fcpxml` | |
| 37 | - **Contacts**, drawn up to 1 MB: `.vcf`, `.vcard` | |
| 38 | - **Email**, drawn up to 5 MB: `.eml` | |
| 39 | - **G-code**, drawn up to 50 MB: `.gcode`, `.gco` | |
| 40 | - **DXF drawing**, drawn up to 5 MB: `.dxf`, a file that opens on 0 then SECTION | |
| 41 | - **Mermaid diagram**, drawn up to 1 MB: `.mmd`, `.mermaid` | |
| 42 | - **draw.io diagram**, drawn up to 1 MB: `.drawio` | |
| 43 | - **Excalidraw**, drawn up to 1 MB: `.excalidraw` | |
| 44 | - **STEP model**, drawn up to 5 MB: `.step`, `.stp` | |
| 45 | - **SARIF report**, drawn up to 5 MB: `.sarif` | |
| 46 | - **Coverage (lcov)**, drawn up to 5 MB: `.lcov`, `lcov.info` | |
| 47 | - **JUnit report**, drawn up to 5 MB: `*.junit.xml`, `TEST-*.xml`, `.xml with a <testsuite> root` | |
| 48 | - **OPML**, drawn up to 5 MB: `.opml`, `.xml with an <opml> root` | |
outdated
|
||
| 49 | - **RSS or Atom feed**, drawn up to 5 MB: `.rss`, `.atom`, `.xml with an <rss>, <feed> or <rdf:RDF> root` | |
| 50 | - **Env example**, drawn up to 1 MB: `.env.example`, `.env.sample`, `.env.template` | |
| 51 | - **OpenAPI**, drawn up to 1 MB: `openapi.json`, `openapi.yaml`, `openapi.yml`, `*.openapi.*` | |
| 52 | - **package.json**, drawn up to 1 MB: `package.json` | |
| 53 | - **Makefile**, drawn up to 1 MB: `Makefile`, `GNUmakefile`, `*.mk` | |
| 54 | - **Dockerfile**, drawn up to 1 MB: `Dockerfile`, `Containerfile`, `*.Dockerfile` | |
| 55 | - **GitHub workflow**, drawn up to 1 MB: `.github/workflows/*.yml`, `.github/workflows/*.yaml` | |
| 56 | - **Compose file**, drawn up to 1 MB: `compose.yaml`, `compose.yml`, `docker-compose.yaml`, `docker-compose.yml` | |
| 57 | - **SQL**, drawn up to 1 MB: `.sql` | |
| 58 | - **GraphQL**, drawn up to 1 MB: `.graphql`, `.gql` | |
| 59 | - **Other text**, drawn up to 1 MB: any other text | |
| 60 | - **Other binary**, none: download only: any other bytes | |
| 61 | ||
outdated
'any other text' and 'any other bytes' are prose shown as code; render plain. |
||
| 62 | <!-- file-kinds:end --> |
docs/guide-your-apps.md +5 −1
| @@ -12,7 +12,7 @@ Every app has an address on the forge. To use your own, open the app's Settings, | ||
| 12 | 12 | |
| 13 | 13 | ## Environment and secrets |
| 14 | 14 | |
| 15 | Variables are set in the app's Settings, App pane: a name, a value, and where it applies (production or previews). A name ending `_KEY`, `_SECRET` or `_TOKEN` is hidden after you save it. A `.env.example` file in the repository opens as a table of what the app needs ([](features/file-env.md)). Never commit a real secret. | |
| 15 | Variables are set in the app's Settings, App pane: a name, a value, and where it applies (production or previews). A name ending `_KEY`, `_SECRET` or `_TOKEN` is hidden after you save it. A `.env.example` file in the repository opens as a table of what the app needs. Never commit a real secret. | |
| 16 | 16 | |
| 17 | 17 | Your own account's keys, tokens and passkeys are at `/settings/secrets`, `/settings/tokens` and `/settings/passkeys`. |
| 18 | 18 | |
| @@ -35,6 +35,10 @@ The forge wakes a sleeping app at that time and calls the path. Printing a daily | ||
| 35 | 35 | |
| 36 | 36 | An app's own data lives under `FORGE_APP_DATA`. See [](features/app-backup.md). |
| 37 | 37 | |
| 38 | ## Which files open | |
| 39 | ||
| 40 | Every kind of file the viewer draws, and its size limit: [](features/file-kinds.md). | |
| 41 | ||
| 38 | 42 | Reference: [](APPS.md). Next: [](guide-hosting.md). |
| 39 | 43 | |
| 40 | 44 | Every feature note, by topic: [](features/README.md). |
scripts/kinds-guide.ts added +54
| @@ -0,0 +1,54 @@ | ||
| 1 | /** | |
| 2 | * Rewrite the file-kind table in docs/features/file-kinds.md from `kinds.ts`: | |
| 3 | * `bun scripts/kinds-guide.ts`. | |
| 4 | */ | |
| 5 | import { ALL_KINDS, RENDER_CAP, kindContent, kindMatches, type FileKind } from "../src/web/render/kinds.ts"; | |
| 6 | ||
| 7 | export const BEGIN = "<!-- file-kinds:begin (generated by scripts/kinds-guide.ts from src/web/render/kinds.ts; edit the code, then run `bun scripts/kinds-guide.ts`) -->"; | |
| 8 | export const END = "<!-- file-kinds:end -->"; | |
| 9 | ||
| 10 | /** The name a person says for each kind. A new kind without one fails the type check. */ | |
| 11 | export const NAMES: Readonly<Record<FileKind, string>> = { | |
| 12 | image: "Image", svg: "SVG", pdf: "PDF", html: "HTML page", audio: "Audio", video: "Video", csv: "Table (CSV, TSV, JSON lines)", | |
| 13 | sqlite: "SQLite database", model3d: "3D model", archive: "Archive", sheet: "Spreadsheet", document: "Word document", | |
| 14 | slides: "Slides", layers: "Layered image", font: "Font", psd: "Photoshop", config: "Config", markdown: "Markdown", | |
| 15 | notebook: "Notebook", patch: "Patch", log: "Log", subtitles: "Subtitles", gpx: "GPS track", har: "HTTP archive", | |
| 16 | geojson: "GeoJSON", kml: "KML", calendar: "Calendar", otio: "OpenTimelineIO", edl: "Edit list", fcpxml: "Final Cut XML", | |
| 17 | contacts: "Contacts", mail: "Email", gcode: "G-code", dxf: "DXF drawing", mermaid: "Mermaid diagram", drawio: "draw.io diagram", | |
| 18 | excalidraw: "Excalidraw", step: "STEP model", sarif: "SARIF report", lcov: "Coverage (lcov)", junit: "JUnit report", | |
| 19 | opml: "OPML", feed: "RSS or Atom feed", env: "Env example", openapi: "OpenAPI", package: "package.json", makefile: "Makefile", | |
| 20 | dockerfile: "Dockerfile", workflow: "GitHub workflow", compose: "Compose file", sql: "SQL", graphql: "GraphQL", | |
| 21 | text: "Other text", binary: "Other binary", | |
| 22 | }; | |
| 23 | ||
| 24 | /** 1_000_000 as `1 MB`; 4_000_000_000 as `4 GB`; no cap as `none: download only`. */ | |
| 25 | export function capText(bytes: number): string { | |
Comment says nothing is |
||
| 26 | if (bytes <= 0) return "none: download only"; | |
| 27 | return bytes >= 1_000_000_000 ? `${bytes / 1_000_000_000} GB` : `${bytes / 1_000_000} MB`; | |
| 28 | } | |
| 29 | ||
| 30 | /** One line to a kind, so a narrow screen wraps the names instead of squeezing a column. */ | |
| 31 | export function renderKinds(): string { | |
| 32 | return ALL_KINDS.map((k) => { | |
| 33 | const names = [...kindMatches(k).map((m) => `\`${m}\``), ...(kindContent(k) === undefined ? [] : [kindContent(k)])]; | |
| 34 | const cap = RENDER_CAP[k] > 0 ? `, drawn up to ${capText(RENDER_CAP[k])}` : `, ${capText(RENDER_CAP[k])}`; | |
| 35 | return `- **${NAMES[k]}**${cap}: ${names.join(", ")}`; | |
| 36 | }).join("\n"); | |
| 37 | } | |
| 38 | ||
| 39 | export function kindsIn(doc: string): string { | |
| 40 | const a = doc.indexOf(BEGIN), b = doc.indexOf(END); | |
| 41 | if (a < 0 || b < a) throw new Error("docs/features/file-kinds.md has no file-kinds markers"); | |
| 42 | return doc.slice(a + BEGIN.length, b).trim(); | |
| 43 | } | |
| 44 | ||
| 45 | export function withKinds(doc: string, table: string): string { | |
| 46 | const a = doc.indexOf(BEGIN), b = doc.indexOf(END); | |
| 47 | if (a < 0 || b < a) throw new Error("docs/features/file-kinds.md has no file-kinds markers"); | |
| 48 | return `${doc.slice(0, a + BEGIN.length)}\n\n${table}\n\n${doc.slice(b)}`; | |
| 49 | } | |
| 50 | ||
| 51 | if (import.meta.main) { | |
| 52 | const path = new URL("../docs/features/file-kinds.md", import.meta.url); | |
| 53 | await Bun.write(path, withKinds(await Bun.file(path).text(), renderKinds())); | |
| 54 | } |
src/web/render/kinds.ts +47
| @@ -529,3 +529,50 @@ const SNIFFED: readonly (readonly [string, Magic])[] = [ | ||
| 529 | 529 | export function sniffType(head: Uint8Array): string { |
| 530 | 530 | return SNIFFED.find(([, is]) => is(head))?.[0] ?? "binary data"; |
| 531 | 531 | } |
| 532 | ||
| 533 | /** Every kind, in the order the guide lists them: media first, then data, then text formats. */ | |
| 534 | export const ALL_KINDS: readonly FileKind[] = Object.keys(RENDER_CAP) as FileKind[]; | |
| 535 | ||
| 536 | /** Kinds that no extension names: a file name, a root element or the bytes decide. */ | |
| 537 | const BY_NAME: Readonly<Partial<Record<FileKind, readonly string[]>>> = { | |
| 538 | junit: ["*.junit.xml", "TEST-*.xml", ".xml with a <testsuite> root"], | |
| 539 | opml: [".xml with an <opml> root"], | |
| 540 | feed: [".xml with an <rss>, <feed> or <rdf:RDF> root"], | |
| 541 | env: [".env.example", ".env.sample", ".env.template"], | |
| 542 | openapi: ["openapi.json", "openapi.yaml", "openapi.yml", "*.openapi.*"], | |
| 543 | package: ["package.json"], | |
| 544 | makefile: ["Makefile", "GNUmakefile", "*.mk"], | |
| 545 | dockerfile: ["Dockerfile", "Containerfile", "*.Dockerfile"], | |
| 546 | workflow: [".github/workflows/*.yml", ".github/workflows/*.yaml"], | |
| 547 | compose: ["compose.yaml", "compose.yml", "docker-compose.yaml", "docker-compose.yml"], | |
| 548 | lcov: ["lcov.info"], | |
outdated
lcov: '.lcov' is already produced from TEXTUAL; drop it here, which removes the duplicate in the guide. |
||
| 549 | archive: [".tar.gz"], | |
| 550 | }; | |
| 551 | ||
| 552 | /** Kinds named in words, not by a name: shown as plain text, never as code. */ | |
| 553 | const BY_CONTENT: Readonly<Partial<Record<FileKind, string>>> = { | |
| 554 | dxf: "a file that opens on 0 then SECTION", | |
| 555 | text: "any other text", | |
| 556 | binary: "any other bytes", | |
| 557 | }; | |
| 558 | ||
| 559 | /** | |
| 560 | * Extensions the sniffing tables above do not list: `.xlsx` is checked by its zip entries, not | |
| 561 | * named. | |
| 562 | */ | |
| 563 | const SNIFFED_EXTENSIONS: Readonly<Partial<Record<FileKind, readonly string[]>>> = { | |
| 564 | sheet: ["xlsx"], | |
outdated
Redundant if xlsx is already in OFFICE/TEXTUAL; and line 563 is convoluted (adds tar.gz inside a loop). Remove or simplify, and cover with a test. |
||
| 565 | archive: ["zip", "tar", "tgz"], | |
| 566 | }; | |
| 567 | ||
| 568 | /** What names a kind, for the guide: extensions and file names, each once, to show as code. */ | |
| 569 | export function kindMatches(kind: FileKind): string[] { | |
| 570 | const exts = new Set<string>(SNIFFED_EXTENSIONS[kind] ?? []); | |
| 571 | for (const [ext, m] of Object.entries(MEDIA)) if (m.kind === kind) exts.add(ext); | |
| 572 | for (const [ext, k] of Object.entries(TEXTUAL)) if (k === kind) exts.add(ext); | |
| 573 | for (const [ext, k] of Object.entries(OFFICE)) if (k === kind) exts.add(ext); | |
| 574 | return [...[...exts].map((e) => `.${e}`), ...(BY_NAME[kind] ?? [])]; | |
| 575 | } | |
| 576 | ||
| 577 | /** What a kind is named by in words, when no name does: shown as plain text. */ | |
| 578 | export const kindContent = (kind: FileKind): string | undefined => BY_CONTENT[kind]; |
test/kinds-guide.test.ts added +42
| @@ -0,0 +1,42 @@ | ||
| 1 | import { expect, test } from "bun:test"; | |
| 2 | import { readFileSync } from "node:fs"; | |
| 3 | import { renderKinds, kindsIn, withKinds } from "../scripts/kinds-guide.ts"; | |
| 4 | import { ALL_KINDS, fileKind, kindMatches, RENDER_CAP } from "../src/web/render/kinds.ts"; | |
| 5 | import { RENDERERS } from "../src/web/render/renderers.ts"; | |
| 6 | ||
| 7 | const DOC = readFileSync(new URL("../docs/features/file-kinds.md", import.meta.url), "utf8"); | |
| 8 | ||
| 9 | test("the guide holds the file-kind table the code renders", () => { | |
| 10 | expect(kindsIn(DOC), "docs/features/file-kinds.md is stale: run bun scripts/kinds-guide.ts").toBe(renderKinds()); | |
| 11 | }); | |
| 12 | ||
| 13 | test("a stale table is caught and withKinds repairs it", () => { | |
| 14 | const stale = withKinds(DOC, renderKinds().replace("SQLite database", "Nope")); | |
| 15 | expect(kindsIn(stale)).not.toBe(renderKinds()); | |
| 16 | expect(withKinds(stale, renderKinds())).toBe(DOC); | |
| 17 | expect(() => withKinds("nothing", "t")).toThrow("markers"); | |
| 18 | }); | |
| 19 | ||
| 20 | test("every kind has a renderer, except text and binary, which keep the source view", () => { | |
| 21 | const without = ALL_KINDS.filter((k) => RENDERERS[k] === undefined && k !== "text" && k !== "binary"); | |
| 22 | expect(without, `kind(s) with no renderer registered in renderers.ts: ${without.join(", ")}`).toEqual([]); | |
| 23 | }); | |
| 24 | ||
| 25 | test("every kind is listed with a cap, and a named extension resolves to its kind", () => { | |
| 26 | expect(ALL_KINDS.length).toBe(Object.keys(RENDER_CAP).length); | |
| 27 | expect(kindMatches("sqlite")).toContain(".sqlite"); | |
| 28 | expect(renderKinds()).toContain("- **SQLite database**, drawn up to 5 MB: `.db`, `.sqlite`, `.sqlite3`"); | |
| 29 | expect(fileKind("a.tsv", new Uint8Array([97]))).toBe("csv"); | |
| 30 | }); | |
| 31 | ||
| 32 | test("a name is shown once, prose is plain text, and sheets and archives are named", () => { | |
| 33 | for (const k of ALL_KINDS) { | |
| 34 | const names = kindMatches(k); | |
| 35 | expect({ k, dup: names.length !== new Set(names).size }).toEqual({ k, dup: false }); | |
| 36 | } | |
| 37 | expect(kindMatches("lcov")).toEqual([".lcov", "lcov.info"]); | |
| 38 | expect(kindMatches("sheet")).toEqual([".xlsx"]); | |
| 39 | expect(kindMatches("archive").sort()).toEqual([".tar", ".tar.gz", ".tgz", ".zip"]); | |
| 40 | expect(renderKinds()).toContain("- **DXF drawing**, drawn up to 5 MB: `.dxf`, a file that opens on 0 then SECTION"); | |
| 41 | expect(renderKinds()).toContain("- **Other binary**, none: download only: any other bytes"); | |
| 42 | }); |
Nested backticks break the code span and the sentence is prose. Principle 8: write it as plain text (a file that opens on 0 then SECTION), not as an extension in code.