simple-site-generator 0.1.2 → 0.2.0

package/dist/pages/page-schema.js

@@ -0,0 +1,161 @@
+import { z } from 'zod';
+/**
+ * The page frontmatter contract.
+ *
+ * This is the guard that stops the class of bug the old template suffered from:
+ * a page whose frontmatter is subtly wrong builds and deploys, and the damage is
+ * only visible on the live site. `ssg check` runs this before a build, so a typo
+ * fails in the terminal instead of in production.
+ */
+/** Tags the templates understand. An unknown tag means a menu entry silently vanishes. */
+export const PAGE_TAGS = ['menu', 'footer', 'contact'];
+export const pageFrontmatterSchema = z.object({
+    /** Route segment: `undefined`-free, because the router builds `/${id}` from it. */
+    id: z.string().min(1, 'id must not be empty'),
+    /** Used verbatim as the `<h1>`; the `<title>` unless `headTitle` overrides it. */
+    title: z.string().min(1, 'title is required'),
+    /**
+     * The page's `<title>`, used verbatim.
+     *
+     * Without it the document title names the site as well — `<site> | <title>` —
+     * which is right for every page except the front page, whose head title is the
+     * site name and whose `<h1>` is a sentence.
+     */
+    headTitle: z.string().min(1, 'headTitle must not be empty').optional(),
+    /** The meta description. Required: a page without one is invisible to search. */
+    description: z.string().min(1, 'description is required'),
+    /** Navigation label; falls back to `title` in the templates. */
+    label: z.string().min(1).optional(),
+    /** Sort weight; the home page is always first. */
+    order: z.number().optional(),
+    tags: z.array(z.enum(['menu', 'footer', 'contact'])).optional(),
+    /** Keep the page out of the index and the sitemap. */
+    noindex: z.boolean().optional(),
+    /** Render client-side only (for pages that cannot be prerendered). */
+    noSsr: z.boolean().optional(),
+    /** Template component to render, e.g. `Landing`. */
+    page: z.string().min(1).optional(),
+    image: z.string().min(1).optional(),
+    breadcrumbs: z.array(z.string().min(1)).optional(),
+    faq: z
+        .array(z.object({
+        question: z.string().min(1),
+        answer: z.string().min(1)
+    }))
+        .optional(),
+    cta: z
+        .object({
+        message: z.string().min(1),
+        route: z.string().min(1).optional(),
+        /**
+         * The quieter action beside the primary one, rendered as an outline.
+         *
+         * Validated here as well as typed, because a malformed second action is
+         * invisible: the template only checks that `message` is present, so a
+         * missing `message` would drop the button without a word.
+         */
+        secondary: z
+            .object({
+            message: z.string().min(1),
+            route: z.string().min(1).optional()
+        })
+            .optional()
+    })
+        .optional(),
+    /**
+     * The hero's animated process graphic (`shared/HeroDemo.vue`).
+     *
+     * Two stops minimum: the graphic draws a route between them, and one stop is a
+     * dot with a label, not a process. Rejected here rather than rendered badly,
+     * because the templates degrade silently — a malformed `demo` would just show
+     * nothing.
+     */
+    demo: z
+        .object({
+        steps: z.array(z.string().min(1)).min(2),
+        label: z.string().min(1).optional()
+    })
+        .optional(),
+    /**
+     * The principles band (`shared/PrincipleGrid.vue`).
+     *
+     * At least one item, and every item needs both halves: the component renders a
+     * heading and a body per card, so a title with no text is an empty box in the
+     * layout. Rejected here rather than rendered badly, because a malformed
+     * `principles` shows nothing at all.
+     */
+    principles: z
+        .object({
+        heading: z.string().min(1).optional(),
+        leading: z.string().min(1).optional(),
+        items: z
+            .array(z.object({
+            title: z.string().min(1),
+            text: z.string().min(1)
+        }))
+            .min(1),
+        note: z.string().min(1).optional()
+    })
+        .optional(),
+    /** Ids of pages nested under this one in the navigation. */
+    subpages: z.array(z.string().min(1)).optional(),
+    lists: z.array(z.unknown()).optional(),
+    cards: z.array(z.unknown()).optional(),
+    images: z.array(z.unknown()).optional(),
+    videos: z.array(z.unknown()).optional(),
+    extra: z.record(z.string(), z.unknown()).optional()
+});
+/** Validate one page's frontmatter, returning every problem rather than the first. */
+export function validatePage(file, data) {
+    const result = pageFrontmatterSchema.safeParse(data);
+    if (result.success)
+        return [];
+    return result.error.issues.map((issue) => ({
+        file,
+        message: issue.path.length
+            ? `${issue.path.join('.')}: ${issue.message}`
+            : issue.message
+    }));
+}
+/**
+ * Validate the collection as a whole.
+ *
+ * Uniqueness and referential integrity are only checkable with every page in
+ * hand: two files claiming the same `id` produce two identical routes (one
+ * silently unreachable), and a `subpages` entry pointing at a missing page
+ * produces a dead navigation link.
+ */
+export function validateCollection(pages) {
+    const issues = [];
+    const seen = new Map();
+    for (const page of pages) {
+        const id = page.data?.id;
+        if (typeof id !== 'string' || !id)
+            continue;
+        const existing = seen.get(id);
+        if (existing) {
+            issues.push({
+                file: page.file,
+                message: `duplicate id "${id}" — already used by ${existing}`
+            });
+        }
+        else {
+            seen.set(id, page.file);
+        }
+    }
+    for (const page of pages) {
+        const data = page.data;
+        const subpages = data?.subpages;
+        if (!Array.isArray(subpages))
+            continue;
+        for (const childId of subpages) {
+            if (typeof childId !== 'string' || seen.has(childId))
+                continue;
+            issues.push({
+                file: page.file,
+                message: `subpages references "${childId}", which no page declares as its id`
+            });
+        }
+    }
+    return issues;
+}

