@warpgogol/werkstatt-shared 0.8.2 → 0.8.5

package/README.md

@@ -0,0 +1,135 @@
+# @warpgogol/werkstatt-shared
+
+[Українська](README.uk.md) | English
+
+Stack-agnostic shared infrastructure extracted from `werkstatt-site` (RFC-0868). Owns checks, integration, ontology, passport, share, and surface domains consumed by both the Werkstatt engine and the site plugin.
+
+---
+
+## What this package does
+
+This is a **shared infrastructure library** used by the [Werkstatt](https://www.npmjs.com/package/@warpgogol/werkstatt) engine and the `werkstatt-site` plugin. It provides:
+
+- **Checks** — content validators, SEO validators, surface expand/bake logic
+- **Integration** — CRM, funnel, hub, sharding, QStash adapters
+- **Ontology** — catalogs, enums, Sternsystem owner types
+- **Passport** — DHT signing, identity signing, schema validation
+- **Share** — slug generation, semantic extraction, URL canonicalization, route filtering, middleware, access protection
+- **Surface** — surface expand/bake helpers and labels
+
+You don't use this package on its own — it is consumed by the engine and site plugin as a dependency.
+
+---
+
+## Installation
+
+```sh
+pnpm add @warpgogol/werkstatt-shared
+```
+
+This package is installed automatically when you install `@warpgogol/werkstatt` or `@warpgogol/werkstatt-site`.
+
+---
+
+## How it fits into the Werkstatt ecosystem
+
+| Package | Role |
+| --- | --- |
+| `@warpgogol/forge` | Governance layer — skills, RFC/ADR workflows, CLI, project scaffolding |
+| `@warpgogol/werkstatt` | Runtime engine — missions, releases, deployment, certification, Bordbuch |
+| `@warpgogol/werkstatt-shared` | **This package** — shared infrastructure (checks, integration, ontology, passport, share) |
+| `@warpgogol/werkstatt-site` | Astro site plugin — consumes this package for checks, integration, ontology, passport, share |
+
+The engine and site plugin both import from this package. It MUST NOT import from `werkstatt-site` — enforced by `werkstatt.shared.validate`.
+
+---
+
+## Canonical utilities
+
+### Slug generation (RFC-0915, DNA-88)
+
+| Export | Purpose |
+| --- | --- |
+| `slugUrl(text, lang?)` | Locale-aware URL slug (German umlauts, Ukrainian transliteration, default) |
+| `slugId(text)` | Semantic block ID slug |
+| `HeadingSlugger` | Stateful heading anchor deduplication |
+
+```ts
+import { slugUrl } from "@warpgogol/werkstatt-shared/share/slug";
+
+const url = slugUrl("Über uns", "de"); // "ueber-uns"
+```
+
+### Semantic extraction (RFC-0901)
+
+| Export | Purpose |
+| --- | --- |
+| `splitSentences(text, locale?)` | Locale-aware sentence boundary detection (`de`, `uk`, `en`) |
+
+### Canonical entity URL (RFC-0910)
+
+| Export | Purpose |
+| --- | --- |
+| `canonicalRootUrl(baseUrl)` | Unprefixed root URL for JSON-LD entity identity |
+
+### Placeholder route filtering (RFC-0917)
+
+| Export | Purpose |
+| --- | --- |
+| `hasPlaceholderRoutes(routes)` | Detect Astro dynamic route templates (`[slug]`, `[version]`) |
+
+---
+
+## Architecture
+
+| Directory | Purpose |
+| --- | --- |
+| `src/index.ts` | Main barrel export |
+| `src/checks/` | Content validators, SEO validators, surface expand/bake |
+| `src/integration/` | CRM, funnel, hub, sharding, QStash adapters |
+| `src/ontology/` | Catalogs, enums, Sternsystem owner types |
+| `src/passport/` | DHT signing, identity signing, schema validation |
+| `src/share/` | Slug, semantic, URL canonicalization, routes, middleware, access protection |
+| `src/surface/` | Surface expand/bake helpers and labels |
+| `src/content/` | SystemManifest types and content schema |
+
+---
+
+## Boundary rules
+
+- This package MUST NOT import from `@warpgogol/werkstatt-site` — enforced by `werkstatt.shared.validate`.
+- This package MAY import from `@warpgogol/werkstatt` (engine) and external packages.
+- Axiom dependencies (`@syrokomskyi/axiom-*`) are `optionalDependencies` — consumers without axiom installed must use type-only imports or guard runtime access.
+
+---
+
+## Publishing to npm
+
+This package is published to the npm registry as `@warpgogol/werkstatt-shared`. Publishing is automated via GitHub Actions CI.
+
+### How it works
+
+1. The source lives in the [warpgogol/werkstatt](https://github.com/syrokomskyi/werkstatt) monorepo under `packages/werkstatt-shared/`.
+2. [`@warpgogol/repo-extract`](https://github.com/syrokomskyi/repo-extract) extracts the package into the standalone [syrokomskyi/werkstatt-shared](https://github.com/syrokomskyi/werkstatt-shared) repository, flattening it to repo root and stripping workspace dependencies.
+3. The generated GitHub Actions CI workflow runs on every push to `main`: lint → typecheck → build → test → `npm publish --provenance --access public`.
+4. The `NPM_TOKEN` secret must be set in the [repository settings](https://github.com/syrokomskyi/werkstatt-shared/settings/secrets/actions).
+
+### Triggering a new release
+
+From the werkstatt monorepo root:
+
+```sh
+# 1. Bump the version in packages/werkstatt-shared/package.json
+# 2. Run the extraction (extracts + commits + pushes to github.com:syrokomskyi/werkstatt-shared.git)
+pnpm exec repo-extract --config packages/werkstatt-shared/extract.config.yaml --verbose
+
+# 3. CI picks up the push and publishes to npm automatically
+```
+
+After CI completes, verify the new version on [npmjs.com/package/@warpgogol/werkstatt-shared](https://www.npmjs.com/package/@warpgogol/werkstatt-shared).
+
+---
+
+## License
+
+Apache-2.0

package/README.uk.md

@@ -0,0 +1,135 @@
+# @warpgogol/werkstatt-shared
+
+Українська | [English](README.md)
+
+Спільна інфраструктура, незалежна від стеку, витягнута з `werkstatt-site` (RFC-0868). Володіє доменами checks, integration, ontology, passport, share та surface, які споживають рушій Werkstatt та site-плагін.
+
+---
+
+## Що робить цей пакет
+
+Це **бібліотека спільної інфраструктури**, яку використовують рушій [Werkstatt](https://www.npmjs.com/package/@warpgogol/werkstatt) та плагін `werkstatt-site`. Вона надає:
+
+- **Checks** — валідатори контенту, SEO-валідатори, логіка surface expand/bake
+- **Integration** — адаптери CRM, funnel, hub, sharding, QStash
+- **Ontology** — каталоги, enum-и, типи Sternsystem owner
+- **Passport** — DHT-підписування, підписування ідентичності, валідація схем
+- **Share** — генерація slug-ів, семантична екстракція, канонізація URL, фільтрація маршрутів, middleware, захист доступу
+- **Surface** — хелпери surface expand/bake та мітки
+
+Цей пакет не використовується самостійно — його споживають рушій та site-плагін як залежність.
+
+---
+
+## Встановлення
+
+```sh
+pnpm add @warpgogol/werkstatt-shared
+```
+
+Цей пакет встановлюється автоматично при встановленні `@warpgogol/werkstatt` або `@warpgogol/werkstatt-site`.
+
+---
+
+## Як це вписується в екосистему Werkstatt
+
+| Пакет | Роль |
+| --- | --- |
+| `@warpgogol/forge` | Шар управління — навички, RFC/ADR робочі процеси, CLI, скаффолд проєктів |
+| `@warpgogol/werkstatt` | Рушій runtime — місії, релізи, розгортання, сертифікація, Bordbuch |
+| `@warpgogol/werkstatt-shared` | **Цей пакет** — спільна інфраструктура (checks, integration, ontology, passport, share) |
+| `@warpgogol/werkstatt-site` | Astro site-плагін — споживає цей пакет для checks, integration, ontology, passport, share |
+
+Рушій та site-плагін імпортують з цього пакунка. Він НЕ ПОВИНЕН імпортувати з `werkstatt-site` — це контролюється `werkstatt.shared.validate`.
+
+---
+
+## Канонічні утиліти
+
+### Генерація slug (RFC-0915, DNA-88)
+
+| Експорт | Призначення |
+| --- | --- |
+| `slugUrl(text, lang?)` | Локалізований URL-slug (німецькі умлаути, українська транслітерація, за замовчуванням) |
+| `slugId(text)` | Семантичний slug ID блоку |
+| `HeadingSlugger` | Станковий дедуплікатор якорів заголовків |
+
+```ts
+import { slugUrl } from "@warpgogol/werkstatt-shared/share/slug";
+
+const url = slugUrl("Über uns", "de"); // "ueber-uns"
+```
+
+### Семантична екстракція (RFC-0901)
+
+| Експорт | Призначення |
+| --- | --- |
+| `splitSentences(text, locale?)` | Локалізоване виявлення меж речень (`de`, `uk`, `en`) |
+
+### Канонічний URL сутності (RFC-0910)
+
+| Експорт | Призначення |
+| --- | --- |
+| `canonicalRootUrl(baseUrl)` | Непрефіксований кореневий URL для JSON-LD ідентичності сутності |
+
+### Фільтрація плейсхолдер-маршрутів (RFC-0917)
+
+| Експорт | Призначення |
+| --- | --- |
+| `hasPlaceholderRoutes(routes)` | Виявлення Astro динамічних шаблонів маршрутів (`[slug]`, `[version]`) |
+
+---
+
+## Архітектура
+
+| Директорія | Призначення |
+| --- | --- |
+| `src/index.ts` | Головний barrel-експорт |
+| `src/checks/` | Валідатори контенту, SEO-валідатори, surface expand/bake |
+| `src/integration/` | Адаптери CRM, funnel, hub, sharding, QStash |
+| `src/ontology/` | Каталоги, enum-и, типи Sternsystem owner |
+| `src/passport/` | DHT-підписування, підписування ідентичності, валідація схем |
+| `src/share/` | Slug, семантика, канонізація URL, маршрути, middleware, захист доступу |
+| `src/surface/` | Хелпери surface expand/bake та мітки |
+| `src/content/` | Типи SystemManifest та схема контенту |
+
+---
+
+## Межі
+
+- Цей пакет НЕ ПОВИНЕН імпортувати з `@warpgogol/werkstatt-site` — контролюється `werkstatt.shared.validate`.
+- Цей пакет МОЖЕ імпортувати з `@warpgogol/werkstatt` (рушій) та зовнішніх пакунків.
+- Axiom-залежності (`@syrokomskyi/axiom-*`) — `optionalDependencies`. Споживачі без axiom повинні використовувати type-only імпорти або охороняти runtime-доступ.
+
+---
+
+## Публікація в npm
+
+Цей пакет публікується в реєстр npm як `@warpgogol/werkstatt-shared`. Публікація автоматизована через GitHub Actions CI.
+
+### Як це працює
+
+1. Вихідний код знаходиться в монорепозиторії [warpgogol/werkstatt](https://github.com/syrokomskyi/werkstatt) у `packages/werkstatt-shared/`.
+2. [`@warpgogol/repo-extract`](https://github.com/syrokomskyi/repo-extract) витягує пакет у автономний репозиторій [syrokomskyi/werkstatt-shared](https://github.com/syrokomskyi/werkstatt-shared), вирівнюючи його до кореня репозиторію та видаляючи залежності робочого простору.
+3. Згенерований GitHub Actions CI-воркфлоу запускається при кожному пуші в `main`: lint → typecheck → build → test → `npm publish --provenance --access public`.
+4. Секрет `NPM_TOKEN` має бути встановлений у [налаштуваннях репозиторію](https://github.com/syrokomskyi/werkstatt-shared/settings/secrets/actions).
+
+### Запуск нового релізу
+
+З кореня монорепозиторію werkstatt:
+
+```sh
+# 1. Підняти версію в packages/werkstatt-shared/package.json
+# 2. Запустити екстракцію (витягує + комітить + пушить в github.com:syrokomskyi/werkstatt-shared.git)
+pnpm exec repo-extract --config packages/werkstatt-shared/extract.config.yaml --verbose
+
+# 3. CI підхоплює пуш і публікує в npm автоматично
+```
+
+Після завершення CI перевірте нову версію на [npmjs.com/package/@warpgogol/werkstatt-shared](https://www.npmjs.com/package/@warpgogol/werkstatt-shared).
+
+---
+
+## Ліцензія
+
+Apache-2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warpgogol/werkstatt-shared",
-  "version": "0.8.2",
+  "version": "0.8.5",
   "private": false,
   "type": "module",
   "engines": {

package/src/share/image-provider.ts

@@ -219,6 +219,8 @@ export interface ImageVariantEntry {
    * stale derived variants (same contract as video.variants.generate RFC-0210).
    */
   sourceHash?: string;
+  /** RFC-0928: WebP quality used by image.variants.generate (minimum 90). */
+  quality?: number;
 }
 
 /** Top-level manifest written by `image.variants.generate` and read by createBuildPortableProvider. */

package/src/share/middleware/access-protection.ts

@@ -45,6 +45,16 @@ function isDevOrAltHost(host: string): boolean {
   return host.startsWith("dev.") || host.startsWith("alt.");
 }
 
+/**
+ * Paths exempt from access protection on dev/alt subdomains.
+ * Browsers fetch these without sending Basic Auth credentials, causing 401 console errors.
+ */
+const PUBLIC_STATIC_EXEMPTIONS = ["/manifest.webmanifest"];
+
+function isExemptPath(pathname: string): boolean {
+  return PUBLIC_STATIC_EXEMPTIONS.includes(pathname);
+}
+
 /**
  * RFC-0899: Check access protection for a request. Called from the Worker entry point
  * (worker.ts) before passing to the Astro handler. This is necessary because Astro
@@ -66,6 +76,9 @@ export function checkAccessProtection(
   const host = request.headers.get("host") ?? "";
   if (!isDevOrAltHost(host)) return null;
 
+  const url = new URL(request.url);
+  if (isExemptPath(url.pathname)) return null;
+
   const pin = (env.ACCESS_PIN as string | undefined) ?? undefined;
 
   // No PIN set — allow access (caller should add X-Robots-Tag)
@@ -144,6 +157,13 @@ export const accessProtectionMiddleware = defineMiddleware(async (context: any,
     return next();
   }
 
+  const url = new URL(context.request.url);
+  if (isExemptPath(url.pathname)) {
+    const response = await next();
+    response.headers.set("X-Robots-Tag", NOINDEX_HEADER);
+    return response;
+  }
+
   const pin = await resolveAccessPin();
 
   // No PIN set — allow access but still set noindex headers

package/src/share/middleware/tests/access-protection.test.ts

@@ -25,7 +25,7 @@ describe("RFC-0899: access protection middleware", () => {
     ) => Promise<Response>;
   }
 
-  function makeContext(host: string, authHeader?: string) {
+  function makeContext(host: string, authHeader?: string, pathname = "/") {
     const headers = new Map<string, string>();
     headers.set("host", host);
     if (authHeader) headers.set("authorization", authHeader);
@@ -34,6 +34,7 @@ describe("RFC-0899: access protection middleware", () => {
         headers: {
           get: (name: string) => headers.get(name.toLowerCase()) ?? null,
         },
+        url: `https://${host}${pathname}`,
       },
     };
   }
@@ -42,10 +43,11 @@ describe("RFC-0899: access protection middleware", () => {
     handler: (context: unknown, next: () => Promise<Response>) => Promise<Response>,
     host: string,
     authHeader?: string,
+    pathname = "/",
   ): Promise<Response & { _nextCalled: boolean }> {
     let nextCalled = false;
     const nextResponse = new Response("page content", { status: 200 });
-    const result = await handler(makeContext(host, authHeader), async () => {
+    const result = await handler(makeContext(host, authHeader, pathname), async () => {
       nextCalled = true;
       return nextResponse;
     });
@@ -120,4 +122,21 @@ describe("RFC-0899: access protection middleware", () => {
     const res = await runMiddleware(handler, "example.com");
     expect(res.headers.get("X-Robots-Tag")).toBe(null);
   });
+
+  it("exempts /manifest.webmanifest from auth on dev.* when PIN is set", async () => {
+    mockEnv.ACCESS_PIN = "1234";
+    const handler = await loadMiddleware();
+    const res = await runMiddleware(handler, "dev.example.com", undefined, "/manifest.webmanifest");
+    expect(res._nextCalled).toBe(true);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("X-Robots-Tag")).toBe("noindex, nofollow, noai, noimageai");
+  });
+
+  it("exempts /manifest.webmanifest from auth on alt.* when PIN is set", async () => {
+    mockEnv.ACCESS_PIN = "1234";
+    const handler = await loadMiddleware();
+    const res = await runMiddleware(handler, "alt.example.com", undefined, "/manifest.webmanifest");
+    expect(res._nextCalled).toBe(true);
+    expect(res.status).toBe(200);
+  });
 });