@doxbrix/doxloop 0.1.5 → 0.2.0

package/dist/evidence.js

@@ -0,0 +1,175 @@
+import { writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { DoxloopError } from './errors.js';
+import { pathExists, readJson } from './fs.js';
+import { matchesGlob } from './globs.js';
+export const EVIDENCE_MAP_FILE = join('.doxloop', 'evidence-map.json');
+/**
+ * The evidence map records which configured source produced each page, so
+ * staleness can be attributed to individual pages without starting an agent.
+ * It is committed, so a malformed file fails closed rather than being ignored.
+ */
+export async function readEvidenceMap(root) {
+    const path = join(root, EVIDENCE_MAP_FILE);
+    if (!(await pathExists(path)))
+        return undefined;
+    const map = normalizeEvidenceConfidence(await readJson(path));
+    if (!isEvidenceMap(map)) {
+        throw new DoxloopError(`${EVIDENCE_MAP_FILE} has an unsupported format. Delete it and run \`doxloop update\` to rebuild it.`);
+    }
+    return map;
+}
+/**
+ * A page whose evidence the writer found contradicted needs a person to look
+ * at it; "contradicted" is the claim-level word for that, and an agent that
+ * has just marked a claim contradicted sometimes writes the same word as the
+ * page's confidence. That is a wording slip, not a broken file: refusing the
+ * whole map for it discarded complete generation runs.
+ */
+function normalizeEvidenceConfidence(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return value;
+    const pages = value.pages;
+    if (!pages || typeof pages !== 'object' || Array.isArray(pages))
+        return value;
+    let changed = false;
+    const normalized = Object.fromEntries(Object.entries(pages).map(([page, evidence]) => {
+        if (!evidence || typeof evidence !== 'object' || Array.isArray(evidence))
+            return [page, evidence];
+        const confidence = evidence.confidence;
+        if (confidence !== 'contradicted')
+            return [page, evidence];
+        changed = true;
+        return [page, { ...evidence, confidence: 'needs-human' }];
+    }));
+    return changed ? { ...value, pages: normalized } : value;
+}
+export async function writeEvidenceMap(root, map) {
+    const pages = Object.fromEntries(Object.entries(map.pages).sort(([left], [right]) => left.localeCompare(right)));
+    await writeFile(join(root, EVIDENCE_MAP_FILE), `${JSON.stringify({ schemaVersion: 1, pages }, null, 2)}\n`, 'utf8');
+}
+/**
+ * A run that ends by recording the sync baseline has just verified its pages
+ * against that baseline. Stamp each verified page with the revision it was
+ * checked against, so coverage and drift can tell "verified at the current
+ * baseline" from "verified at some point"; without it every generated page
+ * counted as unverified. Existing stamps are kept. Returns the pages stamped.
+ */
+export async function stampVerifiedRevisions(root, state) {
+    const map = await readEvidenceMap(root);
+    if (!map)
+        return 0;
+    let stamped = 0;
+    for (const evidence of Object.values(map.pages)) {
+        if (evidence.confidence !== 'verified')
+            continue;
+        let changed = false;
+        for (const entry of evidence.sources) {
+            const record = state.sources[entry.source];
+            if (!record?.commit || evidence.verifiedAt?.[entry.source])
+                continue;
+            evidence.verifiedAt = { ...evidence.verifiedAt, [entry.source]: record.commit };
+            changed = true;
+        }
+        if (changed)
+            stamped += 1;
+    }
+    if (stamped > 0)
+        await writeEvidenceMap(root, map);
+    return stamped;
+}
+/**
+ * Pages that claim behavior from a changed source path, in page order.
+ * An entry naming only a source, with no paths, matches every change in it.
+ */
+export function pagesForChange(map, source, changedPaths) {
+    const matches = new Map();
+    for (const [page, evidence] of Object.entries(map.pages)) {
+        const patterns = evidenceIdentifiers(evidence, source);
+        if (patterns === undefined)
+            continue;
+        const matched = patterns.length === 0
+            ? [...changedPaths]
+            : changedPaths.filter((path) => patterns.some((pattern) => evidenceMatches(path, pattern)));
+        if (matched.length > 0)
+            matches.set(page, matched);
+    }
+    return matches;
+}
+/** Every source name the map attributes at least one page to. */
+export function trackedSources(map) {
+    const names = new Set();
+    for (const evidence of Object.values(map.pages)) {
+        for (const entry of evidence.sources)
+            names.add(entry.source);
+    }
+    return names;
+}
+/** Patterns recorded for one source, or undefined when the page ignores it. */
+function evidenceIdentifiers(evidence, source) {
+    const entries = evidence.sources.filter((entry) => entry.source === source);
+    if (entries.length === 0)
+        return undefined;
+    return entries.flatMap((entry) => [...(entry.paths ?? []), ...(entry.operations ?? [])]);
+}
+/**
+ * A recorded path may be an exact file, a directory, or a glob. A bare
+ * directory is treated as everything below it so `src/routes` keeps matching
+ * after a new file is added to it.
+ */
+function evidenceMatches(path, pattern) {
+    return matchesGlob(path, pattern) || matchesGlob(path, `${pattern}/**`);
+}
+function isEvidenceMap(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const candidate = value;
+    if (candidate.schemaVersion !== 1)
+        return false;
+    if (!candidate.pages ||
+        typeof candidate.pages !== 'object' ||
+        Array.isArray(candidate.pages)) {
+        return false;
+    }
+    return Object.entries(candidate.pages).every(([page, evidence]) => page.trim() !== '' && isPageEvidence(evidence));
+}
+function isPageEvidence(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const evidence = value;
+    if (!Array.isArray(evidence.sources) || !evidence.sources.every(isPageEvidenceSource)) {
+        return false;
+    }
+    if (evidence.confidence !== undefined &&
+        !['verified', 'inferred', 'needs-human'].includes(evidence.confidence)) {
+        return false;
+    }
+    if (evidence.claims !== undefined && !isTextList(evidence.claims))
+        return false;
+    if (evidence.claimVerification !== undefined && (!evidence.claimVerification ||
+        typeof evidence.claimVerification !== 'object' ||
+        Array.isArray(evidence.claimVerification) ||
+        !Object.entries(evidence.claimVerification).every(([claim, state]) => claim.trim() !== '' && ['verified', 'inferred', 'contradicted', 'needs-human'].includes(String(state)))))
+        return false;
+    const revisionMapValid = evidence.verifiedAt === undefined || (typeof evidence.verifiedAt === 'object' &&
+        !Array.isArray(evidence.verifiedAt) &&
+        Object.entries(evidence.verifiedAt).every(([source, revision]) => source.trim() !== '' && typeof revision === 'string' && revision.trim() !== ''));
+    const dateMapValid = evidence.verifiedOn === undefined || (typeof evidence.verifiedOn === 'object' &&
+        !Array.isArray(evidence.verifiedOn) &&
+        Object.entries(evidence.verifiedOn).every(([source, timestamp]) => source.trim() !== '' && typeof timestamp === 'string' && !Number.isNaN(Date.parse(timestamp))));
+    return revisionMapValid && dateMapValid;
+}
+function isPageEvidenceSource(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const entry = value;
+    return (typeof entry.source === 'string' &&
+        entry.source.trim() !== '' &&
+        (entry.paths === undefined || isTextList(entry.paths)) &&
+        (entry.operations === undefined || isTextList(entry.operations)));
+}
+function isTextList(value) {
+    return (Array.isArray(value) &&
+        value.every((item) => typeof item === 'string' && item.trim() !== ''));
+}
+//# sourceMappingURL=evidence.js.map

package/dist/fs.d.ts

@@ -1,6 +1,12 @@
 export declare function assertInside(root: string, candidate: string): string;
-export declare function resolveContainedDirectory(root: string, configuredPath: string, label?: string): Promise<string>;
-export declare function listFiles(root: string, extensions: ReadonlySet<string>): Promise<string[]>;
+export declare function resolveContainedDirectory(root: string, configuredPath: string, label?: string, options?: {
+    allowRoot?: boolean;
+}): Promise<string>;
+export declare function listFiles(root: string, extensions: ReadonlySet<string>, options?: {
+    ignoredDirectories?: ReadonlySet<string>;
+}): Promise<string[]>;
 export declare function readJson<T>(path: string): Promise<T>;
 export declare function pathExists(path: string): Promise<boolean>;
+/** Add machine-local artifacts to .gitignore without losing concurrent additions. */
+export declare function ensureGitignoreEntries(root: string, entries: string[]): Promise<void>;
 //# sourceMappingURL=fs.d.ts.map

package/dist/fs.js

@@ -1,5 +1,5 @@
-import { lstat, readdir, readFile, realpath } from 'node:fs/promises';
-import { extname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { lstat, readdir, readFile, realpath, writeFile } from 'node:fs/promises';
+import { extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { DoxloopError } from './errors.js';
 export function assertInside(root, candidate) {
     const absoluteRoot = resolve(root);
@@ -10,16 +10,19 @@ export function assertInside(root, candidate) {
     }
     return absoluteCandidate;
 }
-export async function resolveContainedDirectory(root, configuredPath, label = 'Directory') {
-    if (configuredPath.trim() === '' ||
+export async function resolveContainedDirectory(root, configuredPath, label = 'Directory', options = {}) {
+    const rootContent = configuredPath === '' && options.allowRoot === true;
+    if ((!rootContent && configuredPath.trim() === '') ||
         isAbsolute(configuredPath) ||
         configuredPath === '.' ||
         configuredPath === '..') {
         throw new DoxloopError(`${label} must be a project-relative directory.`);
     }
     const absoluteRoot = resolve(root);
-    const candidate = assertInside(absoluteRoot, resolve(absoluteRoot, configuredPath));
-    if (candidate === absoluteRoot) {
+    const candidate = rootContent
+        ? absoluteRoot
+        : assertInside(absoluteRoot, resolve(absoluteRoot, configuredPath));
+    if (candidate === absoluteRoot && !rootContent) {
         throw new DoxloopError(`${label} cannot be the project root.`);
     }
     const relation = relative(absoluteRoot, candidate);
@@ -36,20 +39,21 @@ export async function resolveContainedDirectory(root, configuredPath, label = 'D
     assertInside(realRoot, realCandidate);
     return candidate;
 }
-export async function listFiles(root, extensions) {
+export async function listFiles(root, extensions, options = {}) {
     const output = [];
-    await walk(root, root, extensions, output);
+    await walk(root, root, extensions, output, options.ignoredDirectories);
     return output.sort();
 }
-async function walk(root, directory, extensions, output) {
+async function walk(root, directory, extensions, output, ignoredDirectories) {
     const entries = await readdir(directory, { withFileTypes: true });
     for (const entry of entries) {
         const path = assertInside(root, resolve(directory, entry.name));
         if (entry.isSymbolicLink()) {
             throw new DoxloopError(`Symbolic links are not allowed in documentation: ${path}`);
         }
-        if (entry.isDirectory())
-            await walk(root, path, extensions, output);
+        if (entry.isDirectory() && !ignoredDirectories?.has(entry.name)) {
+            await walk(root, path, extensions, output, ignoredDirectories);
+        }
         else if (entry.isFile() && extensions.has(extname(entry.name)))
             output.push(path);
     }
@@ -74,4 +78,30 @@ export async function pathExists(path) {
         throw error;
     }
 }
+const gitignoreQueues = new Map();
+/** Add machine-local artifacts to .gitignore without losing concurrent additions. */
+export async function ensureGitignoreEntries(root, entries) {
+    const key = resolve(root);
+    const previous = gitignoreQueues.get(key) ?? Promise.resolve();
+    const queued = previous.catch(() => undefined).then(async () => {
+        const path = join(key, '.gitignore');
+        const existing = (await pathExists(path)) ? await readFile(path, 'utf8') : '';
+        const lines = existing.split(/\r?\n/).filter(Boolean);
+        const seen = new Set(lines);
+        for (const entry of entries)
+            if (!seen.has(entry)) {
+                lines.push(entry);
+                seen.add(entry);
+            }
+        await writeFile(path, `${lines.join('\n')}\n`, 'utf8');
+    });
+    gitignoreQueues.set(key, queued);
+    try {
+        await queued;
+    }
+    finally {
+        if (gitignoreQueues.get(key) === queued)
+            gitignoreQueues.delete(key);
+    }
+}
 //# sourceMappingURL=fs.js.map

package/dist/generator-api.d.ts

@@ -39,6 +39,58 @@ export interface GeneratorPage {
     description?: string;
     body: string;
 }
+/** One page the navigation should reference. `path` is relative to the content root. */
+export interface GeneratorNavigationPage {
+    path: string;
+    title: string;
+    /** Section label; adapters that support grouping nest the page under it. */
+    section?: string;
+}
+export interface GeneratorNavigationContext {
+    root: string;
+    contentRoot: string;
+    project: DoxloopProject;
+    /** `add` inserts the page, `remove` drops it, `rename` moves `from` to `page`. */
+    action: 'add' | 'remove' | 'rename';
+    page: GeneratorNavigationPage;
+    /** Content-relative path of the page before a rename. */
+    from?: string;
+}
+/**
+ * A whole navigation as a tree, for the control center's navigation editor.
+ * `file` is content-relative and keeps the page extension the generator uses.
+ */
+export type GeneratorNavigationTreeNode = {
+    type: 'page';
+    file: string;
+    title?: string;
+} | {
+    type: 'group';
+    label: string;
+    items: GeneratorNavigationTreeNode[];
+};
+export interface GeneratorNavigationTree {
+    nodes: GeneratorNavigationTreeNode[];
+}
+export interface GeneratorNavigationTreeContext {
+    root: string;
+    contentRoot: string;
+    project: DoxloopProject;
+}
+export interface GeneratorRenderContext {
+    root: string;
+    contentRoot: string;
+    /** Content-relative path of the page being rendered. */
+    path: string;
+    /** The page as read from disk, or unsaved content when previewing an edit. */
+    page: GeneratorPage;
+}
+export interface GeneratorRenderedPage {
+    /** HTML for the page body only; the host supplies the document shell. */
+    html: string;
+    /** True when native components were left unrendered and the full build would differ. */
+    partial?: boolean;
+}
 export interface GeneratorAdapter {
     apiVersion: typeof GENERATOR_API_VERSION;
     id: string;
@@ -49,11 +101,28 @@ export interface GeneratorAdapter {
         skillName: string;
         skillDirectory: string;
     };
+    planning?: {
+        /** Generator-native files that own primary or sidebar navigation. */
+        navigationFiles: string[];
+    };
     project: {
         defaultContentDir: string;
         pageExtensions: string[];
         gitignore: string[];
         contentFormat?: 'markdown' | 'rst' | 'html';
+        /**
+         * Project-relative directory uploaded images land in, and the URL prefix
+         * pages use to reference them. Absent means `assets` under the content
+         * directory, referenced as `/assets/<name>`.
+         */
+        assets?: {
+            directory: string;
+            publicPrefix: string;
+        };
+    };
+    /** The generator's own theme configuration, named in the branding panel when Doxloop cannot edit it. */
+    theme?: {
+        configFile: string;
     };
     build: {
         command: string;
@@ -64,6 +133,26 @@ export interface GeneratorAdapter {
     validate(context: GeneratorValidationContext): Promise<ValidationIssue[]>;
     resolveLocalAsset?(context: GeneratorAssetContext): string | undefined;
     readPage?(path: string): Promise<GeneratorPage>;
+    /**
+     * Update the generator's own navigation file when a page is created,
+     * removed, or renamed. Absent when the generator derives navigation from the
+     * file system or from configuration Doxloop cannot rewrite safely.
+     */
+    writeNavigation?(context: GeneratorNavigationContext): Promise<void>;
+    /**
+     * Read the whole navigation as a tree so the control center can reorder,
+     * group, and relabel it, and write the edited tree back. Absent when the
+     * generator's navigation is code or is derived from the file system.
+     */
+    readNavigationTree?(context: GeneratorNavigationTreeContext): Promise<GeneratorNavigationTree>;
+    writeNavigationTree?(context: GeneratorNavigationTreeContext & {
+        tree: GeneratorNavigationTree;
+    }): Promise<void>;
+    /**
+     * Render one page to HTML without running the native build. Absent when the
+     * host's generic Markdown preview is the best available approximation.
+     */
+    renderPage?(context: GeneratorRenderContext): Promise<GeneratorRenderedPage>;
 }
 export declare function defineGenerator<T extends GeneratorAdapter>(adapter: T): T;
 //# sourceMappingURL=generator-api.d.ts.map

package/dist/generator-preflight.d.ts

@@ -0,0 +1,27 @@
+import { type GeneratorTier } from './generators.js';
+import type { GeneratorName } from './types.js';
+export interface GeneratorPreflightCheck {
+    status: 'pass' | 'warning' | 'fail';
+    label: string;
+    detail?: string;
+}
+export interface GeneratorPreflight {
+    generator: GeneratorName;
+    tier: GeneratorTier;
+    /** False when a required tool is missing; warnings do not clear it. */
+    ready: boolean;
+    checks: GeneratorPreflightCheck[];
+}
+export interface PreflightProbe {
+    findExecutable: (name: string) => Promise<string | undefined>;
+    /** Runs `command args` and resolves stdout+stderr, or undefined when it cannot run. */
+    runVersion: (command: string, args: string[]) => Promise<string | undefined>;
+    nodeVersion: string;
+}
+/**
+ * Checks that the runtimes a generator's preview and strict build need are
+ * present before the wizard creates a project with it. Doxloop's own
+ * requirements (Node.js) are checked once regardless of generator.
+ */
+export declare function generatorPreflight(generator: GeneratorName, probe?: Partial<PreflightProbe>): Promise<GeneratorPreflight>;
+//# sourceMappingURL=generator-preflight.d.ts.map

package/dist/generator-preflight.js

@@ -0,0 +1,105 @@
+import { execFile } from 'node:child_process';
+import { findExecutable } from './generator-runtime.js';
+import { GENERATOR_TOOLCHAINS, generatorCatalogEntry, } from './generators.js';
+const DEFAULT_PROBE = {
+    findExecutable,
+    runVersion: (command, args) => new Promise((resolveOutput) => {
+        execFile(command, args, { timeout: 8_000, windowsHide: true }, (error, stdout, stderr) => {
+            resolveOutput(error && !stdout && !stderr ? undefined : `${stdout}${stderr}`.trim());
+        });
+    }),
+    nodeVersion: process.versions.node,
+};
+/**
+ * Checks that the runtimes a generator's preview and strict build need are
+ * present before the wizard creates a project with it. Doxloop's own
+ * requirements (Node.js) are checked once regardless of generator.
+ */
+export async function generatorPreflight(generator, probe = {}) {
+    const entry = generatorCatalogEntry(generator);
+    if (!entry)
+        throw new Error(`Unknown generator "${generator}".`);
+    const tools = { ...DEFAULT_PROBE, ...probe };
+    const checks = [];
+    if (entry.toolchain.length === 0) {
+        checks.push({ status: 'pass', label: 'Built into Doxloop', detail: 'No extra toolchain is needed for preview or build.' });
+    }
+    for (const id of entry.toolchain) {
+        checks.push(...(await toolchainChecks(id, tools)));
+    }
+    return {
+        generator,
+        tier: entry.tier,
+        ready: checks.every((check) => check.status !== 'fail'),
+        checks,
+    };
+}
+async function toolchainChecks(id, tools) {
+    const requirement = GENERATOR_TOOLCHAINS[id];
+    switch (id) {
+        case 'node': {
+            const [major = 0, minor = 0] = tools.nodeVersion.split('.').map(Number);
+            const supported = major > 20 || (major === 20 && minor >= 12);
+            const checks = [
+                supported
+                    ? { status: 'pass', label: `Node.js ${tools.nodeVersion}` }
+                    : { status: 'fail', label: `Node.js ${tools.nodeVersion} is too old`, detail: `${requirement.label} is required for the native build.` },
+            ];
+            const managers = await Promise.all(['npm', 'pnpm', 'yarn'].map(async (name) => ((await tools.findExecutable(name)) ? name : undefined)));
+            const available = managers.filter((name) => Boolean(name));
+            checks.push(available.length > 0
+                ? { status: 'pass', label: `Package manager: ${available.join(', ')}` }
+                : { status: 'fail', label: 'No package manager found', detail: 'Install npm, pnpm, or yarn so the site dependencies can be installed.' });
+            return checks;
+        }
+        case 'python': {
+            const python = (await tools.findExecutable('python3')) ?? (await tools.findExecutable('python'));
+            if (!python) {
+                return [{ status: 'fail', label: 'Python is not installed', detail: `${requirement.label} is required. ${requirement.detail}` }];
+            }
+            const version = await tools.runVersion(python, ['--version']);
+            const match = version?.match(/(\d+)\.(\d+)(?:\.(\d+))?/);
+            const [, major = '0', minor = '0'] = match ?? [];
+            const supported = Number(major) > 3 || (Number(major) === 3 && Number(minor) >= 9);
+            const checks = [
+                supported
+                    ? { status: 'pass', label: `Python ${match?.[0] ?? version ?? 'found'}` }
+                    : { status: 'fail', label: `Python ${match?.[0] ?? 'version unknown'} is too old`, detail: `${requirement.label} is required for MkDocs and Sphinx.` },
+            ];
+            const venv = await tools.runVersion(python, ['-c', 'import venv, ensurepip; print("ok")']);
+            checks.push(venv?.includes('ok')
+                ? { status: 'pass', label: 'venv and pip modules available' }
+                : { status: 'warning', label: 'venv or ensurepip module missing', detail: 'Doxloop creates .doxloop/venv on first preview; install the python3-venv package if that fails.' });
+            return checks;
+        }
+        case 'hugo': {
+            const hugo = await tools.findExecutable('hugo');
+            if (!hugo) {
+                return [{ status: 'fail', label: 'Hugo is not installed', detail: 'Install Hugo from https://gohugo.io/installation/ so preview and build can run.' }];
+            }
+            const version = await tools.runVersion(hugo, ['version']);
+            const extended = /extended/i.test(version ?? '');
+            return [
+                { status: 'pass', label: `Hugo ${version?.match(/v?\d+\.\d+(?:\.\d+)?/)?.[0] ?? 'found'}${extended ? ' (extended)' : ''}` },
+                ...(extended ? [] : [{ status: 'warning', label: 'Standard edition', detail: 'Themes that compile Sass need the extended edition.' }]),
+            ];
+        }
+        case 'ruby': {
+            const ruby = await tools.findExecutable('ruby');
+            const bundle = await tools.findExecutable('bundle');
+            const checks = [];
+            if (!ruby) {
+                checks.push({ status: 'fail', label: 'Ruby is not installed', detail: 'Install Ruby 3.1 or later; Jekyll runs on it.' });
+            }
+            else {
+                const version = await tools.runVersion(ruby, ['--version']);
+                checks.push({ status: 'pass', label: `Ruby ${version?.match(/\d+\.\d+(?:\.\d+)?/)?.[0] ?? 'found'}` });
+            }
+            checks.push(bundle
+                ? { status: 'pass', label: 'Bundler available' }
+                : { status: 'fail', label: 'Bundler is not installed', detail: 'Run `gem install bundler` so Jekyll gems can be installed under .doxloop/bundle.' });
+            return checks;
+        }
+    }
+}
+//# sourceMappingURL=generator-preflight.js.map

package/dist/generator-runtime.d.ts

@@ -19,6 +19,13 @@ export declare function ensurePythonDependencies(root: string, binaryName: strin
 export declare function runCommand(command: string, args: string[], root: string): Promise<number>;
 export declare function runPreviewProcess(command: string, args: string[], root: string, label: string, environment?: NodeJS.ProcessEnv): Promise<void>;
 export declare function openBrowser(url: string): Promise<void>;
+/**
+ * A validator that cannot tell which pages the native site links reports one
+ * warning instead of guessing. The native strict build remains the authority.
+ */
+export declare function navigationUnverifiedIssue(label: string, file: string, reason: string): ValidationIssue;
+/** Content-relative, forward-slash page paths for the validation context. */
+export declare function contentRelativePages(contentRoot: string, pages: readonly string[]): string[];
 export declare function requiredFileIssues(label: string, files: string[], existing: Set<string>): ValidationIssue[];
 export declare function serveStaticDirectory(options: GeneratorPreviewOptions, directory: string, label: string): Promise<void>;
 //# sourceMappingURL=generator-runtime.d.ts.map

package/dist/generator-runtime.js

@@ -2,7 +2,7 @@ import { spawn } from 'node:child_process';
 import { createReadStream } from 'node:fs';
 import { access, readFile, stat, writeFile } from 'node:fs/promises';
 import { createServer } from 'node:http';
-import { delimiter, extname, join, normalize, resolve, sep } from 'node:path';
+import { delimiter, extname, join, normalize, relative, resolve, sep } from 'node:path';
 import { DoxloopError } from './errors.js';
 export async function pathExists(path) {
     try {
@@ -184,6 +184,22 @@ export async function openBrowser(url) {
         });
     });
 }
+/**
+ * A validator that cannot tell which pages the native site links reports one
+ * warning instead of guessing. The native strict build remains the authority.
+ */
+export function navigationUnverifiedIssue(label, file, reason) {
+    return {
+        severity: 'warning',
+        code: 'navigation-unverified',
+        message: `${label} navigation was not verified: ${reason} Run the native build to confirm every page is reachable.`,
+        file,
+    };
+}
+/** Content-relative, forward-slash page paths for the validation context. */
+export function contentRelativePages(contentRoot, pages) {
+    return pages.map((page) => relative(contentRoot, page).split('\\').join('/'));
+}
 export function requiredFileIssues(label, files, existing) {
     return files
         .filter((file) => !existing.has(file))

package/dist/generators.d.ts

@@ -1,5 +1,12 @@
 import { type GeneratorAdapter } from './generator-api.js';
 import type { DoxloopProject, GeneratorName } from './types.js';
+/**
+ * How much of Doxloop's workflow a generator gets. The tier is a statement
+ * about the adapter, not the framework: it says what validation, preview, and
+ * authoring guidance Doxloop itself provides for that generator today.
+ */
+export type GeneratorTier = 'full' | 'supported' | 'basic';
+export type GeneratorToolchainId = 'node' | 'python' | 'hugo' | 'ruby';
 export interface GeneratorCatalogEntry {
     id: GeneratorName;
     displayName: string;
@@ -7,7 +14,18 @@ export interface GeneratorCatalogEntry {
     skillName: string;
     buildCommand?: string;
     outputDir?: string;
+    tier: GeneratorTier;
+    /** External runtimes the native build and preview need, beyond Doxloop itself. */
+    toolchain: readonly GeneratorToolchainId[];
 }
+export declare const GENERATOR_TIERS: Record<GeneratorTier, {
+    label: string;
+    description: string;
+}>;
+export declare const GENERATOR_TOOLCHAINS: Record<GeneratorToolchainId, {
+    label: string;
+    detail: string;
+}>;
 export declare const GENERATOR_CATALOG: readonly GeneratorCatalogEntry[];
 export declare function generatorCatalogEntry(id: string): GeneratorCatalogEntry | undefined;
 export declare function parseGenerator(value: string | undefined): GeneratorName | undefined;
@@ -15,7 +33,11 @@ export declare function generatorPackageName(generator: GeneratorName, configure
 export declare function generatorSkillName(generator: GeneratorName): string;
 export declare function loadGeneratorAdapter(root: string, projectOrGenerator: DoxloopProject | GeneratorName, configuredPackage?: string): Promise<GeneratorAdapter>;
 export declare function resolveGeneratorPackage(root: string, packageName: string): string | undefined;
-export declare function installedGeneratorEntries(root: string): Promise<Array<GeneratorCatalogEntry & {
+export interface InstalledGeneratorEntry extends GeneratorCatalogEntry {
     installed: boolean;
-}>>;
+    tierLabel: string;
+    tierDescription: string;
+    toolchainLabels: string[];
+}
+export declare function installedGeneratorEntries(root: string): Promise<InstalledGeneratorEntry[]>;
 //# sourceMappingURL=generators.d.ts.map