@shoalrun/cli 0.1.0-alpha.19 → 1.0.0

package/dist/artifact-bundle.js

@@ -12,6 +12,8 @@ import { fictionalDocument, optionalDocument, resolveLlmsDiscovery } from './llm
 import { boundedDiscovery } from './compact-discovery.js';
 import { iconLicenseFile } from './icons.js';
 import { peleLicenseFile } from './diagrams.js';
+import { fontMediaType } from './fonts.js';
+import { createHash } from 'node:crypto';
 import { defaultShareSvg, faviconSvg, fillShareTemplate, renderPng, touchIconSvg } from './share-images.js';
 import { paletteCatalog, paletteCss, presetCatalog, resolvePalette } from './palettes.js';
 import { heading, link, list, paragraph, renderMarkdown, root, searchIndex, shareCardText, text } from './content.js';
@@ -38,6 +40,8 @@ export async function assembleArtifacts(input) {
             artifactDirectories.add(parent);
         artifacts.set(normalized, data);
     };
+    for (const [route, bytes] of input.extraArtifacts ?? [])
+        addArtifact(route, bytes);
     const addPublicArtifact = (route, data) => addArtifact(publicPath(route), data);
     const addMetadataArtifact = (route, data) => {
         for (const url of new Set([route, publicPath(route)]))
@@ -146,10 +150,16 @@ export async function assembleArtifacts(input) {
     }
     if (generatedFontsCss)
         addPublicArtifact('/assets/fonts.css', generatedFontsCss.replaceAll('url("/assets/', `url("${basePath}/assets/`));
+    const addFont = (route, bytes, immutable) => {
+        addPublicArtifact(route, bytes);
+        const type = fontMediaType(route);
+        if (type)
+            headers[publicPath(route)] = { 'Content-Type': type, 'Cache-Control': immutable ? 'public, max-age=31536000, immutable' : 'public, max-age=0, must-revalidate', ETag: `"${createHash('sha256').update(bytes).digest('hex')}"` };
+    };
     for (const file of fontFiles)
-        addPublicArtifact(`/assets/fonts/${path.basename(file)}`, await readFile(file));
-    for (const route of new Set(fonts.faces.map(face => face.route)))
-        addPublicArtifact(route, await readFile(fonts.faces.find(face => face.route === route).file));
+        addFont(`/assets/fonts/${path.basename(file)}`, await readFile(file), false);
+    for (const [route, bytes] of input.projectFontAssets)
+        addFont(route, bytes, true);
     const shareTemplate = shareImages.template ? await readFile(shareImages.template, 'utf8') : undefined;
     for (const page of rendered) {
         const share = shareFor(page.doc);

package/dist/authoring-snapshot.js

@@ -193,7 +193,7 @@ export async function captureSnapshotInputs(configFile, options = {}) {
                 for (const key of Object.keys(value))
                     await visit(value[key], [...segments, key]);
             }
-            else if (typeof value === 'string' && (['file', 'path', 'module', 'manifest', 'customCss', 'customReaderModule', 'body', 'template', 'favicon', 'logo'].includes(segments.at(-1)) || segments.at(-2) === 'files') && !/^(?:[a-z][a-z0-9+.-]*:|#)/i.test(value)) {
+            else if (typeof value === 'string' && (['file', 'path', 'module', 'manifest', 'customCss', 'customReaderModule', 'body', 'template', 'favicon', 'logo'].includes(segments.at(-1)) || segments.at(-2) === 'files' || (segments[0] === 'outputs' && segments[1] === 'html' && segments[2] === 'highlighting' && segments.at(-1) === 'grammar') || (segments.includes('pdf') && (segments.at(-1) === 'stylesheet' || segments.includes('fonts') && segments.at(-1) === 'source'))) && !/^(?:[a-z][a-z0-9+.-]*:|#)/i.test(value)) {
                 if (path.isAbsolute(value))
                     throw new SnapshotError('unsupported_dependency', `Absolute dependency at ${segments.join('.')} cannot be isolated; use a relative path.`);
                 if (segments[0] === 'components' && segments.at(-1) === 'module' && !value.startsWith('.'))

package/dist/browser-print-assets.d.ts

@@ -0,0 +1,9 @@
+/** One shared print theme for the entire build; no page content is materialized. */
+export declare function browserPrintAssets(configFile: string, options: {
+    basePath: string;
+    profile?: string;
+    style?: string;
+}): Promise<{
+    artifacts: Map<string, string | Buffer<ArrayBufferLike>>;
+    dependencies: Set<string>;
+}>;

package/dist/browser-print-assets.js

@@ -0,0 +1,45 @@
+import path from 'node:path';
+import { parse } from 'parse5';
+import { loadConfig } from './config.js';
+import { projectPdfSettings } from './pdf-project.js';
+import { preparePdfDocument } from './pdf-renderer.js';
+import { sitePath } from './site-path.js';
+/** One shared print theme for the entire build; no page content is materialized. */
+export async function browserPrintAssets(configFile, options) {
+    const loaded = await loadConfig(configFile, { profile: options.profile });
+    const { config, files } = projectPdfSettings(loaded, configFile, options.style);
+    const prepared = await preparePdfDocument({
+        documents: [{ id: 'print-theme', title: '', html: '' }], title: '', assets: new Map(), publicBase: '/',
+        config: { ...config, cover: false, toc: false }, configFile,
+        assetRoots: files.map(file => path.dirname(file))
+    });
+    let css = '';
+    const findStyle = (node) => { if (node.tagName === 'style')
+        css += (node.childNodes ?? []).map((child) => child.value ?? '').join(''); for (const child of node.childNodes ?? [])
+        findStyle(child); };
+    findStyle(parse(prepared.html));
+    const artifacts = new Map();
+    let logo;
+    for (const [original, asset] of prepared.assets) {
+        const route = sitePath(options.basePath, `/assets/print/${path.posix.basename(original)}`);
+        artifacts.set(route, asset.bytes);
+        css = css.replaceAll(original, route);
+        if (original.startsWith('/__pdf_logo/'))
+            logo = route;
+    }
+    const margins = { top: '18mm', right: '18mm', bottom: '18mm', left: '18mm', ...config.margins };
+    css = `@page{size:${config.size ?? 'A4'};margin:${margins.top} ${margins.right} ${margins.bottom} ${margins.left}}\n` + css;
+    css += '\n.pdf-print-tools{display:flex;gap:10px;align-items:center;padding:12px 0;margin-bottom:24px;font:14px Arial,sans-serif}.pdf-print-tools button{font:inherit;padding:8px 12px;border:1px solid #89998e;border-radius:4px;cursor:pointer}.pdf-print-tools .pdf-print-note{margin-left:auto;color:#53665e;font-size:12px}.pdf-chapter .page-head h1{margin-bottom:8pt}.pdf-chapter .page-head .summary{font-size:10pt;line-height:1.5;margin:0 0 8pt}.pdf-chapter .page-head .pdf-page-meta{font-size:8pt;margin:5pt 0 12pt}.pdf-page-meta{color:var(--pdf-muted);font-size:9pt;margin-bottom:14pt}.pdf-chapter .eyebrow{color:var(--pdf-muted);font-size:9pt}.pdf-chapter .page-dates{display:flex;flex-wrap:wrap;gap:4pt 10pt;font-size:9pt;color:var(--pdf-muted)}.pdf-chapter .doc-callout{border-left:3pt solid var(--pdf-accent);padding:10pt 14pt;background:#f1f4ee;margin:14pt 0}.pdf-chapter details{display:block}.pdf-reader-label{font-weight:bold;margin-top:14pt}@media screen{html{background:#dfe5de}body{max-width:210mm;margin:24px auto;padding:18mm;background:white;box-shadow:0 8px 40px #173c3520}}@media print{.pdf-print-tools{display:none!important}}';
+    // A manual theme may start every chapter on a new page. When no cover or
+    // contents precede this chapter, that break can produce a blank first sheet.
+    css += '\n.pdf-print-tools + .pdf-chapter{break-before:auto}';
+    const stylesheet = sitePath(options.basePath, '/assets/print/theme.css');
+    artifacts.set(stylesheet, css);
+    const settings = {
+        schemaVersion: 1, stylesheet, ...(logo ? { logo } : {}), cover: config.cover ?? false,
+        toc: config.toc ?? false, subtitle: config.subtitle ?? '', header: config.header ?? '', footer: config.footer ?? '',
+        fonts: (config.fonts ?? []).map(({ family, weight, style }) => ({ family, weight, style }))
+    };
+    artifacts.set(sitePath(options.basePath, '/assets/print/settings.json'), JSON.stringify(settings));
+    return { artifacts, dependencies: new Set([...loaded.dependencies, ...files]) };
+}

package/dist/cli-discovery.d.ts

@@ -1,4 +1,4 @@
 export declare const docsHelp = "Usage: shoalrun docs <command>\n\nRead bundled references (no project or provider key required):\n  search <query> [--json]\n  read <document-id> [--json]\n  outline <document-id> [--json]\n  section <document-id> <section-id> [--json]\n\nSearch and reads accept --site DIRECTORY, --max-tokens N, and publication\nselectors --product P --channel C --version V --language L.\n\nInspect a project:\n  project [--config FILE] [--profile FILE] [--section pages|guidance|configuration|navigation|relationships|templates|findings]\n  source FILE [--config FILE] [--profile FILE]\n  context <document-id> [--config FILE]\n\nValidate and preview edits:\n  baseline --out FILE [--config FILE] [--profile FILE]\n  validate (--baseline FILE | --file FILE | --id ID) [--config FILE] [--profile FILE]\n  validation-status REPORT\n  review REPORT [--format json|markdown]\n  preview REPORT [--port PORT]\n\nOther authoring tools: changes, plan, apply, mcp.\nDiscover packaged agent guidance with shoalrun skills list.\n";
 export declare const skillsHelp = "Usage: shoalrun skills list [--json]\n       shoalrun skills read <name> [--json]\n\nList the names, descriptions and local paths of packaged skills, or read a skill.\nThese commands do not install skills or require a project or provider key.\n";
-export declare const cliHelp = "Usage: shoalrun <command>\n\nStart and build:\n  init [directory] [--starter minimal|api-docs|showcase]\n  build [config] [output] [--profile FILE]\n  export [config] --out DIRECTORY [--target NAME] [--profile FILE]\n  dev [config] [output] [--profile FILE] [--port PORT]\n  serve <site-directory> [--host HOST] [--port PORT]\n  check [config] [--json]\n  audit [config]\n  scaffold <template> -n <target> [--config FILE] [--product P]\n\nAgent guidance and offline documentation:\n  skills list [--json]\n  skills read <name> [--json]\n  docs search <query> [--site DIRECTORY] [--product P] [--json]\n  docs read <document-id> [--site DIRECTORY] [--product P] [--json]\n  docs project [--config FILE] [--profile FILE]\n  docs baseline --out FILE [--config FILE] [--profile FILE]\n  docs validate (--baseline FILE | --file FILE | --id ID) [--config FILE] [--profile FILE]\n  docs review REPORT [--format json|markdown]\n  docs preview REPORT [--port PORT]\n\nOther commands: config, api, operation, ingredient, recipe, search, index,\nask, answers, ask-log, chat, eval, vercel.\nRun shoalrun docs --help or shoalrun skills --help for discovery commands.\n";
+export declare const cliHelp = "Usage: shoalrun <command>\n\nStart and build:\n  init [directory] [--starter minimal|api-docs|showcase]\n  build [config] [output] [--profile FILE]\n  export [config] --out DIRECTORY [--target NAME] [--profile FILE]\n  dev [config] [output] [--profile FILE] [--port PORT]\n  serve <site-directory> [--host HOST] [--port PORT]\n  check [config] [--json]\n  references check <snapshot.json>\n  audit [config]\n  scaffold <template> -n <target> [--config FILE] [--product P]\n\nAgent guidance and offline documentation:\n  skills list [--json]\n  skills read <name> [--json]\n  docs search <query> [--site DIRECTORY] [--product P] [--json]\n  docs read <document-id> [--site DIRECTORY] [--product P] [--json]\n  docs project [--config FILE] [--profile FILE]\n  docs baseline --out FILE [--config FILE] [--profile FILE]\n  docs validate (--baseline FILE | --file FILE | --id ID) [--config FILE] [--profile FILE]\n  docs review REPORT [--format json|markdown]\n  docs preview REPORT [--port PORT]\n\nOther commands: config, api, operation, ingredient, recipe, search, index,\nask, answers, ask-log, chat, eval, vercel.\nRun shoalrun docs --help or shoalrun skills --help for discovery commands.\n";
 export declare function runSkillsCommand(args: string[]): Promise<string>;

package/dist/cli-discovery.js

@@ -43,6 +43,7 @@ Start and build:
   dev [config] [output] [--profile FILE] [--port PORT]
   serve <site-directory> [--host HOST] [--port PORT]
   check [config] [--json]
+  references check <snapshot.json>
   audit [config]
   scaffold <template> -n <target> [--config FILE] [--product P]
 

package/dist/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { readCodeReference } from './code-reference-model.js';
 import { runExportCommand, exportHelp } from './content-export-command.js';
 import { cliHelp, docsHelp, skillsHelp, runSkillsCommand } from './cli-discovery.js';
 import { compareDocumentSnapshots } from './document-sync.js';
@@ -99,6 +100,12 @@ try {
     else if (command === 'skills') {
         process.stdout.write(await runSkillsCommand([subcommand, ...rest].filter((value) => value !== undefined)));
     }
+    else if (command === 'references') {
+        if (subcommand !== 'check' || rest.length !== 1)
+            throw new Error('Usage: shoalrun references check <snapshot.json>');
+        const snapshot = await readCodeReference(path.resolve(rest[0]));
+        process.stdout.write(JSON.stringify({ status: 'ok', programmingLanguage: snapshot.programmingLanguage, symbols: snapshot.symbols.length }) + '\n');
+    }
     else if (command === 'init') {
         const args = [subcommand, ...rest].filter((item) => item !== undefined);
         let directory = '.';

package/dist/code-reference-model.d.ts

@@ -0,0 +1,85 @@
+import { z } from 'zod';
+export declare const codeReferenceSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    kind: z.ZodLiteral<"shoalrun-code-reference">;
+    programmingLanguage: z.ZodString;
+    producer: z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+        extractorVersion: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    sourceDigest: z.ZodOptional<z.ZodString>;
+    symbols: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        kind: z.ZodEnum<{
+            function: "function";
+            constructor: "constructor";
+            module: "module";
+            type: "type";
+            constant: "constant";
+            enum: "enum";
+            method: "method";
+            property: "property";
+            namespace: "namespace";
+            class: "class";
+            interface: "interface";
+            attribute: "attribute";
+        }>;
+        parent: z.ZodOptional<z.ZodString>;
+        visibility: z.ZodDefault<z.ZodEnum<{
+            public: "public";
+            private: "private";
+        }>>;
+        summary: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        annotation: z.ZodOptional<z.ZodString>;
+        default: z.ZodOptional<z.ZodString>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        bases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        constructorSignature: z.ZodOptional<z.ZodString>;
+        typeReferences: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        signatures: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        parameters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            type: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+            default: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        returns: z.ZodOptional<z.ZodObject<{
+            type: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        yields: z.ZodOptional<z.ZodObject<{
+            type: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        raises: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            type: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+            default: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        examples: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            title: z.ZodOptional<z.ZodString>;
+            code: z.ZodString;
+        }, z.core.$strict>>>;
+        seeAlso: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        source: z.ZodOptional<z.ZodObject<{
+            path: z.ZodString;
+            line: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type CodeReferenceSnapshot = z.infer<typeof codeReferenceSchema>;
+export type CodeSymbol = CodeReferenceSnapshot['symbols'][number];
+export type CodeReference = {
+    catalog: string;
+    programmingLanguage: string;
+    symbol: CodeSymbol;
+    sourceUrl?: string;
+    layout?: 'symbols' | 'classes' | 'modules';
+    complete?: boolean;
+};
+export declare function validateCodeReference(value: unknown): CodeReferenceSnapshot;
+export declare function readCodeReference(file: string, root?: string): Promise<CodeReferenceSnapshot>;

package/dist/code-reference-model.js

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+import { readFile, realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+const text = z.string().max(100_000);
+const id = z.string().min(1).max(512).regex(/^[^\s\x00-\x1f]+$/, 'Symbol IDs cannot contain whitespace or control characters');
+const detail = z.object({ name: z.string().min(1).max(512), type: text.optional(), description: text.optional(), default: text.optional() }).strict();
+export const codeReferenceSchema = z.object({
+    schemaVersion: z.literal(1),
+    kind: z.literal('shoalrun-code-reference'),
+    programmingLanguage: z.string().regex(/^[a-z][a-z0-9_-]{0,63}$/),
+    producer: z.object({ name: z.string().min(1).max(100), version: z.string().min(1).max(100), extractorVersion: z.string().max(100).optional() }).strict(),
+    sourceDigest: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+    symbols: z.array(z.object({
+        id, name: z.string().min(1).max(512),
+        kind: z.enum(['module', 'namespace', 'class', 'interface', 'enum', 'type', 'function', 'method', 'constructor', 'property', 'attribute', 'constant']),
+        parent: id.optional(), visibility: z.enum(['public', 'private']).default('public'),
+        summary: z.string().max(1000).optional(), description: text.optional(),
+        annotation: text.optional(), default: text.optional(), required: z.boolean().optional(),
+        bases: z.array(text).max(100).optional(), constructorSignature: text.optional(),
+        typeReferences: z.record(z.string().min(1).max(512), id).optional(),
+        signatures: z.array(text).max(100).optional(),
+        parameters: z.array(detail).max(1000).optional(),
+        returns: z.object({ type: text.optional(), description: text.optional() }).strict().optional(),
+        yields: z.object({ type: text.optional(), description: text.optional() }).strict().optional(),
+        raises: z.array(detail).max(1000).optional(),
+        examples: z.array(z.object({ title: z.string().max(512).optional(), code: text }).strict()).max(100).optional(),
+        seeAlso: z.array(id).max(1000).optional(),
+        source: z.object({ path: z.string().min(1).max(1000).regex(/^(?!\/)(?!.*(?:^|\/)\.{1,2}(?:\/|$))[^/\\\x00:]+(?:\/[^/\\\x00:]+)*$/), line: z.number().int().positive().optional() }).strict().optional()
+    }).strict()).min(1).max(10_000)
+}).strict();
+export function validateCodeReference(value) {
+    const result = codeReferenceSchema.parse(value);
+    const symbols = new Map();
+    for (const symbol of result.symbols) {
+        if (symbols.has(symbol.id))
+            throw new Error(`Duplicate code symbol ${symbol.id}`);
+        symbols.set(symbol.id, symbol);
+    }
+    const complete = new Set();
+    for (const symbol of result.symbols) {
+        for (const target of [symbol.parent, ...symbol.seeAlso ?? [], ...Object.values(symbol.typeReferences ?? {})])
+            if (target && !symbols.has(target))
+                throw new Error(`${symbol.id}: unknown code symbol ${target}`);
+        const seen = new Set([symbol.id]);
+        let parent = symbol.parent;
+        while (parent && !complete.has(parent)) {
+            if (seen.has(parent))
+                throw new Error(`${symbol.id}: cyclic symbol ownership`);
+            seen.add(parent);
+            parent = symbols.get(parent)?.parent;
+        }
+        for (const id of seen)
+            complete.add(id);
+    }
+    return result;
+}
+export async function readCodeReference(file, root) {
+    const canonical = await realpath(file);
+    if (root) {
+        const base = await realpath(root);
+        if (canonical !== base && !canonical.startsWith(base + path.sep))
+            throw new Error('Code reference source escapes the project root');
+    }
+    if (canonical.split(path.sep).some(part => /^\.env(?:\.|$)|^\.git$|\.(?:local|override)\.md$/i.test(part)))
+        throw new Error('Private local files cannot be code reference sources');
+    const info = await stat(canonical);
+    if (!info.isFile() || info.size > 32 * 1024 * 1024)
+        throw new Error('Code reference source must be a regular JSON file at most 32 MiB');
+    const bytes = await readFile(canonical);
+    if (bytes.length > 32 * 1024 * 1024)
+        throw new Error('Code reference source exceeds 32 MiB');
+    return validateCodeReference(JSON.parse(bytes.toString('utf8')));
+}

package/dist/code-references.d.ts

@@ -0,0 +1,23 @@
+import { type CodeReference } from './code-reference-model.js';
+import { type loadConfig } from './config.js';
+import { type ReaderFiltersConfig, type ReaderSelection } from './reader-filters.js';
+import { type Document, type Variant } from './content-source.js';
+import type { AuthoredPublicationConfig, AuthoredPublicationPlan } from './publication-plan.js';
+export declare function codeDocumentId(catalog: string, symbol: string): string;
+export declare function materializeCodeReferences(input: {
+    config: AuthoredPublicationConfig & {
+        codeReferences?: unknown;
+    };
+    loaded: Awaited<ReturnType<typeof loadConfig>>;
+    plan: AuthoredPublicationPlan;
+    base: string;
+    basePath: string;
+    variants: Variant[];
+    language: string;
+    readerFilters?: ReaderFiltersConfig;
+    contentFilter?: ReaderSelection;
+    dependencies: Set<string>;
+    allowRouteCollisions?: boolean;
+}): Promise<void>;
+/** Imported prose is inert Markdown; it never enters MDX or project directive expansion. */
+export declare function renderCodeReference(reference: CodeReference, doc: Document, documents: Map<string, Document>): any;