@vyriy/ssg 0.9.0 → 0.9.2

package/AGENTS.md

@@ -14,6 +14,7 @@ Always read the root `AGENTS.md` first for current project direction, then use t
 - Avoid hidden framework, CMS, browser, filesystem, network, or cloud assumptions unless they are the package contract.
 - Add packages only when they reduce real complexity, clarify boundaries, or improve reuse.
 - Prefer the option that is simpler to explain, easier to evolve, and calmer to maintain.
+- Grow package functionality in small, calm, reviewable steps that are easy to test and continue.
 
 ## Standard Package Shape
 
@@ -84,6 +85,8 @@ Documentation must move with code. Do not finish a package change while docs des
 - Keep `doc.mdx` aligned with the README and package title when packages are added, renamed, or reorganized.
 - Add or update JSDoc for public exports when behavior, parameters, return values, errors, side effects, or usage expectations need explanation.
 - For component packages, include visual documentation, stories, or examples for supported states, variants, and interaction states.
+- Keep reusable components as dumb as practical: push data shaping, stateful orchestration, and demo-specific logic into the entry point or owning composition layer.
+- Store demo data in stories instead of embedding it in reusable component source.
 - Avoid broad architecture essays in package READMEs; keep architectural direction in root-level docs unless it is necessary to use the package.
 
 ## Tests Are Required
@@ -94,9 +97,11 @@ Tests should protect public behavior and meaningful regression risk.
 - Add a real test immediately for new packages. If behavior is not finalized, add a valid placeholder test with a clear public API expectation.
 - Prefer behavior-focused tests over private implementation lock-in.
 - Keep tests deterministic and avoid real network, timers, browser, filesystem, or cloud dependencies unless that dependency is the behavior under test.
+- Mock external dependencies from `node_modules` in unit tests so package behavior stays deterministic and local.
 - When mocking modules, install mocks before loading the module under test.
 - Use `@jest/globals` in Jest tests.
-- Use `--coverage=false` for focused behavioral regression runs when global coverage thresholds would obscure the result.
+- Keep coverage enabled for normal validation. The shared Jest config in `packages/jest/index.ts` requires 100% global coverage for branches, functions, lines, and statements.
+- For small changes, run Jest against the changed tests or changed package with coverage enabled. For larger package changes, public API changes, or cross-package changes, run the full Jest suite with coverage.
 
 Typical package test naming:
 
@@ -127,10 +132,12 @@ Preferred validation commands:
 yarn tsc --pretty false
 yarn eslint <changed files or package>
 yarn prettier --check <changed files or package>
-yarn jest <changed tests or package> --runInBand --coverage=false
+yarn jest <changed tests or package> --runInBand
 ```
 
-Also run `yarn build:dist` for package export, manifest, build-shape, or generated-dist behavior changes. After larger package or library changes, prefer building the affected library/package as an additional confidence check.
+Run ESLint after YAML/YML changes too, for example `yarn eslint <changed.yml>`, because the repo ESLint setup validates YAML files as well.
+
+Also run `yarn build:dist` for package export, manifest, build-shape, or generated-dist behavior changes. After larger package or library changes, run the full Jest suite with coverage and prefer building the affected library/package as an additional confidence check.
 
 If a required validation command cannot be run, state why and report the remaining risk.
 

package/README.md

@@ -1,105 +1,55 @@
 # @vyriy/ssg
 
-Part of [Vyriy](https://vyriy.dev) - a calm architecture toolkit for TypeScript, React, SSR, SSG, APIs, and cloud-ready apps.
+Static generation helpers for `vyriy.dev`.
 
-Full documentation: https://vyriy.dev/docs/ssg/
-
-Static Markdown site generator for Vyriy-style content sites.
-
-## Purpose
-
-This package builds a static site from Markdown `README.md` files. It is intended for content-first sites that need HTML pages, section catalogs, MiniSearch data, featured home content, related links, sitemap, robots, and copied public assets without adopting a full framework.
-
-Markdown rendering uses `react-markdown` with GitHub-flavored Markdown and `rehype-highlight`, so content supports tables, task lists, autolinks, and highlighted fenced code blocks.
-
-## CLI
-
-Build a site from `site` into `dist`:
-
-```bash
-vyriy-ssg site --output dist
-```
-
-The package also exposes the short `ssg` command:
-
-```bash
-ssg site -o dist
-```
-
-Useful options:
-
-- `--site-url <url>` sets canonical URLs and sitemap locations.
-- `--site-name <name>` sets the built-in theme name.
-- `--stylesheet <href>` links a stylesheet instead of using the built-in CSS.
-- `--stylesheet-file <path>` inlines a stylesheet file.
-- `--ga <id>` adds a Google Analytics measurement ID.
-
-## Content
-
-By default, the generator expects this shape:
-
-```txt
-site/
-  home/README.md
-  consulting/README.md
-  docs/README.md
-  blog/<slug>/README.md
-  docs/<slug>/README.md
-  examples/<slug>/README.md
-  public/
-```
-
-Markdown files can include simple frontmatter:
-
-```md
----
-title: Calm deployment
-description: Deployment notes for calm static sites.
-date: 2026-06-16
-published: true
-homePage: true
-tags:
-  - ssg
-  - deployment
----
-
-# Calm deployment
-
-Page content.
-```
-
-## API
+## Usage
 
 ```ts
 import { buildStaticSite } from '@vyriy/ssg';
 
