@warpgogol/werkstatt-shared 0.2.0

package/package.json

@@ -0,0 +1,352 @@
+{
+  "name": "@warpgogol/werkstatt-shared",
+  "version": "0.2.0",
+  "private": false,
+  "type": "module",
+  "description": "Stack-agnostic shared infrastructure extracted from werkstatt-site (RFC-0868).",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./checks": {
+      "types": "./src/checks/index.ts",
+      "default": "./src/checks/index.ts"
+    },
+    "./checks/lib/astro-site-url": {
+      "types": "./src/checks/lib/astro-site-url.ts",
+      "default": "./src/checks/lib/astro-site-url.ts"
+    },
+    "./checks/lib/i18n": {
+      "types": "./src/checks/lib/i18n.ts",
+      "default": "./src/checks/lib/i18n.ts"
+    },
+    "./checks/result-helpers": {
+      "types": "./src/checks/result-helpers.ts",
+      "default": "./src/checks/result-helpers.ts"
+    },
+    "./checks/suppressions-config": {
+      "types": "./src/checks/suppressions-config.ts",
+      "default": "./src/checks/suppressions-config.ts"
+    },
+    "./integration": {
+      "types": "./src/integration/index.ts",
+      "default": "./src/integration/index.ts"
+    },
+    "./integration-adapter-supabase-crm": {
+      "types": "./src/integration-adapter-supabase-crm/index.ts",
+      "default": "./src/integration-adapter-supabase-crm/index.ts"
+    },
+    "./integration-adapter-supabase-crm/tenant-registry": {
+      "types": "./src/integration-adapter-supabase-crm/tenant-registry.ts",
+      "default": "./src/integration-adapter-supabase-crm/tenant-registry.ts"
+    },
+    "./integration-adapter-supabase-crm/worker": {
+      "types": "./src/integration-adapter-supabase-crm/worker.ts",
+      "default": "./src/integration-adapter-supabase-crm/worker.ts"
+    },
+    "./integration/crm-buffer": {
+      "types": "./src/integration/crm-buffer.ts",
+      "default": "./src/integration/crm-buffer.ts"
+    },
+    "./integration/port": {
+      "types": "./src/integration/port.ts",
+      "default": "./src/integration/port.ts"
+    },
+    "./observability": {
+      "types": "./src/observability/index.ts",
+      "default": "./src/observability/index.ts"
+    },
+    "./ontology": {
+      "types": "./src/ontology/index.ts",
+      "default": "./src/ontology/index.ts"
+    },
+    "./ontology/cosmic": {
+      "types": "./src/ontology/cosmic/index.ts",
+      "default": "./src/ontology/cosmic/index.ts"
+    },
+    "./ontology/external-surfaces": {
+      "types": "./src/ontology/external-surfaces/index.ts",
+      "default": "./src/ontology/external-surfaces/index.ts"
+    },
+    "./ontology/manifest": {
+      "types": "./src/ontology/manifest.ts",
+      "default": "./src/ontology/manifest.ts"
+    },
+    "./ontology/operations": {
+      "types": "./src/ontology/operations/index.ts",
+      "default": "./src/ontology/operations/index.ts"
+    },
+    "./ontology/archetypes": {
+      "types": "./src/ontology/archetype-registry.ts",
+      "default": "./src/ontology/archetype-registry.ts"
+    },
+    "./ontology/schemas": {
+      "types": "./src/ontology/schemas/index.ts",
+      "default": "./src/ontology/schemas/index.ts"
+    },
+    "./ontology/schemas/manifest-resolver": {
+      "types": "./src/ontology/schemas/manifest-resolver.ts",
+      "default": "./src/ontology/schemas/manifest-resolver.ts"
+    },
+    "./ontology/shared-section-props": {
+      "types": "./src/ontology/shared-section-props/index.ts",
+      "default": "./src/ontology/shared-section-props/index.ts"
+    },
+    "./passport": {
+      "types": "./src/passport/index.ts",
+      "default": "./src/passport/index.ts"
+    },
+    "./passport/dht-sign": {
+      "types": "./src/passport/dht-sign.ts",
+      "default": "./src/passport/dht-sign.ts"
+    },
+    "./passport/identity-sign": {
+      "types": "./src/passport/identity-sign.ts",
+      "default": "./src/passport/identity-sign.ts"
+    },
+    "./passport/key-rotate": {
+      "types": "./src/passport/key-rotate.ts",
+      "default": "./src/passport/key-rotate.ts"
+    },
+    "./passport/schema": {
+      "types": "./src/passport/schema.ts",
+      "default": "./src/passport/schema.ts"
+    },
+    "./passport/sign": {
+      "types": "./src/passport/sign.ts",
+      "default": "./src/passport/sign.ts"
+    },
+    "./share": {
+      "types": "./src/share/index.ts",
+      "default": "./src/share/index.ts"
+    },
+    "./share/agent": {
+      "types": "./src/share/agent/index.ts",
+      "default": "./src/share/agent/index.ts"
+    },
+    "./share/attribution-display": {
+      "types": "./src/share/attribution-display.ts",
+      "default": "./src/share/attribution-display.ts"
+    },
+    "./share/check-hints": {
+      "types": "./src/share/check-hints.ts",
+      "default": "./src/share/check-hints.ts"
+    },
+    "./share/content": {
+      "types": "./src/share/content/index.ts",
+      "default": "./src/share/content/index.ts"
+    },
+    "./share/content-discipline": {
+      "types": "./src/share/content-discipline/index.ts",
+      "default": "./src/share/content-discipline/index.ts"
+    },
+    "./share/content-reference": {
+      "types": "./src/share/content-reference.ts",
+      "default": "./src/share/content-reference.ts"
+    },
+    "./share/content/resolve-field-path": {
+      "types": "./src/share/content/resolve-field-path.ts",
+      "default": "./src/share/content/resolve-field-path.ts"
+    },
+    "./share/counter-utils": {
+      "types": "./src/share/counter-utils.ts",
+      "default": "./src/share/counter-utils.ts"
+    },
+    "./share/css-value-normalize": {
+      "types": "./src/share/css-value-normalize.ts",
+      "default": "./src/share/css-value-normalize.ts"
+    },
+    "./share/dev-props-validator": {
+      "types": "./src/share/dev-props-validator.ts",
+      "default": "./src/share/dev-props-validator.ts"
+    },
+    "./share/entitlement": {
+      "types": "./src/share/entitlement.ts",
+      "default": "./src/share/entitlement.ts"
+    },
+    "./share/feature-policy": {
+      "types": "./src/share/feature-policy.ts",
+      "default": "./src/share/feature-policy.ts"
+    },
+    "./share/formula-eval": {
+      "types": "./src/share/formula-eval.ts",
+      "default": "./src/share/formula-eval.ts"
+    },
+    "./share/fs": {
+      "types": "./src/share/fs/index.ts",
+      "default": "./src/share/fs/index.ts"
+    },
+    "./share/image-provider": {
+      "types": "./src/share/image-provider.ts",
+      "default": "./src/share/image-provider.ts"
+    },
+    "./share/knowledge": {
+      "types": "./src/share/knowledge/index.ts",
+      "default": "./src/share/knowledge/index.ts"
+    },
+    "./share/knowledge/claim": {
+      "types": "./src/share/knowledge/claim.ts",
+      "default": "./src/share/knowledge/claim.ts"
+    },
+    "./share/knowledge/derivation": {
+      "types": "./src/share/knowledge/derivation.ts",
+      "default": "./src/share/knowledge/derivation.ts"
+    },
+    "./share/knowledge/freshness": {
+      "types": "./src/share/knowledge/freshness.ts",
+      "default": "./src/share/knowledge/freshness.ts"
+    },
+    "./share/knowledge/ledger": {
+      "types": "./src/share/knowledge/ledger.ts",
+      "default": "./src/share/knowledge/ledger.ts"
+    },
+    "./share/knowledge/plan": {
+      "types": "./src/share/knowledge/plan.ts",
+      "default": "./src/share/knowledge/plan.ts"
+    },
+    "./share/knowledge/source": {
+      "types": "./src/share/knowledge/source.ts",
+      "default": "./src/share/knowledge/source.ts"
+    },
+    "./share/material-credits": {
+      "types": "./src/share/material-credits.ts",
+      "default": "./src/share/material-credits.ts"
+    },
+    "./share/middleware": {
+      "types": "./src/share/middleware/language-redirect.ts",
+      "default": "./src/share/middleware/language-redirect.ts"
+    },
+    "./share/offer-capacity": {
+      "types": "./src/share/offer-capacity.ts",
+      "default": "./src/share/offer-capacity.ts"
+    },
+    "./share/onboarding-yaml": {
+      "types": "./src/share/onboarding-yaml/index.ts",
+      "default": "./src/share/onboarding-yaml/index.ts"
+    },
+    "./share/page": {
+      "types": "./src/share/page.ts",
+      "default": "./src/share/page.ts"
+    },
+    "./share/redirects": {
+      "types": "./src/share/redirects.ts",
+      "default": "./src/share/redirects.ts"
+    },
+    "./share/rfc0042-utils": {
+      "types": "./src/share/rfc0042-utils.ts",
+      "default": "./src/share/rfc0042-utils.ts"
+    },
+    "./share/runtime-context": {
+      "types": "./src/share/runtime-context.ts",
+      "default": "./src/share/runtime-context.ts"
+    },
+    "./share/schemas": {
+      "types": "./src/share/schemas/index.ts",
+      "default": "./src/share/schemas/index.ts"
+    },
+    "./share/schemas/effects": {
+      "types": "./src/share/schemas/effects.ts",
+      "default": "./src/share/schemas/effects.ts"
+    },
+    "./share/schemas/features": {
+      "types": "./src/share/schemas/features.ts",
+      "default": "./src/share/schemas/features.ts"
+    },
+    "./share/schemas/material-credit": {
+      "types": "./src/share/schemas/material-credit.ts",
+      "default": "./src/share/schemas/material-credit.ts"
+    },
+    "./share/schemas/media": {
+      "types": "./src/share/schemas/media.ts",
+      "default": "./src/share/schemas/media.ts"
+    },
+    "./share/schemas/print": {
+      "types": "./src/share/schemas/print.ts",
+      "default": "./src/share/schemas/print.ts"
+    },
+    "./share/schemas/site-background": {
+      "types": "./src/share/schemas/site-background.ts",
+      "default": "./src/share/schemas/site-background.ts"
+    },
+    "./share/scripts/gsap-mountain-journey": {
+      "types": "./src/share/scripts/gsap-mountain-journey.ts",
+      "default": "./src/share/scripts/gsap-mountain-journey.ts"
+    },
+    "./share/semantic": {
+      "types": "./src/share/semantic/index.ts",
+      "default": "./src/share/semantic/index.ts"
+    },
+    "./share/semantic/derived-prices-loader": {
+      "types": "./src/share/semantic/derived-prices-loader.ts",
+      "default": "./src/share/semantic/derived-prices-loader.ts"
+    },
+    "./share/shared-context": {
+      "types": "./src/share/shared-context.ts",
+      "default": "./src/share/shared-context.ts"
+    },
+    "./share/string-utils": {
+      "types": "./src/share/string-utils.ts",
+      "default": "./src/share/string-utils.ts"
+    },
+    "./share/text-normalize": {
+      "types": "./src/share/text-normalize.ts",
+      "default": "./src/share/text-normalize.ts"
+    },
+    "./share/text-position": {
+      "types": "./src/share/text-position.ts",
+      "default": "./src/share/text-position.ts"
+    },
+    "./share/visibility": {
+      "types": "./src/share/visibility.ts",
+      "default": "./src/share/visibility.ts"
+    },
+    "./share/wrap-inline-numbers": {
+      "types": "./src/share/wrap-inline-numbers.ts",
+      "default": "./src/share/wrap-inline-numbers.ts"
+    },
+    "./surface": {
+      "types": "./src/surface/index.ts",
+      "default": "./src/surface/index.ts"
+    },
+    "./surface/io": {
+      "types": "./src/surface/io/index.ts",
+      "default": "./src/surface/io/index.ts"
+    }
+  },
+  "scripts": {
+    "build": "pnpm exec tsc -p tsconfig.json --noEmit",
+    "build:check": "pnpm exec tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "pnpm exec tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": ["src", "tsconfig.json"],
+  "dependencies": {
+    "@lordicon/element": "^2.3.1",
+    "@noble/ed25519": "^3.1.0",
+    "ajv": "^8.20.0",
+    "bs58": "^6.0.0",
+    "expr-eval": "^2.0.2",
+    "hls.js": "^1.6.16",
+    "lenis": "^1.3.25",
+    "plyr": "^3.8.4",
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3"
+  },
+  "optionalDependencies": {
+    "@syrokomskyi/axiom-study": "*"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^5.20260801.1",
+    "@types/node": "^24.0.0",
+    "astro": "^7.2.0",
+    "fast-check": "^4.9.0",
+    "vitest": "^4.1.10"
+  }
+}

