@ctcstack/ctcdocs-core 0.1.0

package/dist/site-configuration.js

@@ -0,0 +1,206 @@
+/**
+ * The project configuration layer.
+ *
+ * Everything that identifies one deployment of this platform — the product
+ * name, the hostnames it is served from, the Worker it deploys to, the marker
+ * stamped into generated files — lives in the project's `site.config.json` and
+ * is read from here. Adapting the platform to another project is editing that
+ * one file plus the environment variables in `.env.example`; no source file,
+ * test, or workflow in the platform carries a project name of its own.
+ *
+ * The values are validated rather than trusted, because a typo in a hostname is
+ * the difference between a protected deployment and a public one.
+ */
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { PROJECT_LAYOUT } from './project-layout.js';
+export class SiteConfigurationError extends Error {
+    name = 'SiteConfigurationError';
+}
+function fail(path, expectation) {
+    throw new SiteConfigurationError(`${PROJECT_LAYOUT.configurationFile}: ${path} ${expectation}.`);
+}
+function record(value, path) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        fail(path, 'must be an object');
+    }
+    return value;
+}
+function text(source, key, path) {
+    const value = source[key];
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        fail(path, 'must be a non-empty string');
+    }
+    return value.trim();
+}
+/**
+ * Accepts only a bare HTTPS origin. A path, query, or embedded credential
+ * would silently produce wrong canonical URLs, wrong Wrangler routes, and a
+ * smoke test that probes the wrong address.
+ */
+function origin(source, key, path) {
+    const value = text(source, key, path);
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return fail(path, 'must be an absolute URL');
+    }
+    if (url.protocol !== 'https:' ||
+        url.username ||
+        url.password ||
+        url.search ||
+        url.hash ||
+        !['', '/'].includes(url.pathname)) {
+        fail(path, 'must be an HTTPS origin without credentials, path, or query');
+    }
+    return url;
+}
+/**
+ * A list of distinct, non-empty titles. Two entries differing only in case
+ * would make the precedence between them depend on which one a folder happens
+ * to contain, so they are rejected rather than deduplicated.
+ */
+function titleList(source, key, path) {
+    const value = source[key];
+    if (!Array.isArray(value) || value.length === 0) {
+        fail(path, 'must be a non-empty array of titles');
+    }
+    const titles = value.map((entry, index) => {
+        if (typeof entry !== 'string' || entry.trim().length === 0) {
+            fail(`${path}[${index}]`, 'must be a non-empty string');
+        }
+        return entry.trim();
+    });
+    const seen = new Set(titles.map((title) => title.toLocaleLowerCase('en')));
+    if (seen.size !== titles.length) {
+        fail(path, 'must not repeat a title');
+    }
+    return Object.freeze(titles);
+}
+function flag(source, key, path) {
+    const value = source[key];
+    if (typeof value !== 'boolean') {
+        fail(path, 'must be true or false');
+    }
+    return value;
+}
+function optionalVisibility(source, path) {
+    const value = source.visibility;
+    if (value === undefined) {
+        return 'private';
+    }
+    if (value !== 'private' && value !== 'public') {
+        fail(`${path}.visibility`, 'must be "private" or "public"');
+    }
+    return value;
+}
+/**
+ * Environment names become Wrangler environment keys and appear in Worker
+ * names as `<worker>-<environment>`, so they are held to the same shape as the
+ * Worker name itself.
+ */
+function environments(source) {
+    const raw = record(source.environments, 'deployment.environments');
+    const names = Object.keys(raw);
+    if (!names.includes('production')) {
+        fail('deployment.environments', 'must define a production environment');
+    }
+    const parsed = {};
+    const hostnames = new Map();
+    for (const name of names) {
+        const path = `deployment.environments.${name}`;
+        if (!/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/u.test(name)) {
+            fail(path, 'must be named with lowercase letters, digits, and hyphens');
+        }
+        const environmentSource = record(raw[name], path);
+        const url = origin(environmentSource, 'url', `${path}.url`);
+        const visibility = optionalVisibility(environmentSource, path);
+        const previous = hostnames.get(url.host);
+        if (previous !== undefined) {
+            fail(path, `must not reuse the hostname already bound by the ${previous} environment`);
+        }
+        hostnames.set(url.host, name);
+        parsed[name] = { hostname: url.host, url: url.origin, visibility };
+    }
+    return Object.freeze(parsed);
+}
+export function parseSiteConfiguration(input) {
+    const root = record(input, 'the configuration');
+    const brandSource = record(root.brand, 'brand');
+    const faviconPath = text(brandSource, 'faviconPath', 'brand.faviconPath');
+    if (!faviconPath.startsWith('/')) {
+        fail('brand.faviconPath', 'must be a site-root-relative path');
+    }
+    const brand = {
+        faviconPath,
+        name: text(brandSource, 'name', 'brand.name'),
+        siteDescription: text(brandSource, 'siteDescription', 'brand.siteDescription'),
+        siteTitle: text(brandSource, 'siteTitle', 'brand.siteTitle'),
+    };
+    const deploymentSource = record(root.deployment, 'deployment');
+    const workerName = text(deploymentSource, 'workerName', 'deployment.workerName');
+    if (!/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/u.test(workerName)) {
+        fail('deployment.workerName', 'must be lowercase letters, digits, and hyphens');
+    }
+    const syncSource = record(root.sync, 'sync');
+    const generatedBy = text(syncSource, 'generatedBy', 'sync.generatedBy');
+    // The marker is embedded in an HTML comment in every generated Markdown
+    // file. A comment delimiter inside it would terminate that comment early and
+    // publish the rest of the marker as document text.
+    if (generatedBy.includes('--') || generatedBy.includes('<')) {
+        fail('sync.generatedBy', 'must not contain "--" or "<"');
+    }
+    const defaultLocale = text(syncSource, 'defaultLocale', 'sync.defaultLocale');
+    if (defaultLocale.length < 2) {
+        fail('sync.defaultLocale', 'must be a language tag such as "en"');
+    }
+    const navigationSource = record(root.navigation, 'navigation');
+    const homeSource = record(root.home, 'home');
+    return {
+        brand,
+        deployment: {
+            environments: environments(deploymentSource),
+            workerName,
+        },
+        home: { lede: text(homeSource, 'lede', 'home.lede') },
+        navigation: {
+            landingDocumentTitles: titleList(navigationSource, 'landingDocumentTitles', 'navigation.landingDocumentTitles'),
+            sectionIndexPages: flag(navigationSource, 'sectionIndexPages', 'navigation.sectionIndexPages'),
+        },
+        sync: {
+            commitBotName: text(syncSource, 'commitBotName', 'sync.commitBotName'),
+            defaultLocale,
+            generatedBy,
+        },
+    };
+}
+/**
+ * Parsed configurations, keyed by absolute project root.
+ *
+ * The configuration is read by the Astro build, by every component that renders
+ * during it, and by the sync CLI. Reading and validating the same file dozens of
+ * times per build would be wasted work, and — more importantly — two components
+ * disagreeing about the configuration because one of them read a half-written
+ * file is a class of bug worth designing out.
+ */
+const loaded = new Map();
+export function loadSiteConfiguration(projectRoot) {
+    const root = resolve(projectRoot);
+    const cached = loaded.get(root);
+    if (cached) {
+        return cached;
+    }
+    const configurationPath = resolve(root, PROJECT_LAYOUT.configurationFile);
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(configurationPath, 'utf8'));
+    }
+    catch (error) {
+        throw new SiteConfigurationError(`${configurationPath} could not be read: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const configuration = parseSiteConfiguration(raw);
+    loaded.set(root, configuration);
+    return configuration;
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@ctcstack/ctcdocs-core",
+  "version": "0.1.0",
+  "description": "Configuration schema, project layout, and generated-path allowlist shared by the CTCDocs platform packages.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ctcstack/ctcdocs.git",
+    "directory": "packages/core"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.1",
+    "fast-check": "4.9.0",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "typecheck": "tsc --project tsconfig.json",
+    "test": "vitest run --root ../.."
+  }
+}

package/src/generated-paths.ts

@@ -0,0 +1,48 @@
+import { posix } from 'node:path';
+
+import {
+  GENERATED_DIRECTORY_ALLOWLIST,
+  GENERATED_FILE_ALLOWLIST,
+} from './project-layout.js';
+
+export function normalizeRepositoryPath(input: string): string | undefined {
+  if (input.length === 0 || input.includes('\\') || input.startsWith('/')) {
+    return undefined;
+  }
+
+  const normalized = posix.normalize(input);
+  if (
+    normalized === '.' ||
+    normalized === '..' ||
+    normalized.startsWith('../')
+  ) {
+    return undefined;
+  }
+
+  return normalized;
+}
+
+export function isGeneratedPathAllowed(input: string): boolean {
+  const normalized = normalizeRepositoryPath(input);
+  if (normalized === undefined) {
+    return false;
+  }
+
+  if (
+    GENERATED_FILE_ALLOWLIST.some((allowedPath) => normalized === allowedPath)
+  ) {
+    return true;
+  }
+
+  return GENERATED_DIRECTORY_ALLOWLIST.some(
+    (allowedDirectory) =>
+      normalized === allowedDirectory ||
+      normalized.startsWith(`${allowedDirectory}/`),
+  );
+}
+
+export function assertGeneratedPathAllowed(input: string): void {
+  if (!isGeneratedPathAllowed(input)) {
+    throw new Error(`Generated output path is not allowed: ${input}`);
+  }
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+export {
+  GENERATED_DIRECTORY_ALLOWLIST,
+  GENERATED_FILE_ALLOWLIST,
+  PROJECT_LAYOUT,
+} from './project-layout.js';
+export {
+  assertGeneratedPathAllowed,
+  isGeneratedPathAllowed,
+  normalizeRepositoryPath,
+} from './generated-paths.js';
+export {
+  generatedMarkdownHeader,
+  generatedSourceHeader,
+} from './ownership-markers.js';
+export { findProjectRoot, ProjectRootError } from './project-root.js';
+export {
+  loadSiteConfiguration,
+  parseSiteConfiguration,
+  SiteConfigurationError,
+} from './site-configuration.js';
+export type {
+  BrandConfiguration,
+  DeploymentConfiguration,
+  DeploymentEnvironmentConfiguration,
+  DeploymentEnvironmentConfigurations,
+  DeploymentVisibility,
+  HomeConfiguration,
+  NavigationConfiguration,
+  SiteConfiguration,
+  SyncConfigurationDefaults,
+} from './site-configuration.js';

package/src/ownership-markers.ts

@@ -0,0 +1,23 @@
+import type { SiteConfiguration } from './site-configuration.js';
+
+/**
+ * Ownership markers, derived from `sync.generatedBy` in the project
+ * configuration so one setting names the pipeline everywhere it signs its
+ * output. Markdown carries the HTML-comment form; generated TypeScript carries
+ * the line-comment form.
+ *
+ * They are functions of the configuration rather than constants because the
+ * platform does not own the value: it is read from the project that installed
+ * the platform, and two projects sharing this package must not share a marker.
+ */
+export function generatedMarkdownHeader(
+  configuration: SiteConfiguration,
+): string {
+  return `<!-- AUTO-GENERATED BY ${configuration.sync.generatedBy}. DO NOT EDIT. -->`;
+}
+
+export function generatedSourceHeader(
+  configuration: SiteConfiguration,
+): string {
+  return `// AUTO-GENERATED BY ${configuration.sync.generatedBy}. DO NOT EDIT.`;
+}

package/src/project-layout.ts

@@ -0,0 +1,45 @@
+/**
+ * Where a CTCDocs project keeps its files.
+ *
+ * The layout is a fixed convention rather than configuration, and deliberately
+ * so: the generated-path allowlist below is a security control. Sync automation
+ * fails when it writes outside it, and an allowlist a project can widen is an
+ * allowlist an attacker can widen. A project that wants a different shape forks
+ * the platform; it does not get a setting.
+ *
+ * Every path is repository-relative and POSIX-separated, because they are
+ * compared against Git paths and written into the manifest.
+ */
+export const PROJECT_LAYOUT = {
+  /** Identifies a project root; `findProjectRoot` walks up looking for it. */
+  configurationFile: 'site.config.json',
+  /** Deployment target. Wrangler reads it itself, so it cannot be generated. */
+  wranglerConfigurationFile: 'wrangler.jsonc',
+  /** Secret-scanning configuration, whose exemptions `validate` checks. */
+  gitleaksConfigurationFile: '.gitleaks.toml',
+  /** Served verbatim by the Worker. */
+  publicDirectory: 'public',
+  robotsFile: 'public/robots.txt',
+  headersFile: 'public/_headers',
+  /** Generated Markdown, one directory per Drive folder. */
+  generatedDocumentsDirectory: 'src/content/docs/_generated',
+  /** Original images, one directory per Google file identifier. */
+  generatedAssetsDirectory: 'src/assets/generated',
+  /** Generated TypeScript: the sidebar and the redirect map. */
+  generatedSourceDirectory: 'src/generated',
+  manifestFile: 'data/sync-manifest.json',
+  documentIndexFile: 'data/docs-index.json',
+  syncReportFile: 'data/latest-sync-report.json',
+} as const;
+
+export const GENERATED_DIRECTORY_ALLOWLIST = [
+  PROJECT_LAYOUT.generatedDocumentsDirectory,
+  PROJECT_LAYOUT.generatedAssetsDirectory,
+  PROJECT_LAYOUT.generatedSourceDirectory,
+] as const;
+
+export const GENERATED_FILE_ALLOWLIST = [
+  PROJECT_LAYOUT.manifestFile,
+  PROJECT_LAYOUT.documentIndexFile,
+  PROJECT_LAYOUT.syncReportFile,
+] as const;

package/src/project-root.ts

@@ -0,0 +1,40 @@
+/**
+ * Finding the project a platform package is running inside.
+ *
+ * The platform packages live in `node_modules` of a project they know nothing
+ * about. The CLI, the Astro components, and the browser suite all need the
+ * project's root — to read its configuration, to resolve generated output, to
+ * point Playwright at a corpus — and none of them can be told where it is by a
+ * relative path from their own file.
+ */
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+import { PROJECT_LAYOUT } from './project-layout.js';
+
+export class ProjectRootError extends Error {
+  override readonly name = 'ProjectRootError';
+}
+
+/**
+ * The nearest ancestor of `from` that holds `site.config.json`, `from`
+ * included. Defaults to the working directory, which is the project root for
+ * `astro build`, for `ctcdocs-sync`, and for every script a project's
+ * `package.json` runs.
+ */
+export function findProjectRoot(from: string = process.cwd()): string {
+  let directory = resolve(from);
+
+  for (;;) {
+    if (existsSync(resolve(directory, PROJECT_LAYOUT.configurationFile))) {
+      return directory;
+    }
+    const parent = dirname(directory);
+    if (parent === directory) {
+      throw new ProjectRootError(
+        `No ${PROJECT_LAYOUT.configurationFile} found in ${resolve(from)} or any parent directory. Run this from inside a CTCDocs project.`,
+      );
+    }
+    directory = parent;
+  }
+}