npm - @escape-game-over/atlas - Versions diffs - 0.1.1 - Mend

@escape-game-over/atlas 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (63) hide show

package/README.md +364 -0
package/bin/use-project.mjs +131 -0
package/docs/NOT-BUILT.md +329 -0
package/docs/checks.md +139 -0
package/docs/share-images.md +52 -0
package/docs/toolchain.md +83 -0
package/package.json +51 -0
package/src/analytics/google.ts +351 -0
package/src/analytics/index.ts +102 -0
package/src/analytics/tags.ts +57 -0
package/src/analytics/umami.ts +285 -0
package/src/astro/MetaTags.astro +87 -0
package/src/astro/consent.ts +165 -0
package/src/astro/images.ts +315 -0
package/src/astro/index.ts +44 -0
package/src/astro/public-files.ts +129 -0
package/src/astro/site-routes.ts +307 -0
package/src/config.ts +218 -0
package/src/contact.ts +233 -0
package/src/file.ts +16 -0
package/src/files.ts +39 -0
package/src/hours.ts +312 -0
package/src/i18n/define.ts +217 -0
package/src/i18n/placeholders.ts +94 -0
package/src/i18n/translate.ts +190 -0
package/src/image.ts +29 -0
package/src/index.ts +222 -0
package/src/jsonld/article.ts +165 -0
package/src/jsonld/breadcrumb.ts +34 -0
package/src/jsonld/business.ts +196 -0
package/src/jsonld/ids.ts +106 -0
package/src/jsonld/index.ts +59 -0
package/src/jsonld/node.ts +78 -0
package/src/jsonld/organization.ts +154 -0
package/src/jsonld/place.ts +96 -0
package/src/jsonld/product.ts +172 -0
package/src/jsonld/quantity.ts +55 -0
package/src/jsonld/service.ts +237 -0
package/src/jsonld/video.ts +239 -0
package/src/jsonld/website.ts +58 -0
package/src/llms.ts +160 -0
package/src/meta/content.ts +190 -0
package/src/meta/index.ts +432 -0
package/src/meta/robots.ts +212 -0
package/src/meta/share-image.ts +232 -0
package/src/meta/tag.ts +133 -0
package/src/meta/verification.ts +53 -0
package/src/money.ts +237 -0
package/src/project.ts +249 -0
package/src/redirects.ts +266 -0
package/src/robots.ts +80 -0
package/src/routes/define.ts +412 -0
package/src/routes/family.ts +251 -0
package/src/routes/resolve.ts +266 -0
package/src/site/api.ts +354 -0
package/src/site/create.ts +660 -0
package/src/site/index.ts +32 -0
package/src/site/page.ts +148 -0
package/src/sitemap.ts +257 -0
package/src/types.ts +160 -0
package/src/url.ts +144 -0
package/src/warn.ts +88 -0
package/src/xml.ts +103 -0

package/README.md ADDED Viewed