package/dist/pages/render-page.js

@@ -0,0 +1,46 @@
+import matter from 'gray-matter';
+/**
+ * Build the markdown source for a new page.
+ *
+ * Frontmatter is serialised by `gray-matter`, so keys it does not understand are
+ * preserved and the output round-trips through the same parser `ssg check` uses.
+ * The body is a placeholder that already respects the heading contract — the
+ * page template owns the `<h1>`, so content starts at `##`.
+ */
+export function renderPage(input) {
+    const data = {
+        id: input.id,
+        title: input.title,
+        description: input.description
+    };
+    if (input.label)
+        data.label = input.label;
+    if (input.order !== undefined)
+        data.order = input.order;
+    if (input.tags?.length)
+        data.tags = input.tags;
+    if (input.page)
+        data.page = input.page;
+    const body = [
+        '## Overview',
+        '',
+        `${input.title} — replace this with the page content.`,
+        '',
+        '<!--',
+        '  Writing notes:',
+        '  - The page title above is already the <h1>. Start body headings at "##".',
+        "  - Answer the page's main question in the first paragraph.",
+        '  - See CONTENT-BLUEPRINT.md for the service x location matrix and',
+        '    internal-linking rules.',
+        '-->',
+        ''
+    ].join('\n');
+    return matter.stringify(body, data);
+}
+/**
+ * Derive a page id from a file path, so `src/pages/GettingStarted/Install.md`
+ * becomes `GettingStarted/Install`.
+ */
+export function idFromPath(relativePath) {
+    return relativePath.replace(/\\/g, '/').replace(/\.md$/, '');
+}

package/dist/paths.js