-await buildStaticSite({
-  contentPath: 'site',
-  outputPath: 'dist',
-  siteUrl: 'https://vyriy.dev',
-});
-```
-
-Custom sections are supported:
-
-```ts
-await buildStaticSite({
-  sections: [
-    {
-      path: 'articles',
-      title: 'Articles',
-    },
-  ],
-});
+await buildStaticSite();
 ```
 
-Set `index: false` when a section should generate individual pages and search data without its own paginated catalog.
+By default, `buildStaticSite` renders:
+
+- `site/home/README.md` to `dist/index.html`
+- `site/docs/README.md` to `dist/docs/index.html`
+- `site/docs/**/README.md` to `dist/docs/**/index.html`
+- `site/blog/**/README.md` to `dist/blog/**/index.html`
+- `site/examples/**/README.md` to `dist/examples/**/index.html`
+- generated docs, blog, and example entries to sibling `.md` files such as
+  `dist/docs/ssg.md`, `dist/blog/post.md`, and `dist/examples/demo.md`
+- `site/consulting/README.md` to `dist/consulting/index.html`
+- `dist/blog/index.html` and `dist/examples/index.html` catalog pages, plus
+  numbered catalog pages when pagination is needed
+- `dist/404.html`
+- `dist/sitemap.xml`, `dist/robots.txt`, and `dist/llms.txt`
+
+When the script is executed from `dist`, it reads content from the parent project
+directory and writes into the current `dist` directory. Blog, documentation, and
+example entries with `published: false` are skipped.
+
+Vyriy SSG can emit `.md` versions of generated content pages next to HTML
+pages. This gives agents, LLM tools, and crawlers a clean text representation of
+docs, blog posts, and examples while preserving the normal human-facing HTML
+site. Generated content HTML pages also include a
+`<link rel="alternate" type="text/markdown">` tag that points to the Markdown
+artifact. The generated home page includes lightweight discovery `<link>` tags
+for `/llms.txt`, `/docs/`, and `/sitemap.xml`.
 
 ## Exports
 
-- `buildStaticSite(options)` builds the static site.
-- `runSsgCli(args)` runs the CLI programmatically.
-- `parsePage(markdown)` parses page frontmatter and fallback metadata.
-- `renderMarkdown(markdown)` renders Markdown through `react-markdown`, `remark-gfm`, and `rehype-highlight`.
-- `renderSitemap(urls, siteUrl)` renders sitemap XML.
-- `renderRobotsTxt(siteUrl)` renders robots.txt.
+- `buildStaticSite` builds the static home page, documentation page, consulting
+  page, 404 page, blog pages, example pages, and section index pages.
+- `renderRobotsTxt` and `writeRobotsTxt` create a crawler policy that allows all
+  indexing, points to the sitemap, and emits permissive content signals for
+  search and AI usage.
+- `renderLlmTxt` and `writeLlmTxt` create a readable LLM index for main pages
+  and published content sections.
+- `getWebPageJsonLd` and `renderJsonLdScript` create safe WebPage JSON-LD for
+  rendered HTML documents.
+- `renderMarkdownPage`, `writeMarkdownPage`, and `getMarkdownOutputPath` create
+  agent-readable Markdown artifacts for generated content pages.
+- `BuildStaticSiteOptions` configures source, output, stylesheet, Google
+  Analytics measurement ID, and current working directory paths.
+- `PageData` describes parsed Markdown page content and metadata.

package/build-static-site.js

@@ -0,0 +1,191 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { getHomePageFeaturedContent, getRelatedDocumentsMap, getSiteSearchDocuments, writeContentData, } from './content-data.js';
+import { buildContentEntries, buildContentSection, writeContentEntryDocuments } from './content-section.js';
+import { writeLlmTxt } from './llm.js';
+import { parsePage } from './parse-page.js';
+import { getStaticSitePaths } from './paths.js';
+import { renderNotFoundPage, renderPage, renderSearchPage } from './render-page.js';
+import { writeRobotsTxt } from './robots.js';
+import { writeSitemap } from './sitemap.js';
+const homeSocialMetadata = {
+    description: 'Calm architecture for cloud-ready applications. Small explicit pieces, clear boundaries, predictable behavior.',
+    imageAlt: 'Vyriy calm architecture diagram with modular cloud-ready software blocks.',
+    imagePath: '/assets/vyriy-calm-architecture.png',
+    siteName: 'Vyriy',
+    title: 'Vyriy - Calm Architecture',
+};
+export const buildStaticSite = async (options = {}) => {
+    const paths = getStaticSitePaths(options.cwd ?? process.cwd());
+    const sourcePath = options.sourcePath ?? paths.sourcePath;
+    const outputPath = options.outputPath ?? paths.outputPath;
+    const page = parsePage(await readFile(sourcePath, 'utf8'));
+    const consultingPage = parsePage(await readFile(paths.consultingSourcePath, 'utf8'));
+    const docPage = parsePage(await readFile(paths.docSourcePath, 'utf8'));
+    const consultingDocument = renderPage(consultingPage, {
+        canonicalPath: '/consulting/',
+        googleAnalyticsMeasurementId: options.googleAnalyticsMeasurementId,
+        siteUrl: options.siteUrl,
+        stylesheetContent: options.stylesheetContent,
+        stylesheetHref: options.stylesheetHref,
+    });
+    const docDocument = renderPage(docPage, {
+        canonicalPath: '/docs/',
+        googleAnalyticsMeasurementId: options.googleAnalyticsMeasurementId,
+        siteUrl: options.siteUrl,
+        stylesheetContent: options.stylesheetContent,
+        stylesheetHref: options.stylesheetHref,
+    });
+    const notFoundDocument = renderNotFoundPage({
+        googleAnalyticsMeasurementId: options.googleAnalyticsMeasurementId,
+        siteUrl: options.siteUrl,
+        stylesheetContent: options.stylesheetContent,
+        stylesheetHref: options.stylesheetHref,
+    });
+    const searchDocument = renderSearchPage({
+        googleAnalyticsMeasurementId: options.googleAnalyticsMeasurementId,
+        siteUrl: options.siteUrl,
+        stylesheetContent: options.stylesheetContent,
+        stylesheetHref: options.stylesheetHref,
+    });
+    const searchOutputPath = join(paths.outputDirectory, 'search/index.html');
+    await mkdir(dirname(outputPath), {
+        recursive: true,
+    });
+    await mkdir(dirname(paths.consultingOutputPath), {
+        recursive: true,
+    });
+    await mkdir(dirname(paths.docOutputPath), {
+        recursive: true,
+    });
+    await mkdir(paths.outputDirectory, {
+        recursive: true,
+    });
+    await mkdir(dirname(searchOutputPath), {
+        recursive: true,
+    });
+    await writeFile(paths.consultingOutputPath, consultingDocument);
+    await writeFile(paths.docOutputPath, docDocument);
+    await writeFile(join(paths.outputDirectory, '404.html'), notFoundDocument);
+    await writeFile(searchOutputPath, searchDocument);
+    const blogSection = await buildContentSection('blog', paths.projectRoot, paths.outputDirectory, options.stylesheetHref, options.siteUrl, options.stylesheetContent, options.googleAnalyticsMeasurementId);
+    const examplesSection = await buildContentSection('examples', paths.projectRoot, paths.outputDirectory, options.stylesheetHref, options.siteUrl, options.stylesheetContent, options.googleAnalyticsMeasurementId);
+    const docsEntries = await buildContentEntries('docs', paths.projectRoot);
+    const docsRootEntry = {
+        ...docPage,
+        href: '/docs/',
+        slug: '',
+    };
+    const contentSections = [
+        {
+            entries: blogSection.entries,
+            section: 'blog',
+        },
+        {
+            entries: [
+                docsRootEntry,
+                ...docsEntries,
+            ],
+            section: 'docs',
+        },
+        {
+            entries: examplesSection.entries,
+            section: 'examples',
+        },
+    ];
+    const relatedDocuments = getRelatedDocumentsMap(getSiteSearchDocuments(contentSections));
+    const featured = getHomePageFeaturedContent(contentSections);
+    const document = renderPage(page, {
+        canonicalPath: '/',
+        discoveryLinks: [
+            {
+                href: '/llms.txt',
+                rel: 'describedby',
+                type: 'text/markdown',
+            },
+            {
+                href: '/docs/',
+                rel: 'service-doc',
+                type: 'text/html',
+            },
+            {
+                href: '/sitemap.xml',
+                rel: 'sitemap',
+                type: 'application/xml',
+            },
+        ],
+        featured,
+        googleAnalyticsMeasurementId: options.googleAnalyticsMeasurementId,
+        siteUrl: options.siteUrl,
+        socialMetadata: homeSocialMetadata,
+        stylesheetContent: options.stylesheetContent,
+        stylesheetHref: options.stylesheetHref,
+    });
+    await writeFile(outputPath, document);
+    await Promise.all([
+        writeContentEntryDocuments('blog', blogSection.entries, paths.outputDirectory, {
+            googleAnalyticsMeasurementId: options.googleAnalyticsMeasurementId,
+            relatedDocuments,
+            siteUrl: options.siteUrl,
+            stylesheetContent: options.stylesheetContent,
+            stylesheetHref: options.stylesheetHref,
+        }),
+        writeContentEntryDocuments('examples', examplesSection.entries, paths.outputDirectory, {
+            googleAnalyticsMeasurementId: options.googleAnalyticsMeasurementId,
+            relatedDocuments,
+            siteUrl: options.siteUrl,
+            stylesheetContent: options.stylesheetContent,
+            stylesheetHref: options.stylesheetHref,
+        }),
+        writeContentEntryDocuments('docs', docsEntries, paths.outputDirectory, {
+            googleAnalyticsMeasurementId: options.googleAnalyticsMeasurementId,
+            relatedDocuments,
+            siteUrl: options.siteUrl,
+            stylesheetContent: options.stylesheetContent,
+            stylesheetHref: options.stylesheetHref,
+        }),
+    ]);
+    await writeContentData(contentSections, paths.outputDirectory);
+    await writeSitemap(paths.outputDirectory, [
+        {
+            path: '/',
+        },
+        {
+            path: '/consulting/',
+        },
+        {
+            path: '/docs/',
+        },
+        ...docsEntries.map((entry) => ({
+            path: entry.href,
+        })),
+        ...blogSection.indexPaths.map((path) => ({
+            path,
+        })),
+        ...blogSection.entries.map((entry) => ({
+            path: entry.href,
+        })),
+        ...examplesSection.indexPaths.map((path) => ({
+            path,
+        })),
+        ...examplesSection.entries.map((entry) => ({
+            path: entry.href,
+        })),
+    ], options.siteUrl);
+    await writeRobotsTxt(paths.outputDirectory, options.siteUrl);
+    await writeLlmTxt(paths.outputDirectory, {
+        pages: [
+            {
+                description: page.description,
+                path: '/',
+                title: page.title,
+            },
+            {
+                description: consultingPage.description,
+                path: '/consulting/',
+                title: consultingPage.title,
+            },
+        ],
+        sections: contentSections,
+    }, options.siteUrl);
+};

package/components.d.ts

@@ -0,0 +1,40 @@
+import type { ComponentProps, FC, ReactNode } from 'react';
+type CardProps = ComponentProps<'article'> & {
+    readonly date?: string;
+    readonly description: string;
+    readonly href: string;
+    readonly tags?: readonly string[];
+    readonly title: string;
+};
+type CatalogProps = {
+    readonly content: ReactNode;
+    readonly paginate: {
+        readonly getHref?: (page: number) => string;
+        readonly page: number;
+        readonly pages: number;
+    };
+};
+type PageRelatedItem = {
+    readonly description: string;
+    readonly href: string;
+    readonly title: string;
+};
+type PageProps = {
+    readonly content: ReactNode;
+    readonly featured?: readonly PageRelatedItem[];
+    readonly related?: readonly PageRelatedItem[];
+    readonly tags?: readonly string[];
+};
+type SearchPageProps = {
+    readonly documentsUrl?: string;
+    readonly indexUrl?: string;
+    readonly miniSearchScriptUrl?: string;
+};
+export declare const Card: FC<CardProps>;
+export declare const Page: FC<PageProps>;
+export declare const Catalog: FC<CatalogProps>;
+export declare const NotFoundPage: FC<{
+    readonly homeHref?: string;
+}>;
+export declare const SearchPage: FC<SearchPageProps>;
+export {};