package/src/checks/index.ts

@@ -0,0 +1,24 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Shared check infrastructure barrel for @warpgogol/werkstatt-shared — exports diagnosticsResult, suppressions, i18n, and astro-site-url helpers (RFC-0868).</purpose>
+<non-goals>
+  <item>Do not export site-specific validators or pipeline definitions.</item>
+  <item>Do not import from @warpgogol/werkstatt-site or any stack plugin.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0868: extracted from werkstatt-site/src/checks as shared infrastructure.</item>
+</CHANGE_SUMMARY>
+*/
+
+export {
+  diagnosticsResult,
+  passResult,
+  failResult,
+  resultFromViolations,
+} from "./result-helpers.ts";
+
+export * from "./suppressions-config.ts";
+
+export { readAstroSiteUrl } from "./lib/astro-site-url.ts";
+export { readDefaultLanguageCode } from "./lib/i18n.ts";

package/src/checks/lib/astro-site-url.ts

@@ -0,0 +1,30 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Best-effort helper to read the canonical site URL from an app's astro.config.mjs.</purpose>
+<non-goals>
+  <item>Do not introduce app-specific runtime composition or deployment behavior into this reusable package source file.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Added Compass scaffolding.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+/**
+ * Read canonical site URL from astro.config.mjs.
+ * Best-effort regex — no AST parsing needed.
+ * Handles JS expressions like `site: process.env.X || "https://example.com"`.
+ */
+export async function readAstroSiteUrl(appDir: string): Promise<string | undefined> {
+  const configPath = join(appDir, "astro.config.mjs");
+  try {
+    const text = await readFile(configPath, "utf-8");
+    const match = text.match(/site:.*?["'](https?:\/\/[^"']+)["']/);
+    return match?.[1];
+  } catch {
+    return undefined;
+  }
+}