@@ -0,0 +1,27 @@
+import { join, resolve } from 'node:path';
+/**
+ * Where things live inside a generated project.
+ *
+ * Every command resolves paths through here so `ssg check`, `ssg build` and
+ * `ssg verify` cannot disagree about which directory they are reading.
+ */
+/** The generated project root. */
+export function appDir(cwd = process.cwd()) {
+    return resolve(cwd);
+}
+/** `src/pages` — the single source of truth for the site's pages. */
+export function pagesDir(app = appDir()) {
+    return join(app, 'src', 'pages');
+}
+/** `public` — copied verbatim into the build output. */
+export function publicDir(app = appDir()) {
+    return join(app, 'public');
+}
+/** `dist/static` — the SSG output that gets deployed. */
+export function distDir(app = appDir()) {
+    return join(app, 'dist', 'static');
+}
+/** Where the generated app's `vitrify.config.ts` lives. */
+export function configPath(app = appDir()) {
+    return join(app, 'vitrify.config.ts');
+}

package/dist/types/cli.d.ts

@@ -1 +1,2 @@
 #!/usr/bin/env node
+export {};

package/dist/types/commands/add-page.d.ts

@@ -0,0 +1,26 @@
+import { PAGE_TAGS } from '../pages/page-schema.js';
+import type { PageTag } from '../pages/page-schema.js';
+export interface AddPageOptions {
+    /** Route segment: `services`, or `services/leaks` for a nested page. */
+    id: string;
+    title?: string;
+    description?: string;
+    label?: string;
+    order?: number;
+    tags?: PageTag[];
+    page?: string;
+    app?: string;
+}
+export interface AddPageResult {
+    file: string;
+    id: string;
+}
+/**
+ * `ssg add-page` — create a page with valid frontmatter.
+ *
+ * Generates the file through the same `renderPage` the schema validates, so a
+ * page created by the CLI cannot fail `ssg check`. It refuses to overwrite: an
+ * agent re-running a command must never silently destroy content.
+ */
+export declare function addPage(options: AddPageOptions): Promise<AddPageResult>;
+export { PAGE_TAGS };

package/dist/types/commands/build.d.ts

@@ -0,0 +1,18 @@
+export interface BuildOptions {
+    app?: string;
+    /** Extra arguments forwarded to `vitrify build`. */
+    passthrough?: string[];
+}
+export interface BuildResult {
+    code: number;
+    outputDir: string;
+}
+/**
+ * `ssg build` — delegate to `vitrify build -m ssg`.
+ *
+ * Deliberately a thin wrapper: the build belongs to vitrify, and reimplementing
+ * it here would fork the build pipeline from the one the dev server uses. The
+ * value this command adds is the fixed SSG mode, the resolved output path, and a
+ * single place for the agent-facing instructions to point at.
+ */
+export declare function build(options?: BuildOptions): Promise<BuildResult>;

package/dist/types/commands/check.d.ts

@@ -0,0 +1,20 @@
+import { type PageIssue } from '../pages/page-schema.js';
+export interface CheckOptions {
+    app?: string;
+}
+export interface CheckResult {
+    ok: boolean;
+    pages: number;
+    issues: PageIssue[];
+}
+/**
+ * `ssg check` — validate every page against the frontmatter contract.
+ *
+ * This is the guard that stops the defect class the old template suffered from:
+ * frontmatter that is subtly wrong still builds, and the damage only shows on the
+ * live site. Running it before a build turns that into a terminal error.
+ *
+ * An empty pages directory is a warning, not a failure — a brand new project has
+ * no pages yet, and failing there would be hostile.
+ */
+export declare function check(options?: CheckOptions): Promise<CheckResult>;