@@ -0,0 +1,364 @@
+# Atlas
+Typed, data-driven machinery for **static, multi-locale, multi-deployment Astro
+sites**.
+You write data — the languages, the copy, the route table, one file per
+deployment. Atlas derives the rest: URLs, `<head>`, `hreflang`, `sitemap.xml`,
+`robots.txt`, `llms.txt`, `_redirects` and the JSON-LD `@graph`. Nothing is
+written down twice, so a retranslated slug moves the sitemap entry, the
+alternates, the `llms.txt` link and the breadcrumb together.
+**A consuming project writes data, never logic.**
+```bash
+npm install @escape-game-over/atlas
+```
+> **Published publicly, built for internal use.** It lives on the public registry
+> so our own deployments can install it without auth or a private registry — not
+> as an invitation. Hence `UNLICENSED`: you can fetch it, you have no licence to
+> use it, and there is no support, no semver promise and no issue tracker behind
+> it. It is readable, and you are welcome to read it.
+Two worked examples live in this repo, and reading one is the fastest way in:
+|                                | What it shows                                                                                                               |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
+| [`examples/b2c`](examples/b2c) | One operator's public site — **2 deployments, 2 locales**, translated slugs, paginated news, a shared brand over two venues |
+| [`examples/b2b`](examples/b2b) | The manufacturer's own site — **1 deployment, 1 locale**, a priced catalogue, a single `Organization`                       |
+They are the same kind of business at either end of it, on purpose: almost
+everything that differs between them is a consequence of who is buying, not of
+which features were switched on.
+```bash
+npm install                              # from the repo root
+npm run dev -w examples/b2c              # or examples/b2b
+```
+## The two ideas
+**1. A route id is the only name you ever type.**
+A route maps an id to a slug per locale. Code links by id, so retranslating a
+URL is a one-line data change that no call site notices. A locale without its own
+slug falls back to the shared one:
+```ts
+about: { enabled: true, slug: "about-us", slugByLocale: { "el-GR": "sxetika-me-emas" } }
+```
+```astro
+<a href={site.pathFor("about", locale)}>  <!-- /about-us or /el-GR/sxetika-me-emas -->
+```
+Linking to a page the active deployment switched off is a compile error, not a
+404.
+**2. A deployment is an overlay, not a fork.**
+One file per deployment, saying only what differs:
+```ts
+export default defineProject(config, defaultMessages, defaultRoutes, {
+  url: "https://acme.example",
+  siteName: "Acme Rome",
+  icon,
+  themeColor: "#1d51e0",
+  enabledLocales: ["el-GR", "en-US"],
+  overrideRouting: { defaultLocale: "el-GR", prefixDefaultLocale: true },
+  overrideMessages: {
+    // Greek only — the English copy still falls through to the default catalog.
+    "home.hero.body": { "el-GR": "Η {company} κρατά το απόθεμα…" },
+  },
+  overrideRoutes: {
+    careers: { enabled: true },                                       // opt into a page
+    contact: { slugByLocale: { "el-GR": "epikoinoniste-mazi-mas" } }, // retranslate a URL
+  },
+})
+```
+Every field is named for what it *does* to the defaults, so a project file can
+never be mistaken for the whole truth: `enabledLocales` picks from what the site
+declares, and every `override*` is a patch over it.
+## The four steps
+Every step infers its types from the *values* of the last, so a consuming project
+never writes a type argument:
+```ts
+// 1. which languages exist, how URLs are shaped
+export default defineSiteConfig({ locales: {...}, defaultRouting: {...} })
+// 2. the base copy and routes
+export const baseMessages = defineMessages(config, {...})
+export const baseRoutes   = defineRoutes(config, {...})
+// 3. one deployment
+export default defineProject(config, baseMessages, baseRoutes, {...})
+// 4. the API the pages use
+export const site = createSite(config, baseMessages, baseRoutes, project)
+```
+Step 4 returns `t()`, `pathFor()`, `urlFor()`, `fileUrl()`, `alternatesFor()`,
+`localeLinksFor()`, `metaFor()`, `breadcrumbFor()`, `staticPaths()`, `routes`,
+`entries`, `sitemap()`, `robots()`, `llms()` and `redirects()` already wired.
+`t()` is bound to a locale and knows each message's `{placeholders}` from its
+text:
+```ts
+const t = site.translate(locale)
+t("contact.intro")                                        // no placeholders, no second argument
+t("footer.copyright", { company: "Acme Rome", year: "2026" })
+t("footer.copyright")                                     // ✗ params are not optional
+t("footer.copyright", { company: "Acme Rome" })           // ✗ {year} missing
+t("footer.copyright", { company: "A", year: "1", x: "" }) // ✗ {x} is not a placeholder
+```
+Nothing is auto-injected. Site-wide values are ordinary placeholders, passed
+explicitly.
+## What the build emits, and who asks for it
+| Output                   | Comes from                       | Needs from the project                  |
+| ------------------------ | -------------------------------- | --------------------------------------- |
+| `sitemap.xml`            | `siteRoutes()`, from the routes  | nothing                                 |
+| `robots.txt`             | `siteRoutes()`                   | nothing                                 |
+| `llms.txt`               | `siteRoutes()`                   | words, via `site.llms({...})`           |
+| `_redirects`             | `siteRoutes()`                   | rules, via `site.redirects()`           |
+| `BreadcrumbList` JSON-LD | `breadcrumbFor()`, from the slug | a name per step, in a layout            |
+| `LocalBusiness` JSON-LD  | `localBusiness()`                | address, phone, hours                   |
+| `Organization` JSON-LD   | `organization()`                 | name, URL, logo                         |
+| `WebSite` JSON-LD        | `website()`, home page only      | site name, optional alternate           |
+| `Product` JSON-LD        | `product()`                      | name, price table                       |
+| `Article` JSON-LD        | `article()`                      | headline, publication date              |
+| `VideoObject` JSON-LD    | `videoObject()`                  | a video, its stills and date            |
+| Analytics tags           | `metaFor()`, from the project    | ids, via `analytics` in `defineProject` |
+| `PublicFile` union       | `publicFiles()`, from `public/`  | nothing                                 |
+`site.metaFor()` returns the `<html>` attributes and every head tag for one page,
+so canonical, `hreflang`, `x-default`, `og:url` and the rest all come from one
+place and cannot disagree.
+## What the compiler enforces
+These are not conventions; each one fails `npm test`, and each is
+regression-tested by an `@ts-expect-error` suite.
+| Mistake                                                                         | Result                                       |
+| ------------------------------------------------------------------------------- | -------------------------------------------- |
+| A message missing a locale                                                      | error — default copy must cover every locale |
+| A locale of a message using different `{placeholders}` than its siblings        | error, naming the locale                     |
+| An override for a key that is not in the default catalog                        | error — typos can't become dead strings      |
+| An override that drops or invents a `{placeholder}`                             | error — existing `t()` calls stay valid      |
+| Calling `t()` without a required placeholder, or with a wrong/extra name        | error                                        |
+| A route that does not state `enabled`                                           | error — a page is never built by implication |
+| A slug or message naming a locale the site doesn't ship                         | error                                        |
+| A locale key that is not a language tag (`en`, `en_US`, `en-us`)                | error, naming the key                        |
+| Linking to a page the active project disabled                                   | error                                        |
+| Reading a disabled page from `site.routes`                                      | it is not there — the list is derived        |
+| A route with no `route.<id>.nav` / `.title` / `.description` / `.imageAlt` copy | error, listing the missing keys              |
+| A route declared with no view component                                         | error                                        |
+| A page with no share image, alt text, description or `robots` directives        | error — none of them have a default          |
+| A `robots` directive that is not a real one                                     | error — the vocabulary is a union            |
+| A project `url` that is not `https://`, or ends in a slash                      | error                                        |
+| `defaultLocale` not among the project's `enabledLocales`                        | error                                        |
+| An unknown field in a project declaration                                       | error — a typo cannot sit there unread       |
+| Two routes resolving to the same URL                                            | build throws, naming both                    |
+| A site icon that is not square, a multiple of 48px, and PNG                     | build throws                                 |
+The runtime throws are the ones types cannot see: facts about a *file* (an
+icon's real dimensions), facts only known after merging (URL collisions), or a
+value typed as plain `string` because it came from an env var. See
+[`docs/checks.md`](docs/checks.md) for the full split and how each error is
+worded.
+## Site-level versus per-page
+The same question answers it every time: *would this differ between two pages of
+the same site?*
+| Per page — passed to `metaFor()` | Site-level — declared in `defineProject()` |
+| -------------------------------- | ------------------------------------------ |
+| `title`, `description`           | `siteName`, `twitterSite`                  |
+| `image` (asset **and** its alt)  | `icon`, `themeColor`, `colorScheme`        |
+| `robots` policy                  | `url`                                      |
+A share image is per page because pages can be generated dynamically — a product
+page's image is part of the product, not of the route table, so routes carry no
+image at all. A favicon is site-level because search engines use one per
+hostname, read from the home page. Image and alt travel as one `ShareImage` value
+so they cannot be supplied from different places and drift apart. See
+[`docs/share-images.md`](docs/share-images.md) for what each social surface
+actually renders, and why `twitter:card` is pinned.
+## Config that tracks which pages exist
+A project switches routes off. Anything defined *alongside* a route then has two
+ways to rot: the page is built and its config is missing, or the page is gone and
+its config lingers. Two types, differing only in how many routes they speak for:
+|                       | `PerRoute<typeof site, T>`           | `WhenEnabled<typeof site, "careers", T>`         |
+| --------------------- | ------------------------------------ | ------------------------------------------------ |
+| Shape                 | a table keyed by route id            | a single value                                   |
+| Says                  | "every built route has one of these" | "this value belongs to *that* page"              |
+| When the route is off | that key is rejected                 | the type is `never` — the field cannot be filled |
+| Use with              | `satisfies`                          | a normal annotation                              |
+`PerRoute` must be used with `satisfies`, not as an annotation: excess-property
+checking is what catches the stale half, and only an object literal checked
+against a known target gets it.
+```ts
+const heroes = {
+    home: { variant: "wide" },
+    about: { variant: "tall" },
+} satisfies PerRoute<typeof site, Hero>;   // ✗ if `about` is off, ✗ if `contact` is on
+const careers: WhenEnabled<typeof site, "careers", Careers> = { ats: "…" };  // ✗ if off
+```
+## The rules this package keeps
+1. **No data, and no slots for data.** No locales, no copy, no route tables, no
+   company details — and no passthrough field for a consumer to smuggle them
+   through either. If Atlas does not read a value, Atlas does not declare it:
+   `defineProject` accepts a URL because it builds absolute links, and rejects a
+   company name because it never touches one.
+2. **No imports from a consumer.** Only relative imports inside `src/`.
+3. **No framework imports — outside `src/astro/`.** The core imports nothing from
+   `astro`, no `.astro` files, no DOM and no Node built-ins. `npm run test:types`
+   runs with `"types": []` to keep it honest, and excludes `src/astro/` because
+   that is the one place allowed to import the framework. Put something there
+   only when it genuinely cannot work without Astro, and prefer moving the
+   framework-dependent *edge* there over moving the logic.
+4. **Infer from values, never from type arguments.** When a helper needs to be
+   typed against project data, take that data as a *parameter* and let TypeScript
+   infer it. This is what keeps rules 1 and 2 satisfiable without making callers
+   write `<Locale, typeof baseMessages>`.
+## The barrel is the only way in
+```jsonc
+"exports": {
+  ".":                  "./src/index.ts",
+  "./astro":            "./src/astro/index.ts",
+  "./astro/images":     "./src/astro/images.ts",
+  "./astro/consent":    "./src/astro/consent.ts",
+  "./astro/meta-tags":  "./src/astro/MetaTags.astro"
+}
+```
+**And nothing else** — there is no wildcard, so
+`import { escapeXml } from "@escape-game-over/atlas/xml.ts"` fails to resolve.
+Whatever those entry points do not export is internal by construction rather than
+by convention, which is what makes the file layout under `src/` a private detail:
+modules can be split, renamed or flattened without touching a consumer.
+The split *within* `astro/` is a further constraint, not tidiness. `./astro` is
+imported by an Astro config, which is evaluated before the build exists — so it
+may use `node:` built-ins but not `astro:assets`. `./astro/images` is the
+opposite: it runs inside the build, from a page, and is unusable from a config.
+Merging them breaks whichever caller loads first.
+**The package ships TypeScript source, and there is no build step.**
+`MetaTags.astro` could not go through `tsc` anyway, and Astro's own
+`tsconfigs/base.json` already sets `allowImportingTsExtensions`, so every
+consumer gets it for free.
+## The `atlas` command
+```bash
+atlas use <project>          # copies config/projects/<name> -> config/project
+atlas use --fallback rome    # only when nothing else named one
+```
+The whole directory is copied, so extra files and nested folders come along
+without touching the tool — the contract is just that it contains `project.ts`.
+It resolves paths from the working directory, so a workspace's own
+`package.json` passes nothing. A deployment pipeline can skip it and write its
+own `config/project`.
+Where a default is wanted it belongs to the caller: the examples pass
+`--fallback` to `dev` and `check`, and deliberately do not to `build`, so the one
+command whose output gets deployed has to say what it is building.
+## Layout
+```txt
+src/            the package — see the export map above for what is reachable
+  index.ts        the public API
+  site/           createSite() and the Site it returns
+  meta/           head tags: canonical, hreflang, Open Graph, Twitter, robots
+  jsonld/         the @graph — one file per node, each linked to Google's docs
+  i18n/           defineMessages(), t(), placeholder extraction
+  routes/         defineRoutes(), routeFamily(), merging and collisions
+  analytics/      Umami and Google, and the Consent Mode defaults
+  astro/          the only framework-aware code, plus the one component
+bin/            the `atlas` CLI
+tests/          runtime behaviour — what a merge resolves to, what a builder rejects
+type-tests/     what the types must reject, via @ts-expect-error
+docs/           the long-form reasoning
+examples/       two complete consumers
+```
+## Testing
+**Two commands are the whole gate, and CI needs no more than these:**
+```bash
+npm run check-fmt   # biome, formatting and lint
+npm test            # everything else
+```
+`npm test` runs three suites in order, and stops at the first failure:
+```bash
+npm run test:types      # tsc --noEmit — the package compiles, and 137 type
+                        #   assertions in type-tests/ still reject what they must
+npm run test:unit       # vitest — 355 runtime tests
+npm run test:examples   # every example, every deployment: astro check + astro build
+npm run test:watch      # vitest, watching
+```
+`test:types` is also the isolation contract: no consumer paths, no ambient types,
+`src/astro/` excluded. If it passes, the package is genuinely independent of
+anything consuming it.
+`test:examples` **builds every deployment**, not just type-checks one, and both
+halves of that matter. `astro check` only ever sees whichever project
+`config/project` currently holds, so checking once would leave the b2c example's
+second venue entirely unlooked-at. And a whole class of guarantee — two routes
+resolving to the same URL, an icon that is not square, price tiers that
+contradict each other — can only throw at build time, because it depends on
+merged data or on a real file. Type-checking alone would pass all of it.
+The whole gate is about 15 seconds.
+## Documentation
+- [`docs/checks.md`](docs/checks.md) — every guarantee, where it is enforced, and
+  how the type tests and runtime tests divide the work.
+- [`docs/share-images.md`](docs/share-images.md) — what each social surface
+  crops, and why one 1200×630 image serves all of them.
+- [`docs/toolchain.md`](docs/toolchain.md) — the pinned TypeScript, the Biome
+  trade-off for `.astro`, and the traps.
+- [`docs/NOT-BUILT.md`](docs/NOT-BUILT.md) — what we deliberately do not build,
+  as questions and answers. Kept beside the code rather than in a backlog,
+  because a backlog is a list of things still to do and every one of these is a
+  thing not to do.
+## Publishing
+The package is `"private": true` today and consumed through the workspace.
+Everything publishing needs is already in place — the export map, `files`, the
+`bin`, `astro` as a peer dependency — so releasing is flipping that one boolean.
+No import statement in any consumer changes.

package/bin/use-project.mjs ADDED Viewed

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+/**
+ * Copies a project overlay into `config/project`, the folder the whole build
+ * reads from. Run automatically before `dev`, `build` and `check`.
+ *
+ *   atlas use acme
+ *   PROJECT=acme npm run build
+ *
+ * The entire project directory is copied, so extra files and nested folders come
+ * along automatically. A deployment pipeline can skip this command and write its
+ * own `config/project` — the contract is just that it contains `project.ts`.
+ */
+import { cp, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * The consuming project, not the package this file is installed in.
+ *
+ * `process.cwd()` rather than a path derived from `import.meta.url`, which is
+ * the whole difference between a script vendored into a repo and a bin: once
+ * this lives in `node_modules`, its own location says where *the package* is
+ * and nothing at all about which site is being built. npm runs a workspace's
+ * scripts with that workspace as the working directory, so a project's own
+ * `package.json` needs to pass nothing.
+ */
+const ROOT = process.cwd();
+const PROJECTS_DIR = join(ROOT, "config", "projects");
+const TARGET_DIR = join(ROOT, "config", "project");
+/**
+ * Only an entry-point check — the whole directory is copied recursively, so a
+ * project can add files and folders freely without touching this script.
+ */
+const ENTRY_FILE = "project.ts";
+/**
+ * Which project to copy. No project name is written in this file.
+ *
+ * This script is machinery: it knows how to copy *a* project and nothing about
+ * which ones exist, so naming one as a default would put a single deployment's
+ * name inside the generic half. Where a default is wanted it belongs to the
+ * caller — `package.json` passes `--fallback` to `dev` and `check`, and
+ * deliberately does not to `build`, so the one command whose output gets
+ * deployed has to say what it is building.
+ *
+ * A flag rather than shell expansion. `PROJECT=${PROJECT:-rome} npm run …` says
+ * the same thing in one line, and says it in POSIX shell — npm runs scripts
+ * through `cmd.exe` on Windows, where that is not syntax but a literal string.
+ * The flag costs six lines here and works wherever node does.
+ *
+ * Precedence is explicit argument, then environment, then fallback: naming a
+ * project on the command line beats an exported `PROJECT` left over from
+ * earlier in a session, and both beat a default nobody asked for.
+ */
+const argv = process.argv.slice(2);
+/**
+ * The subcommand, required and checked rather than assumed.
+ *
+ * `atlas rome` would read as "atlas, the project" to anyone who has met a CLI
+ * before, and there is no reading of it that stays true once this bin grows a
+ * second verb. Rejecting the bare form now costs one branch; discovering later
+ * that a project may not be named `use` costs a breaking change.
+ */
+const verb = argv[0];
+if (verb !== "use") {
+    console.error(
+        verb === undefined
+            ? "Usage: atlas use <project> [--fallback <project>]"
+            : `Unknown command "${verb}". Usage: atlas use <project> [--fallback <project>]`
+    );
+    process.exit(1);
+}
+const args = argv.slice(1);
+const flagAt = args.indexOf("--fallback");
+const fallback = flagAt === -1 ? undefined : args[flagAt + 1];
+// The flag and its value removed, so what is left is what someone typed. Both
+// indices have to be dropped by position rather than by value: a fallback of
+// `rome` and an explicit `rome` are the same string, and filtering by value
+// would take the wrong one out.
+const positional =
+    flagAt === -1
+        ? args
+        : args.filter((_, index) => index !== flagAt && index !== flagAt + 1);
+const name = positional[0] || process.env.PROJECT || fallback;
+async function projectNames() {
+    return (await readdir(PROJECTS_DIR, { withFileTypes: true }))
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name);
+}
+if (!name) {
+    console.error(
+        `No project named. Pass one as an argument or set PROJECT.\nAvailable: ${(await projectNames()).join(", ")}`
+    );
+    process.exit(1);
+}
+const sourceDir = join(PROJECTS_DIR, name);
+async function exists(path) {
+    try {
+        await stat(path);
+        return true;
+    } catch {
+        return false;
+    }
+}
+if (!(await exists(sourceDir))) {
+    console.error(
+        `Unknown project "${name}". Available: ${(await projectNames()).join(", ")}`
+    );
+    process.exit(1);
+}
+if (!(await exists(join(sourceDir, ENTRY_FILE)))) {
+    console.error(`Project "${name}" has no ${ENTRY_FILE}.`);
+    process.exit(1);
+}
+await rm(TARGET_DIR, { recursive: true, force: true });
+await cp(sourceDir, TARGET_DIR, { recursive: true });
+await writeFile(join(TARGET_DIR, ".project"), `${name}\n`, "utf8");
+console.log(
+    `Using project "${name}" (config/projects/${name} -> config/project)`
+);