package/src/checks/lib/i18n.ts

@@ -0,0 +1,30 @@
+import { join } from "node:path";
+import { readFile } from "node:fs/promises";
+import { parse as parseYaml } from "yaml";
+
+function parseFrontmatter(source: string): { data: Record<string, unknown> } {
+  const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  if (!match) return { data: {} };
+  const data = parseYaml(match[1]) as Record<string, unknown>;
+  return { data };
+}
+
+export async function readDefaultLanguageCode(contentRoot: string): Promise<string> {
+  const systemPath = join(contentRoot, "system.md");
+  const raw = await readFile(systemPath, "utf-8");
+  const { data } = parseFrontmatter(raw);
+  const i18n = (data as Record<string, unknown>).i18n as { default?: unknown } | undefined;
+  if (typeof i18n?.default === "string" && i18n.default.trim() !== "") {
+    return i18n.default.trim();
+  }
+  throw new Error("[i18n] src/content/system.md must declare i18n.default.");
+}
+
+export function defaultLanguageFromManifest(manifest: { i18n?: unknown }): string {
+  const i18n = manifest.i18n as { default?: unknown } | undefined;
+  const defaultLanguage = i18n?.default;
+  if (typeof defaultLanguage === "string" && defaultLanguage.trim() !== "") {
+    return defaultLanguage.trim();
+  }
+  throw new Error("[i18n] manifest must declare i18n.default.");
+}