package/dist/types/commands/init.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `ssg init` — scaffold a new site from the app template.
+ *
+ * Replaces the old `create-simple-site-generator` package. Prompts only when the
+ * process is attached to a TTY **and** `--yes` was not passed, so an agent can
+ * run it non-interactively and get the same project every time.
+ */
+export declare const TEMPLATES: readonly ["docs", "landing", "business", "plain"];
+export type TemplateName = (typeof TEMPLATES)[number];
+export interface InitOptions {
+    /** Directory to create the project in. */
+    directory?: string;
+    template?: TemplateName;
+    /** npm package name. */
+    name?: string;
+    /** Displayed site name, used as the product name and default `<title>`. */
+    productName?: string;
+    /** Absolute site origin, e.g. `https://example.com`. */
+    url?: string;
+    description?: string;
+    author?: string;
+    /** Skip every prompt and use defaults. */
+    yes?: boolean;
+    /** Force the interactive prompts even when stdin is not a TTY. */
+    interactive?: boolean;
+}
+export interface InitResult {
+    directory: string;
+    template: TemplateName;
+}
+/**
+ * Resolve options, prompting only when it is safe and wanted.
+ *
+ * A non-interactive run must never hang waiting on stdin, which is why the
+ * `isTTY` check comes before any prompt.
+ */
+export declare function resolveInitOptions(options: InitOptions): Promise<Required<Omit<InitOptions, 'yes' | 'interactive'>>>;
+export declare function init(options?: InitOptions): Promise<InitResult>;
+/** Confirm overwriting a non-empty directory (interactive runs only). */
+export declare function confirmOverwrite(directory: string): Promise<boolean>;

package/dist/types/commands/verify.d.ts

@@ -0,0 +1,47 @@
+import { type Budgets } from '../verify/budgets.js';
+export interface VerifyOptions {
+    app?: string;
+    /** Absolute site origin, so canonical URLs can be checked against it. */
+    siteUrl?: string;
+    budgets?: Budgets;
+    /**
+     * Skip the Lighthouse half. Used where no Chromium is available — the
+     * deterministic SEO/byte checks still run and still gate.
+     */
+    skipLighthouse?: boolean;
+    /**
+     * Glob patterns, relative to the output root, of HTML files to leave out of
+     * the SEO surface check. A third-party drop-in that happens to end in `.html`
+     * (a Google site-verification file, for instance) is not a page and cannot
+     * carry a title, canonical or JSON-LD.
+     */
+    ignore?: string[];
+    /** Chromium binary for Lighthouse. */
+    chromePath?: string;
+}
+export interface VerifyResult {
+    ok: boolean;
+    /** Hard failures — a non-zero exit. */
+    issues: string[];
+    /** Advisory: reported, but does not fail the run. */
+    warnings: string[];
+    report: {
+        pages: number;
+        budgets: {
+            js: number;
+            css: number;
+        };
+        scores?: Record<string, number>;
+    };
+}
+/**
+ * `ssg verify` — prove the built site is correct and fast.
+ *
+ * Two tiers by design: the SEO surface and the byte budgets are deterministic
+ * and **fail** the run; Lighthouse performance only **warns**, because it varies
+ * with the measuring machine and a gate that fails randomly gets switched off.
+ *
+ * It does not build. `verify` measures what is on disk, so it can be run against
+ * a deployed artifact as well as a local build.
+ */
+export declare function verify(options?: VerifyOptions): Promise<VerifyResult>;

package/dist/types/pages/page-schema.d.ts

