Commit afeadf11 by PLN (Algolia)

projects: bilingual folder-model data layer + devname as first project

lib/projects.js generalizes the blog folder model to projects: meta.md
(shared: status, tags, typed links, accent, featured) + en.md/fr.md
(localized title/tagline + body). Default language en, per-language
fallback with honest untranslated flag, drafts follow the shared
prod/dev rule, typed link slots render only when they exist (post:
resolves a blog slug and hides unpublished posts). content/projects/
devname/ ships the first project in both languages.
parent a55eaeda
---
title: devname
---
Every dev server on this machine answers at a stable name — `hindsight.localhost`, `bench.sre.localhost`, `devname.localhost` — and nobody has ever remembered a port for it.
## The idea
`*.localhost` resolves to loopback on any modern OS (RFC 6761), with zero DNS setup. devname rides that: **one Caddy** proxying names to ports, a tiny registry, and a CLI that makes the whole thing boring.
```
devname ensure [project] [--service S] [--branch auto]
```
`ensure` is the only verb an agent ever needs: it prints the URL if the name exists, otherwise it allocates a port (17000–17999), registers the name, and reloads Caddy. Idempotent, safe to run concurrently (the registry is `flock`ed), safe to forget.
## How it works
- A launchd agent runs Caddy on `:80`/`:443`, bound to the wildcard (the only way an unprivileged process can bind a low port on macOS).
- **Every site starts with an abort guard**: any connection whose source is not loopback dies at Caddy. The names are local-program-only, enforced in the config, not in discipline.
- The registry is a flat `names.json`; the Caddyfile is generated from it, never hand-edited.
- `mkcert` issues one SAN certificate covering every registered name, so https works out of the box.
## For agents
The design target was agents starting servers: never hard-code a port, never parse `lsof` output.
```bash
PORT=$(devname ensure myapp --format port)
./myapp --port "$PORT" # now at myapp.localhost
```
Branch variants get their own names (`feat-x--tests.myapp.localhost`), so a worktree never collides with the main checkout.
## The index page
Caddy also serves **devname.localhost** itself: every registered name with live up/down status, probed per request — the registry's front door, built by the same tool that keeps it.
---
title: devname
---
Chaque serveur de dev de cette machine répond sur un nom stable — `hindsight.localhost`, `bench.sre.localhost`, `devname.localhost` — et personne n'a jamais eu à retenir un port.
## L'idée
`*.localhost` pointe vers le loopback sur tout OS moderne (RFC 6761), sans aucune configuration DNS. devname s'appuie là-dessus : **un seul Caddy** qui proxifie des noms vers des ports, un petit registre, et un CLI qui rend le tout ennuyeux — au bon sens du terme.
```
devname ensure [projet] [--service S] [--branch auto]
```
`ensure` est le seul verbe dont un agent a besoin : il affiche l'URL si le nom existe, sinon il alloue un port (17000–17999), enregistre le nom et recharge Caddy. Idempotent, sûr en concurrence (registre sous `flock`), sûr à oublier.
## Comment ça marche
- Un agent launchd fait tourner Caddy sur `:80`/`:443`, lié à l'adresse wildcard (la seule façon pour un processus non privilégié de binder un port bas sur macOS).
- **Chaque site commence par un garde-fou** : toute connexion dont la source n'est pas le loopback meurt chez Caddy. Les noms restent locaux, par construction dans la config, pas par discipline.
- Le registre est un simple `names.json` ; le Caddyfile est généré à partir de lui, jamais édité à la main.
- `mkcert` émet un seul certificat SAN couvrant tous les noms enregistrés — https marche d'emblée.
## Pour les agents
La cible de conception, ce sont les agents qui démarrent des serveurs : jamais de port en dur, jamais de parsing de `lsof`.
```bash
PORT=$(devname ensure monapp --format port)
./monapp --port "$PORT" # maintenant sur monapp.localhost
```
Les variantes de branche ont leurs propres noms (`feat-x--tests.monapp.localhost`) — un worktree ne entre jamais en collision avec le checkout principal.
## La page d'index
Caddy sert aussi **devname.localhost** lui-même : tous les noms enregistrés avec leur état up/down mesuré à chaque requête — la porte d'entrée du registre, construite par l'outil qui le tient.
---
title: devname
tagline: Stable local names for dev servers — nobody remembers ports
description: Every dev server on the machine gets a stable *.localhost name through one loopback-guarded Caddy. No port archaeology, no /etc/hosts, no DNS setup.
status: active
date: '2026-11-03'
tags: [cli, devx, networking, local-first]
accent: '#2e9e44'
featured: true
draft: false
links:
post: devname
---
import fs from 'fs';
import path from 'path';
import matter from 'gray-matter';
import { renderMarkdown } from './markdown';
import { draftsVisible } from './content';
/**
* Projects — the bilingual folder model (decided 2026-11-06, LeBoard
* www/decide/projects-gallery): `content/projects/<slug>/` holds `meta.md`
* (shared metadata) plus one `<lang>.md` per language (localized title,
* optional localized description, body). The slug IS the folder name.
*
* A project missing one language file is a valid project in the other;
* accessors report that via `untranslated`. A missing body is valid too —
* body-less projects render as pure cards, projects with prose become doc
* pages; same components either way.
*
* Shared meta.md fields (typed, all optional unless noted):
* title (required), tagline, description, status (active|beta|archived),
* date, tags[], links {repo, demo, docs, post, download} (each a URL or a
* blog slug for `post:` — only-when-exists: an empty slot renders nothing),
* image (first image is the OG card when the pipeline hasn't made one),
* accent (a CSS color for the card's --project-accent token),
* featured (landing grid), draft (prod/dev rule, same as every collection).
*/
const PROJECTS_ROOT = path.join(process.cwd(), 'content', 'projects');
/** Language of `/projects/<slug>` — the canonical URL stays default-language. */
export const DEFAULT_LANG = 'en';
/** All supported languages, in canonical order. */
export const PROJECT_LANGS = ['en', 'fr'];
/** Typed link slots, in render order. `post` holds a blog slug, not a URL. */
export const LINK_SLOTS = [
{ key: 'repo', label: 'Source' },
{ key: 'demo', label: 'Demo' },
{ key: 'docs', label: 'Docs' },
{ key: 'download', label: 'Download' },
{ key: 'post', label: 'Blog post' },
];
function projectSlugs() {
return fs
.readdirSync(PROJECTS_ROOT)
.filter((name) => fs.statSync(path.join(PROJECTS_ROOT, name)).isDirectory())
.filter((name) => {
const dir = path.join(PROJECTS_ROOT, name);
return (
fs.existsSync(path.join(dir, 'meta.md')) ||
PROJECT_LANGS.some((lang) => fs.existsSync(path.join(dir, `${lang}.md`)))
);
});
}
function langFile(slug, lang) {
return path.join(PROJECTS_ROOT, slug, `${lang}.md`);
}
function hasLang(slug, lang) {
return fs.existsSync(langFile(slug, lang));
}
/** Languages with content for a project, canonical order. */
export function getProjectLanguages(slug) {
return PROJECT_LANGS.filter((lang) => hasLang(slug, lang));
}
function readFrontmatter(file) {
return matter(fs.readFileSync(file, 'utf8')).data;
}
/** Shared metadata; a folder without meta.md falls back to a locale file so
* one malformed folder can't take the listing down (same shim as blog). */
function readMeta(slug) {
const metaFile = path.join(PROJECTS_ROOT, slug, 'meta.md');
if (fs.existsSync(metaFile)) return readFrontmatter(metaFile);
for (const lang of PROJECT_LANGS) {
const file = langFile(slug, lang);
if (fs.existsSync(file)) return readFrontmatter(file);
}
return {};
}
/** Merge meta.md with one language file into a project-shaped entry (no body). */
function projectEntry(slug, lang) {
const meta = readMeta(slug);
const file = langFile(slug, lang);
if (!fs.existsSync(file)) return null;
const localized = readFrontmatter(file);
return {
slug,
...meta,
title: localized.title ?? meta.title,
tagline: localized.tagline ?? meta.tagline,
description: localized.description ?? meta.tagline ?? meta.description,
languages: getProjectLanguages(slug),
};
}
/** First language with content, in canonical order. */
function primaryLang(slug) {
return getProjectLanguages(slug)[0] ?? null;
}
/**
* Project listing, newest-first. Drafts follow the prod/dev rule. `lang`
* picks the displayed title/description; projects without that language fall
* back to their first available language.
*/
export function getProjects(lang = DEFAULT_LANG) {
return projectSlugs()
.map((slug) => projectEntry(slug, getProjectLanguages(slug).includes(lang) ? lang : primaryLang(slug)))
.filter(Boolean)
.filter((project) => draftsVisible() || !project.draft)
.sort((a, b) => (a.date < b.date ? 1 : -1));
}
/** Featured subset for the landing grid, listing order. */
export function getFeaturedProjects(lang = DEFAULT_LANG) {
return getProjects(lang).filter((project) => project.featured === true);
}
/** Slug list — App Router callers map it to params. Drafts follow the prod/dev rule. */
export function getAllProjectSlugs() {
return projectSlugs().filter((slug) => draftsVisible() || readMeta(slug).draft !== true);
}
/** Every tag in the gallery with use counts, most-used first (timeline chips). */
export function getProjectTags() {
const counts = new Map();
for (const project of getProjects()) {
for (const tag of project.tags ?? []) {
counts.set(tag, (counts.get(tag) ?? 0) + 1);
}
}
return [...counts.entries()]
.sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
.map(([tag, count]) => ({ tag, count }));
}
/** OG card path when the pipeline (or the project's own image) provides one. */
export function projectOgImage(slug) {
const meta = readMeta(slug);
if (meta.image) return { url: meta.image };
const generated = `/images/projects/${slug}/og.png`;
return fs.existsSync(path.join(process.cwd(), 'public', generated))
? { url: generated }
: null;
}
/** Typed links resolved to {slot, label, url, host} rows; empty slots absent.
* `post:` holds a blog slug — a blog post that isn't published yet renders
* nothing rather than a dead link. */
export function getProjectLinks(meta) {
const links = meta.links ?? {};
return LINK_SLOTS.flatMap((slot) => {
const value = links[slot.key];
if (!value) return [];
if (slot.key === 'post') {
const post = blogPostMeta(value);
return post ? [{ ...slot, url: `/blog/${value}`, host: 'me.nech.pl' }] : [];
}
let host = null;
try {
host = new URL(value).host;
} catch {
host = null;
}
return [{ ...slot, url: value, host }];
});
}
function blogPostMeta(slug) {
const file = path.join(process.cwd(), 'content', 'blog', slug, 'meta.md');
if (!fs.existsSync(file)) return null;
const meta = readFrontmatter(file);
return meta.draft === true && !draftsVisible() ? null : meta;
}
/**
* Single project with rendered HTML body in `lang`; when that language file
* is missing, the first available language renders instead and
* `untranslated` names the requested language (the banner's job).
*/
export async function getProject(slug, lang = DEFAULT_LANG) {
if (!fs.existsSync(path.join(PROJECTS_ROOT, slug))) {
throw new Error(`No project found for projects/${slug}`);
}
const languages = getProjectLanguages(slug);
const lang_ = languages.includes(lang) ? lang : primaryLang(slug);
if (!lang_) throw new Error(`No language file found for projects/${slug}`);
const { content } = matter(fs.readFileSync(langFile(slug, lang_), 'utf8'));
const meta = readMeta(slug);
const localized = readFrontmatter(langFile(slug, lang_));
const contentHtml = await renderMarkdown(content);
return {
slug,
...meta,
title: localized.title ?? meta.title,
tagline: localized.tagline ?? meta.tagline,
description: localized.description ?? meta.tagline ?? meta.description,
status: meta.status ?? 'active',
links: getProjectLinks(meta),
lang: lang_,
untranslated: lang_ === lang ? null : lang,
languages,
contentHtml,
};
}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment