@texuli/tools 0.0.0-stage → 0.1.0-next.0

package/dist/golden/types.d.ts

@@ -0,0 +1,54 @@
+import type { CatalogTreeInput, RenderTier } from '@texuli/catalog/render/renderer';
+/** One pre-registered interface task of the agent golden set. */
+export interface GoldenTask {
+    /** Stable id: `g<NN>-<kebab-name>`. */
+    id: string;
+    title: string;
+    /** The prompt a model receives. Fictional content only. */
+    brief: string;
+    /** Who authors the tree. The golden set is agent content: `untrusted`. */
+    tier: RenderTier;
+    /** Component ids the interface needs (the scorer's coverage check). */
+    mustInclude: readonly string[];
+    /**
+     * `dontUseWhen` lines the brief deliberately baits (it mentions navigation,
+     * sign-in or a purchase the interface must leave to the host app). Each is
+     * an exact manifest line with a detector in `guidance.ts`.
+     */
+    traps: readonly string[];
+    /** A reference tree that passes every check. */
+    reference: CatalogTreeInput;
+}
+/** The checks the scorer runs, in order. */
+export declare const GOLDEN_CHECKS: readonly ["schema", "dontUseWhen", "sinks", "grammar", "axe", "coverage"];
+export type GoldenCheckId = (typeof GOLDEN_CHECKS)[number];
+/**
+ * `skipped` when a check cannot run: axe without a DOM runner or after a
+ * schema failure, grammar when nothing rendered, sinks and guidance when the
+ * output is not a tree. A skipped check never counts as passed.
+ */
+export type GoldenCheckStatus = 'pass' | 'fail' | 'skipped';
+export interface GoldenCheckResult {
+    check: GoldenCheckId;
+    status: GoldenCheckStatus;
+    /** Why it failed (stable, human-readable lines). Empty on pass. */
+    issues: readonly string[];
+}
+export interface GoldenScore {
+    taskId: string;
+    /** True when no check failed (a skipped check does not fail). */
+    passed: boolean;
+    /** Passed checks over checks that ran. */
+    score: number;
+    checks: readonly GoldenCheckResult[];
+}
+/** What the axe runner reports: one entry per violated rule. */
+export interface GoldenAxeViolation {
+    id: string;
+    impact?: string | null;
+    nodes: number;
+    /** First offending node's markup, for the report. */
+    sample?: string;
+}
+/** Runs axe on a painted document and returns its violations. */
+export type GoldenAxeRunner = (root: Document) => Promise<readonly GoldenAxeViolation[]>;

package/dist/golden/types.js

@@ -0,0 +1,9 @@
+/** The checks the scorer runs, in order. */
+export const GOLDEN_CHECKS = [
+    'schema',
+    'dontUseWhen',
+    'sinks',
+    'grammar',
+    'axe',
+    'coverage',
+];

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `@texuli/tools` — agent and developer tools.
+ * Subpaths land as PLAN_001 tasks ship them.
+ */
+export { type A2uiDiagnostic, type A2uiMessage, a2uiToCatalogTree, catalogTreeToA2ui, validateA2uiMessages, } from './a2ui/index.js';
+export { type AddableComponent, type AddCliArgs, type AddOptions, type AddResult, addComponent, DEFAULT_ADD_REGISTRY, getAddable, hasProvenance, isPrimitivesPath, listAddableIds, parseAddArgs, planAdd, provenanceHeader, runAddCli, } from './cli-add/index.js';
+export { diffComponent, type UpdateFile, type UpdateFileStatus, type UpdateOptions, type UpdateResult, updateComponent, } from './cli-update/index.js';
+export { buildLlmsBundle, componentDocPath, componentHref, formatComponentMarkdown, formatLlmsFullTxt, formatLlmsLink, formatLlmsTxt, type LlmsBundle, type LlmsBundleOptions, type LlmsCliArgs, type LlmsFile, type LlmsWriteResult, parseLlmsArgs, runLlmsCli, writeLlmsBundle, } from './llms/index.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+/**
+ * `@texuli/tools` — agent and developer tools.
+ * Subpaths land as PLAN_001 tasks ship them.
+ */
+export { a2uiToCatalogTree, catalogTreeToA2ui, validateA2uiMessages, } from "./a2ui/index.js";
+export { addComponent, DEFAULT_ADD_REGISTRY, getAddable, hasProvenance, isPrimitivesPath, listAddableIds, parseAddArgs, planAdd, provenanceHeader, runAddCli, } from "./cli-add/index.js";
+export { diffComponent, updateComponent, } from "./cli-update/index.js";
+export { buildLlmsBundle, componentDocPath, componentHref, formatComponentMarkdown, formatLlmsFullTxt, formatLlmsLink, formatLlmsTxt, parseLlmsArgs, runLlmsCli, writeLlmsBundle, } from "./llms/index.js";