@@ -0,0 +1,81 @@
+import { z } from 'zod';
+/**
+ * The page frontmatter contract.
+ *
+ * This is the guard that stops the class of bug the old template suffered from:
+ * a page whose frontmatter is subtly wrong builds and deploys, and the damage is
+ * only visible on the live site. `ssg check` runs this before a build, so a typo
+ * fails in the terminal instead of in production.
+ */
+/** Tags the templates understand. An unknown tag means a menu entry silently vanishes. */
+export declare const PAGE_TAGS: readonly ["menu", "footer", "contact"];
+export type PageTag = (typeof PAGE_TAGS)[number];
+export declare const pageFrontmatterSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    headTitle: z.ZodOptional<z.ZodString>;
+    description: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    order: z.ZodOptional<z.ZodNumber>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        menu: "menu";
+        footer: "footer";
+        contact: "contact";
+    }>>>;
+    noindex: z.ZodOptional<z.ZodBoolean>;
+    noSsr: z.ZodOptional<z.ZodBoolean>;
+    page: z.ZodOptional<z.ZodString>;
+    image: z.ZodOptional<z.ZodString>;
+    breadcrumbs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    faq: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        question: z.ZodString;
+        answer: z.ZodString;
+    }, z.core.$strip>>>;
+    cta: z.ZodOptional<z.ZodObject<{
+        message: z.ZodString;
+        route: z.ZodOptional<z.ZodString>;
+        secondary: z.ZodOptional<z.ZodObject<{
+            message: z.ZodString;
+            route: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    demo: z.ZodOptional<z.ZodObject<{
+        steps: z.ZodArray<z.ZodString>;
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    principles: z.ZodOptional<z.ZodObject<{
+        heading: z.ZodOptional<z.ZodString>;
+        leading: z.ZodOptional<z.ZodString>;
+        items: z.ZodArray<z.ZodObject<{
+            title: z.ZodString;
+            text: z.ZodString;
+        }, z.core.$strip>>;
+        note: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    subpages: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    lists: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    cards: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    images: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    videos: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    extra: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type PageFrontmatter = z.infer<typeof pageFrontmatterSchema>;
+export interface PageIssue {
+    /** Project-relative path of the offending page. */
+    file: string;
+    message: string;
+}
+/** Validate one page's frontmatter, returning every problem rather than the first. */
+export declare function validatePage(file: string, data: unknown): PageIssue[];
+/**
+ * Validate the collection as a whole.
+ *
+ * Uniqueness and referential integrity are only checkable with every page in
+ * hand: two files claiming the same `id` produce two identical routes (one
+ * silently unreachable), and a `subpages` entry pointing at a missing page
+ * produces a dead navigation link.
+ */
+export declare function validateCollection(pages: {
+    file: string;
+    data: unknown;
+}[]): PageIssue[];

package/dist/types/pages/render-page.d.ts

@@ -0,0 +1,26 @@
+import type { PageTag } from './page-schema.js';
+export interface NewPageInput {
+    /** Route segment, e.g. `services` or `services/leaks`. */
+    id: string;
+    title: string;
+    description: string;
+    label?: string;
+    order?: number;
+    tags?: PageTag[];
+    /** Template component to render, e.g. `Landing`. */
+    page?: string;
+}
+/**
+ * Build the markdown source for a new page.
+ *
+ * Frontmatter is serialised by `gray-matter`, so keys it does not understand are
+ * preserved and the output round-trips through the same parser `ssg check` uses.
+ * The body is a placeholder that already respects the heading contract — the
+ * page template owns the `<h1>`, so content starts at `##`.
+ */
+export declare function renderPage(input: NewPageInput): string;
+/**
+ * Derive a page id from a file path, so `src/pages/GettingStarted/Install.md`
+ * becomes `GettingStarted/Install`.
+ */
+export declare function idFromPath(relativePath: string): string;

package/dist/types/paths.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Where things live inside a generated project.
+ *
+ * Every command resolves paths through here so `ssg check`, `ssg build` and
+ * `ssg verify` cannot disagree about which directory they are reading.
+ */
+/** The generated project root. */
+export declare function appDir(cwd?: string): string;
+/** `src/pages` — the single source of truth for the site's pages. */
+export declare function pagesDir(app?: string): string;
+/** `public` — copied verbatim into the build output. */
+export declare function publicDir(app?: string): string;
+/** `dist/static` — the SSG output that gets deployed. */
+export declare function distDir(app?: string): string;
+/** Where the generated app's `vitrify.config.ts` lives. */
+export declare function configPath(app?: string): string;

package/dist/types/verify/budgets.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Transfer-size budgets.
+ *
+ * The tiered policy from the plan: byte budgets are **hard** failures because
+ * they are deterministic and directly measurable, while Lighthouse performance
+ * is a **warn** because it varies with machine and network simulation. A gate
+ * that fails randomly gets disabled, so only the deterministic half blocks.
+ */
+export interface ResourceEntry {
+    /**
+     * Lighthouse's `resource-summary` resource type: `script`, `stylesheet`,
+     * `image`, `font`, `document`, `media`, `other`, or the aggregate `total`.
+     *
+     * Aggregating by type rather than by URL matters: the per-request audit
+     * (`network-requests`) only reports requests Lighthouse actually observed in
+     * its trace, so a warm HTTP cache makes it under-report — and an under-reported
+     * budget is a gate that passes when it should fail.
+     */
+    resourceType: string;
+    /** Bytes over the wire, as reported by Lighthouse's resource summary. */
+    transferSize: number;
+}
+export interface Budgets {
+    /** Hard ceiling for transferred JavaScript, in bytes. */
+    jsBytes: number;
+    /** Hard ceiling for transferred CSS, in bytes. */
+    cssBytes: number;
+}
+export declare const DEFAULT_BUDGETS: Budgets;
+export interface BudgetResult {
+    ok: boolean;
+    /** Total transferred bytes per resource type. */
+    totals: {
+        js: number;
+        css: number;
+    };
+    issues: string[];
+}
+export declare function formatBytes(bytes: number): string;
+/**
+ * Evaluate transferred bytes against the budgets.
+ *
+ * `transferSize` (compressed, over the wire) is used rather than decoded size,
+ * because that is what the visitor actually pays for.
+ */
+export declare function evaluateBudgets(resources: ResourceEntry[], budgets?: Budgets): BudgetResult;
+/** Scores below these are a warning, not a failure (see the tiering note above). */
+/**
+ * Warn when a measured total is within this fraction of its ceiling.
+ *
+ * A budget a site is always near is a cliff: everything passes until the day a
+ * dependency bump pushes it over, and then the failure looks sudden. A warning at
+ * 10% remaining turns "no headroom" into something visible on every run.
+ *
+ * Deliberately not a failure. Being inside the budget is not a defect, and the
+ * deterministic tier is reserved for things that are.
+ */
+export declare const HEADROOM_WARNING_FRACTION = 0.1;
+export declare function budgetHeadroomWarnings(totals: {
+    js: number;
+    css: number;
+}, budgets?: Budgets, fraction?: number): string[];
+export declare const DEFAULT_SCORE_TARGETS: {
+    /** Must equal `required` exactly — anything lower is a defect, not a trade-off. */
+    readonly required: {
+        readonly accessibility: 100;
+        readonly 'best-practices': 100;
+        readonly seo: 100;
+    };
+    /** A warning threshold: performance varies with the measuring machine. */
+    readonly warnBelow: {
+        readonly performance: 90;
+    };
+};
+export interface ScoreResult {
+    ok: boolean;
+    warnings: string[];
+    issues: string[];
+}
+export declare function evaluateScores(scores: Record<string, number>, targets?: {
+    required: Record<string, number>;
+    warnBelow: Record<string, number>;
+}): ScoreResult;
+/**
+ * Measure the transferred JavaScript and CSS of a built site **from disk**.
+ *
+ * This is deliberately not read from Lighthouse. Its `resource-summary` audit
+ * reports `transferSize: 0` when the trace captures no network activity
+ * (reproduced in a sandboxed Chromium), and a budget that measures nothing
+ * silently reports "OK" — a gate that cannot fail is worse than no gate.
+ * Reading the built files is deterministic, needs no browser, and lets the byte
+ * half of `ssg verify` run with `--no-lighthouse`.
+ *
+ * Sizes are gzipped, because that is what actually crosses the network.
+ */
+export declare function measureBuildAssets(root: string): Promise<{
+    js: number;
+    css: number;
+    files: {
+        file: string;
+        bytes: number;
+        type: 'js' | 'css';
+    }[];
+}>;
+/**
+ * Evaluate measured byte totals against the budgets.
+ *
+ * An all-zero measurement is **no measurement**, not a pass: a built site always
+ * ships some JavaScript, so zero means the measurement failed.
+ */
+export declare function evaluateTotals(totals: {
+    js: number;
+    css: number;
+}, budgets?: Budgets): BudgetResult;