package/src/checks/result-helpers.ts

@@ -0,0 +1,102 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-0203 canonical result builders. Every builder returns a CheckResult
+(`{ command, status, diagnostics, summary }`) so non-zero exits propagate to CI
+and the central failure printer renders findings uniformly. The string builders
+(passResult/failResult/resultFromViolations) key each violation to a coarse
+ruleId = command; diagnosticsResult takes rich Diagnostic[] with registered ids.
+</purpose>
+<non-goals>
+  <item>Do not interpret violation severity — string builders emit error-severity diagnostics; failResult always exits 1.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0029 review: Initial creation to fix systemic exit-code bug across check files.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { CheckResult, Diagnostic, KernelCommandResult } from "@warpgogol/werkstatt/kernel";
+
+/**
+ * RFC-0203: canonical result builder. Migrated checks emit `Diagnostic[]` with
+ * registered rule ids instead of bare strings. Exit code is 1 when any
+ * diagnostic is an error; warnings and info do not fail the pipeline.
+ */
+export function diagnosticsResult(
+  command: string,
+  diagnostics: Diagnostic[],
+): KernelCommandResult<CheckResult> {
+  const summary = {
+    error: diagnostics.filter((d) => d.severity === "error").length,
+    warning: diagnostics.filter((d) => d.severity === "warning").length,
+    info: diagnostics.filter((d) => d.severity === "info").length,
+  };
+  const status: CheckResult["status"] =
+    summary.error > 0 ? "fail" : summary.warning > 0 ? "warn" : "pass";
+  return {
+    data: { command, status, diagnostics, summary },
+    exitCode: summary.error > 0 ? 1 : 0,
+    summary: `${command}: ${summary.error} error(s), ${summary.warning} warning(s)`,
+  };
+}
+
+/**
+ * RFC-0203: map bare violation strings into canonical error Diagnostics. The
+ * command name is the coarse, stable ruleId for these single-rule checks; checks
+ * that need finer ids or fixHints use {@link diagnosticsResult} directly.
+ */
+function violationsToDiagnostics(command: string, violations: string[]): Diagnostic[] {
+  return violations.map((message) => ({ ruleId: command, severity: "error" as const, message }));
+}
+
+function emptySummary(): CheckResult["summary"] {
+  return { error: 0, warning: 0, info: 0 };
+}
+
+/**
+ * Canonical success result. RFC-0203: emits an empty `CheckResult` (no
+ * diagnostics) rather than the legacy `{ command, status, violations }` shape.
+ */
+export function passResult(command: string, summary?: string): KernelCommandResult<CheckResult> {
+  return {
+    data: { command, status: "pass", diagnostics: [], summary: emptySummary() },
+    exitCode: 0,
+    summary: summary ?? `${command}: OK`,
+  };
+}
+
+/**
+ * Canonical failure result — always exits 1 (preserving the historical
+ * failResult contract). RFC-0203: violation strings become error Diagnostics
+ * keyed by the command name.
+ */
+export function failResult(
+  command: string,
+  violations: string[],
+): KernelCommandResult<CheckResult> {
+  const diagnostics = violationsToDiagnostics(command, violations);
+  return {
+    data: {
+      command,
+      status: "fail",
+      diagnostics,
+      summary: { error: diagnostics.length, warning: 0, info: 0 },
+    },
+    exitCode: 1,
+    summary: `${command}: ${violations.length} violation(s)`,
+  };
+}
+
+/**
+ * Build a canonical result from a violations array — pass if empty, fail
+ * otherwise. RFC-0203: no longer a bare-string shim; it emits canonical
+ * Diagnostics (ruleId = command). Checks that need registered fine-grained
+ * ruleIds, locators, or fixHints use {@link diagnosticsResult} instead.
+ */
+export function resultFromViolations(
+  command: string,
+  violations: string[],
+): KernelCommandResult<CheckResult> {
+  return violations.length > 0 ? failResult(command, violations) : passResult(command);
+}