package/dist/internal/paths.d.ts

@@ -0,0 +1,56 @@
+import type { AddableComponent } from '../cli-add/types.js';
+/** True when `candidate` escapes `root` (after resolve). */
+export declare function escapesRoot(root: string, candidate: string): boolean;
+/**
+ * Resolve a destination directory under `cwd`.
+ * Returns an error string when the path escapes cwd or is absolute.
+ */
+export declare function resolveContainedOutDir(cwd: string, outRelativeOrDefault: string): {
+    ok: true;
+    outDir: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Walk from `targetPath` up to (and including) `cwdReal`, refusing any symlink.
+ * Missing leaf is fine (we will create it). Every existing ancestor must not
+ * be a symlink.
+ */
+export declare function assertNoSymlinkOnPath(targetPath: string, cwdReal: string): {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Validate a registry entry's package and directory fields.
+ * Both must be relative, normalized, without `..`, absolute form, or NUL.
+ */
+export declare function validateRegistryEntry(entry: AddableComponent): {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Ensure `sourceDir` resolves inside `sourceRoot/packages/<package>`.
+ */
+export declare function resolveContainedSourceDir(sourceRoot: string, entry: AddableComponent): {
+    ok: true;
+    sourceDir: string;
+    packageRoot: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Ensure a source file's real path stays under sourceDir (no symlink escape).
+ */
+export declare function assertSourceFileInside(sourceDir: string, filePath: string): {
+    ok: true;
+    realFile: string;
+} | {
+    ok: false;
+    error: string;
+};

package/dist/internal/paths.js

@@ -0,0 +1,186 @@
+/**
+ * Shared path containment for `@texuli/tools` file writers (`cli-add`, `llms`, …).
+ * Every write stays under a resolved root; every read that claims a source
+ * tree stays under that tree. Symlinks on a destination path are refused.
+ */
+import { existsSync, lstatSync, realpathSync } from 'node:fs';
+import { isAbsolute, normalize, relative, resolve, sep } from 'node:path';
+/** True when `candidate` escapes `root` (after resolve). */
+export function escapesRoot(root, candidate) {
+    const rootResolved = resolve(root);
+    const candidateResolved = resolve(candidate);
+    const rel = relative(rootResolved, candidateResolved);
+    if (rel === '')
+        return false;
+    return rel.startsWith(`..${sep}`) || rel === '..' || isAbsolute(rel);
+}
+function realPathIfExists(path) {
+    try {
+        if (existsSync(path))
+            return realpathSync(path);
+    }
+    catch {
+        // fall through
+    }
+    return resolve(path);
+}
+/**
+ * Resolve a destination directory under `cwd`.
+ * Returns an error string when the path escapes cwd or is absolute.
+ */
+export function resolveContainedOutDir(cwd, outRelativeOrDefault) {
+    const cwdReal = realPathIfExists(cwd);
+    if (isAbsolute(outRelativeOrDefault) ||
+        /^[A-Za-z]:[\\/]/.test(outRelativeOrDefault) ||
+        outRelativeOrDefault.startsWith('\\\\')) {
+        return {
+            ok: false,
+            error: `Destination must be relative to the project root (got absolute path: ${outRelativeOrDefault}).`,
+        };
+    }
+    const resolved = resolve(cwdReal, outRelativeOrDefault);
+    const rel = relative(cwdReal, resolved);
+    if (rel.startsWith(`..${sep}`) || rel === '..' || isAbsolute(rel)) {
+        return {
+            ok: false,
+            error: `Destination escapes the project root: ${outRelativeOrDefault}`,
+        };
+    }
+    return { ok: true, outDir: resolved };
+}
+/**
+ * Walk from `targetPath` up to (and including) `cwdReal`, refusing any symlink.
+ * Missing leaf is fine (we will create it). Every existing ancestor must not
+ * be a symlink.
+ */
+export function assertNoSymlinkOnPath(targetPath, cwdReal) {
+    const cwdResolved = resolve(cwdReal);
+    let current = resolve(targetPath);
+    const relToCwd = relative(cwdResolved, current);
+    if (relToCwd.startsWith(`..${sep}`) || relToCwd === '..' || isAbsolute(relToCwd)) {
+        return { ok: false, error: `Path escapes the project root: ${targetPath}` };
+    }
+    while (true) {
+        if (existsSync(current)) {
+            try {
+                const st = lstatSync(current);
+                if (st.isSymbolicLink()) {
+                    return {
+                        ok: false,
+                        error: `Refusing to write through a symlink: ${current}`,
+                    };
+                }
+            }
+            catch (error) {
+                return {
+                    ok: false,
+                    error: `Cannot inspect path ${current}: ${error instanceof Error ? error.message : String(error)}`,
+                };
+            }
+        }
+        if (current === cwdResolved)
+            break;
+        const parent = resolve(current, '..');
+        if (parent === current)
+            break;
+        const relParent = relative(cwdResolved, parent);
+        if (relParent.startsWith(`..${sep}`) || relParent === '..' || isAbsolute(relParent)) {
+            break;
+        }
+        current = parent;
+    }
+    return { ok: true };
+}
+/**
+ * Validate a registry entry's package and directory fields.
+ * Both must be relative, normalized, without `..`, absolute form, or NUL.
+ */
+export function validateRegistryEntry(entry) {
+    const checkRelativeField = (name, value) => {
+        if (typeof value !== 'string' || value.length === 0) {
+            return `Registry ${name} must be a non-empty string.`;
+        }
+        if (value.includes('\0')) {
+            return `Registry ${name} must not contain NUL.`;
+        }
+        if (isAbsolute(value) || /^[A-Za-z]:[\\/]/.test(value) || value.startsWith('\\\\')) {
+            return `Registry ${name} must be relative (got absolute: ${value}).`;
+        }
+        // Inspect raw segments before normalize() collapses `a/../b` into `b`.
+        const rawSegments = value.split(/[/\\]/);
+        if (rawSegments.some((s) => s === '..')) {
+            return `Registry ${name} must not contain '..' segments (got: ${value}).`;
+        }
+        const normalized = normalize(value);
+        const segments = normalized.split(/[/\\]/).filter((s) => s.length > 0);
+        if (segments.some((s) => s === '..') ||
+            normalized === '..' ||
+            normalized.startsWith(`..${sep}`)) {
+            return `Registry ${name} must not contain '..' segments (got: ${value}).`;
+        }
+        return null;
+    };
+    const packageError = checkRelativeField('package', entry.package);
+    if (packageError)
+        return { ok: false, error: packageError };
+    // package is a bare name or @scope/name (one slash max for scope).
+    const pkgSegments = entry.package.split('/').filter(Boolean);
+    if (entry.package.includes('\\') || pkgSegments.length > 2) {
+        return { ok: false, error: `Registry package must be a package name (got: ${entry.package}).` };
+    }
+    if (pkgSegments.length === 2 && !entry.package.startsWith('@')) {
+        return { ok: false, error: `Registry package must be a package name (got: ${entry.package}).` };
+    }
+    const directoryError = checkRelativeField('directory', entry.directory);
+    if (directoryError)
+        return { ok: false, error: directoryError };
+    return { ok: true };
+}
+/**
+ * Ensure `sourceDir` resolves inside `sourceRoot/packages/<package>`.
+ */
+export function resolveContainedSourceDir(sourceRoot, entry) {
+    const entryCheck = validateRegistryEntry(entry);
+    if (!entryCheck.ok)
+        return entryCheck;
+    const rootReal = realPathIfExists(sourceRoot);
+    const packagesRoot = resolve(rootReal, 'packages');
+    const packageRoot = resolve(packagesRoot, entry.package);
+    if (escapesRoot(packagesRoot, packageRoot)) {
+        return {
+            ok: false,
+            error: `Package path escapes packages/: ${entry.package}`,
+        };
+    }
+    const sourceDir = resolve(packageRoot, entry.directory);
+    if (escapesRoot(packageRoot, sourceDir)) {
+        return {
+            ok: false,
+            error: `Source directory escapes package root: ${entry.directory}`,
+        };
+    }
+    return { ok: true, sourceDir, packageRoot };
+}
+/**
+ * Ensure a source file's real path stays under sourceDir (no symlink escape).
+ */
+export function assertSourceFileInside(sourceDir, filePath) {
+    const sourceReal = realPathIfExists(sourceDir);
+    let fileReal;
+    try {
+        fileReal = existsSync(filePath) ? realpathSync(filePath) : resolve(filePath);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            error: `Cannot resolve source file ${filePath}: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    if (escapesRoot(sourceReal, fileReal)) {
+        return {
+            ok: false,
+            error: `Source file escapes component directory: ${filePath}`,
+        };
+    }
+    return { ok: true, realFile: fileReal };
+}

package/dist/llms/bundle.d.ts

@@ -0,0 +1,6 @@
+import type { LlmsBundle, LlmsBundleOptions } from './types.js';
+/**
+ * Build `llms.txt`, `llms-full.txt` and per-component Markdown from catalog data.
+ * Pure: no filesystem.
+ */
+export declare function buildLlmsBundle(options: LlmsBundleOptions): LlmsBundle;

package/dist/llms/bundle.js

@@ -0,0 +1,47 @@
+import { componentDocPath, formatComponentMarkdown, formatLlmsFullTxt, formatLlmsTxt, } from "./format.js";
+function entriesFromOptions(options) {
+    if (options.catalog) {
+        return [...options.catalog.entries];
+    }
+    if (options.manifests) {
+        return [...options.manifests];
+    }
+    throw new Error('LlmsBundleOptions requires either catalog or manifests.');
+}
+/**
+ * Build `llms.txt`, `llms-full.txt` and per-component Markdown from catalog data.
+ * Pure: no filesystem.
+ */
+export function buildLlmsBundle(options) {
+    const entries = entriesFromOptions(options);
+    const baseUrl = options.baseUrl ?? '';
+    const title = options.title ?? 'Texuli';
+    const summary = options.summary ??
+        'Texuli is a Svelte 5 component system with a closed agent catalog and a sink-free renderer.';
+    const llmsTxt = formatLlmsTxt(entries, {
+        title,
+        summary,
+        intro: options.intro,
+        baseUrl,
+        splitTiers: options.splitTiers,
+    });
+    const llmsFullTxt = formatLlmsFullTxt(entries, { title, baseUrl });
+    const components = [...entries]
+        .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+        .map((entry) => ({
+        path: componentDocPath(entry.id),
+        body: formatComponentMarkdown(entry, { baseUrl, fromComponents: true }),
+    }));
+    const files = [
+        { path: 'llms.txt', body: llmsTxt },
+        { path: 'llms-full.txt', body: llmsFullTxt },
+        ...components,
+    ].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    return {
+        llmsTxt,
+        llmsFullTxt,
+        components,
+        files,
+        entryCount: entries.length,
+    };
+}

package/dist/llms/cli.d.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * CLI: generate llms.txt + agent docs from the live catalog manifests.
+ *
+ *   pnpm exec tsx packages/tools/src/llms/cli.ts --out apps/website/public/llms --json
+ */
+export interface LlmsCliArgs {
+    outDir: string;
+    baseUrl: string;
+    title: string;
+    dryRun: boolean;
+    json: boolean;
+    help: boolean;
+}
+export declare function parseLlmsArgs(argv: string[]): LlmsCliArgs;
+export declare function runLlmsCli(argv?: string[]): Promise<{
+    ok: true;
+    files: number;
+    outDir: string;
+} | {
+    ok: false;
+    error: string;
+}>;
+export declare function isMainModule(metaUrl: string): boolean;

package/dist/llms/cli.js

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+/// <reference types="node" />
+/**
+ * CLI: generate llms.txt + agent docs from the live catalog manifests.
+ *
+ *   pnpm exec tsx packages/tools/src/llms/cli.ts --out apps/website/public/llms --json
+ */
+import { fileURLToPath } from 'node:url';
+import { buildCatalog } from '@texuli/catalog/build';
+import { discoverManifestGroups } from '@texuli/catalog/build/node';
+import { buildLlmsBundle } from "./bundle.js";
+import { writeLlmsBundle } from "./write.js";
+export function parseLlmsArgs(argv) {
+    const args = {
+        outDir: 'dist/llms',
+        baseUrl: '',
+        title: 'Texuli',
+        dryRun: false,
+        json: false,
+        help: false,
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i] ?? '';
+        if (arg === '--help' || arg === '-h')
+            args.help = true;
+        else if (arg === '--dry-run')
+            args.dryRun = true;
+        else if (arg === '--json')
+            args.json = true;
+        else if (arg === '--out' || arg === '-o') {
+            args.outDir = argv[++i] ?? args.outDir;
+        }
+        else if (arg === '--base-url') {
+            args.baseUrl = argv[++i] ?? '';
+        }
+        else if (arg === '--title') {
+            args.title = argv[++i] ?? args.title;
+        }
+        else if (arg.startsWith('-')) {
+            throw new Error(`Unknown flag: ${arg}`);
+        }
+    }
+    return args;
+}
+export async function runLlmsCli(argv = process.argv.slice(2)) {
+    try {
+        const args = parseLlmsArgs(argv);
+        if (args.help) {
+            const help = `Usage: texuli-llms [--out <dir>] [--base-url <url>] [--title <name>] [--dry-run] [--json]
+
+Generate llms.txt, llms-full.txt and components/<id>.md from catalog manifests.
+`;
+            if (!args.json)
+                process.stdout.write(help);
+            else
+                process.stdout.write(`${JSON.stringify({ ok: true, help }, null, 2)}\n`);
+            return { ok: true, files: 0, outDir: args.outDir };
+        }
+        const groups = await discoverManifestGroups();
+        const { catalog, hash } = await buildCatalog(groups);
+        const bundle = buildLlmsBundle({
+            catalog,
+            baseUrl: args.baseUrl,
+            title: args.title,
+        });
+        const result = await writeLlmsBundle(args.outDir, bundle, { dryRun: args.dryRun });
+        if (args.json) {
+            process.stdout.write(`${JSON.stringify({
+                ok: true,
+                outDir: result.outDir,
+                dryRun: result.dryRun,
+                entryCount: bundle.entryCount,
+                files: result.written,
+                catalogHash: hash,
+            }, null, 2)}\n`);
+        }
+        else {
+            process.stdout.write(`Wrote ${result.written.length} files to ${result.outDir} (${bundle.entryCount} components)${result.dryRun ? ' [dry-run]' : ''}\n`);
+        }
+        return { ok: true, files: result.written.length, outDir: result.outDir };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`${message}\n`);
+        return { ok: false, error: message };
+    }
+}
+export function isMainModule(metaUrl) {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return fileURLToPath(metaUrl) === entry;
+    }
+    catch {
+        return false;
+    }
+}
+if (isMainModule(import.meta.url)) {
+    runLlmsCli().then((result) => {
+        if (!result.ok)
+            process.exitCode = 1;
+    });
+}

package/dist/llms/format.d.ts

@@ -0,0 +1,35 @@
+import type { CatalogEntry } from '@texuli/catalog/build';
+import type { CatalogManifest } from '@texuli/catalog/manifest';
+/** Stable path for a component doc: `components/<id>.md`. */
+export declare function componentDocPath(id: string): string;
+/** Link href for llms.txt (relative or absolute). */
+export declare function componentHref(id: string, baseUrl?: string): string;
+/**
+ * Full Markdown page for one catalog entry (agent-facing).
+ * No HTML; plain Markdown only.
+ */
+export declare function formatComponentMarkdown(entry: CatalogManifest | CatalogEntry, options?: {
+    baseUrl?: string;
+    relatedLinks?: boolean;
+    fromComponents?: boolean;
+}): string;
+/** One llms.txt link line. */
+export declare function formatLlmsLink(entry: CatalogManifest | CatalogEntry, baseUrl?: string): string;
+/**
+ * Compact `llms.txt` index (llmstxt.org-style).
+ * Sections: overview, agent-emittable (Tier U + developer), app chrome.
+ */
+export declare function formatLlmsTxt(entries: readonly (CatalogManifest | CatalogEntry)[], options?: {
+    title?: string;
+    summary?: string;
+    intro?: readonly string[];
+    baseUrl?: string;
+    splitTiers?: boolean;
+}): string;
+/**
+ * `llms-full.txt`: every component Markdown page concatenated with clear separators.
+ */
+export declare function formatLlmsFullTxt(entries: readonly (CatalogManifest | CatalogEntry)[], options?: {
+    baseUrl?: string;
+    title?: string;
+}): string;