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

package/dist/cli-init/files.js

@@ -0,0 +1,59 @@
+/// <reference types="node" />
+/**
+ * Contained reads and writes for `texuli init` and `texuli theme`: every
+ * destination resolves inside the project root and no symlink may sit on its
+ * path (even with `--force`).
+ */
+import { existsSync, lstatSync, realpathSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { assertNoSymlinkOnPath, resolveContainedOutDir } from "../internal/paths.js";
+import { projectPathError } from "./safe-path.js";
+export function openProject(cwd) {
+    if (!existsSync(cwd))
+        return `Project root does not exist: ${cwd}`;
+    return { root: realpathSync(cwd) };
+}
+/** Resolves a project-relative path, or explains why it is refused. */
+export function resolveInProject(project, rel, name = 'Path') {
+    const pathError = projectPathError(name, rel);
+    if (pathError)
+        return { error: pathError };
+    const contained = resolveContainedOutDir(project.root, rel);
+    if (!contained.ok)
+        return { error: contained.error };
+    const symlink = assertNoSymlinkOnPath(contained.outDir, project.root);
+    if (!symlink.ok)
+        return { error: symlink.error };
+    if (existsSync(contained.outDir) && !lstatSync(contained.outDir).isFile()) {
+        return { error: `${name} is not a regular file: ${rel}` };
+    }
+    return contained.outDir;
+}
+/** Reads a project file (null when missing), refusing paths outside the project or through symlinks. */
+export async function readProjectFile(project, rel, name) {
+    const path = resolveInProject(project, rel, name);
+    if (typeof path !== 'string')
+        return path;
+    return existsSync(path) ? readFile(path, 'utf8') : null;
+}
+/** A planned write: compare, then (unless dry run) write through the containment checks again. */
+export async function writeProjectFile(project, rel, before, after, dryRun) {
+    const change = {
+        path: rel,
+        action: before === null ? 'create' : before === after ? 'unchanged' : 'update',
+        bytes: Buffer.byteLength(after),
+    };
+    if (dryRun || change.action === 'unchanged')
+        return change;
+    // Check again right before writing: the tree may have changed since planning.
+    const path = resolveInProject(project, rel);
+    if (typeof path !== 'string')
+        return path;
+    await mkdir(dirname(path), { recursive: true });
+    const parent = assertNoSymlinkOnPath(dirname(path), project.root);
+    if (!parent.ok)
+        return { error: parent.error };
+    await writeFile(path, after);
+    return change;
+}

package/dist/cli-init/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `texuli init` and `texuli theme` (`@texuli/tools/cli-init`): wire tokens
+ * and CSS into Vite, Astro and SvelteKit projects; list, preview and apply
+ * themes. Node only, no network.
+ */
+export { type InitCliArgs, parseInitArgs, runInitCli, USAGE } from './cli.js';
+export { CONFIG_FILE, formatConfig, parseConfig } from './config.js';
+export { DEFAULTS, detectFramework, FRAMEWORKS } from './detect.js';
+export { DEFAULT_NAMESPACE, DEFAULT_THEME, initProject } from './init.js';
+export { projectPathError } from './safe-path.js';
+export { applyProjectTheme } from './theme-apply.js';
+export { listThemes, PREVIEW_TOKENS, previewTheme, type ThemePreview, type ThemeSummary, } from './themes.js';
+export type { CommandResult, FileChange, Framework, InitOptions, InitResult, TexuliConfig, ThemeApplyOptions, } from './types.js';
+export { CSS_HEADER, documentTheme, importSpecifier, isGeneratedStylesheet, stylesheet, withCssImport, withDocumentWiring, withTheme, } from './wire.js';

package/dist/cli-init/index.js

@@ -0,0 +1,13 @@
+/**
+ * `texuli init` and `texuli theme` (`@texuli/tools/cli-init`): wire tokens
+ * and CSS into Vite, Astro and SvelteKit projects; list, preview and apply
+ * themes. Node only, no network.
+ */
+export { parseInitArgs, runInitCli, USAGE } from "./cli.js";
+export { CONFIG_FILE, formatConfig, parseConfig } from "./config.js";
+export { DEFAULTS, detectFramework, FRAMEWORKS } from "./detect.js";
+export { DEFAULT_NAMESPACE, DEFAULT_THEME, initProject } from "./init.js";
+export { projectPathError } from "./safe-path.js";
+export { applyProjectTheme } from "./theme-apply.js";
+export { listThemes, PREVIEW_TOKENS, previewTheme, } from "./themes.js";
+export { CSS_HEADER, documentTheme, importSpecifier, isGeneratedStylesheet, stylesheet, withCssImport, withDocumentWiring, withTheme, } from "./wire.js";

package/dist/cli-init/init.d.ts

@@ -0,0 +1,14 @@
+import { type Project } from './files.js';
+import type { CommandResult, InitOptions, InitResult } from './types.js';
+export declare const DEFAULT_THEME = "enterprise-neutral";
+export declare const DEFAULT_NAMESPACE = "app";
+/** The edits for one project, in order: stylesheet, entry, document, config. */
+interface Edit {
+    path: string;
+    before: string | null;
+    after: string;
+}
+/** Writes the planned edits (or only reports them in a dry run). */
+export declare function applyEdits(project: Project, edits: Edit[], dryRun: boolean): Promise<CommandResult>;
+export declare function initProject(options: InitOptions): Promise<InitResult>;
+export {};

package/dist/cli-init/init.js

@@ -0,0 +1,157 @@
+/// <reference types="node" />
+/**
+ * `texuli init`: wires Texuli's tokens and CSS into a Vite, Astro or
+ * SvelteKit project. It writes the generated stylesheet (base styles and a
+ * theme), imports it from the framework's entry, puts the no-flash
+ * bootstrap and `data-tx-theme` on the document, and records the choices in
+ * `texuli.config.json`. Re-running it changes nothing. No network.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { noFlashScript } from '@texuli/tokens/no-flash';
+import { CONFIG_FILE, formatConfig, isId, parseConfig } from "./config.js";
+import { DEFAULTS, detectFramework } from "./detect.js";
+import { openProject, readProjectFile, writeProjectFile } from "./files.js";
+import { projectPathError } from "./safe-path.js";
+import { themeCss, themeExists } from "./themes.js";
+import { importSpecifier, isGeneratedStylesheet, stylesheet, withCssImport, withDocumentWiring, withTheme, } from "./wire.js";
+export const DEFAULT_THEME = 'enterprise-neutral';
+export const DEFAULT_NAMESPACE = 'app';
+const failed = (errors, dryRun) => ({
+    ok: false,
+    dryRun,
+    files: [],
+    errors,
+    notes: [],
+});
+function firstExisting(project, candidates) {
+    return candidates.find((rel) => existsSync(join(project.root, rel))) ?? candidates[0];
+}
+/** Writes the planned edits (or only reports them in a dry run). */
+export async function applyEdits(project, edits, dryRun) {
+    const files = [];
+    const errors = [];
+    for (const edit of edits) {
+        const change = await writeProjectFile(project, edit.path, edit.before, edit.after, dryRun);
+        if ('error' in change) {
+            errors.push(change.error);
+            break;
+        }
+        files.push(change);
+    }
+    return { ok: errors.length === 0, dryRun, files, errors, notes: [] };
+}
+export async function initProject(options) {
+    const dryRun = options.dryRun === true;
+    const force = options.force === true;
+    const opened = openProject(options.cwd);
+    if (typeof opened === 'string')
+        return failed([opened], dryRun);
+    const project = opened;
+    // The framework: explicit, or from package.json.
+    let framework = options.framework;
+    if (!framework) {
+        const pkg = await readProjectFile(project, 'package.json', 'package.json');
+        if (pkg !== null && typeof pkg === 'object')
+            return failed([pkg.error], dryRun);
+        if (pkg === null)
+            return failed(['No package.json: pass --framework vite|astro|sveltekit.'], dryRun);
+        let parsed;
+        try {
+            parsed = JSON.parse(pkg);
+        }
+        catch {
+            return failed(['package.json is not valid JSON.'], dryRun);
+        }
+        framework = detectFramework(parsed) ?? undefined;
+        if (!framework) {
+            return failed(['Could not detect Vite, Astro or SvelteKit in package.json: pass --framework.'], dryRun);
+        }
+    }
+    const defaults = DEFAULTS[framework];
+    const theme = options.theme ?? DEFAULT_THEME;
+    const namespace = options.namespace ?? DEFAULT_NAMESPACE;
+    const css = options.css ?? defaults.css;
+    const errors = [];
+    if (!isId(theme) || !(await themeExists(theme))) {
+        errors.push(`Unknown theme: ${theme}. Run \`texuli theme list\`.`);
+    }
+    if (!isId(namespace))
+        errors.push(`--namespace must be a kebab-case id (got: ${namespace}).`);
+    const cssError = projectPathError('--css', css);
+    if (cssError)
+        errors.push(cssError);
+    else if (!css.endsWith('.css'))
+        errors.push(`--css must name a .css file (got: ${css}).`);
+    if (errors.length > 0)
+        return failed(errors, dryRun);
+    const config = {
+        framework,
+        css,
+        entry: firstExisting(project, defaults.entries),
+        document: firstExisting(project, defaults.document),
+        theme,
+        namespace,
+    };
+    // Read everything first: any refusal stops before a single write.
+    const read = async (rel, name) => readProjectFile(project, rel, name);
+    const sources = {
+        css: await read(config.css, 'Stylesheet'),
+        entry: await read(config.entry, 'Entry'),
+        document: await read(config.document, 'Document'),
+        config: await read(CONFIG_FILE, CONFIG_FILE),
+    };
+    for (const source of Object.values(sources)) {
+        if (source !== null && typeof source === 'object')
+            errors.push(source.error);
+    }
+    if (errors.length > 0)
+        return failed(errors, dryRun);
+    const text = (value) => typeof value === 'string' ? value : null;
+    const compiled = await themeCss(theme);
+    const cssBefore = text(sources.css);
+    let cssAfter;
+    if (cssBefore === null)
+        cssAfter = stylesheet(theme, compiled);
+    else if (isGeneratedStylesheet(cssBefore))
+        cssAfter = withTheme(cssBefore, theme, compiled);
+    else if (force)
+        cssAfter = stylesheet(theme, compiled);
+    else {
+        return failed([
+            `${config.css} exists and was not generated by texuli: pass --force to replace it, or --css <path>.`,
+        ], dryRun);
+    }
+    const configBefore = text(sources.config);
+    if (configBefore !== null && 'errors' in parseConfig(configBefore) && !force) {
+        return failed([`${CONFIG_FILE} exists but is not a valid texuli config: pass --force to replace it.`], dryRun);
+    }
+    const entryBefore = text(sources.entry);
+    const entryAfter = withCssImport(entryBefore, config.entry, importSpecifier(config.entry, config.css));
+    const astro = framework === 'astro';
+    // In Astro the layout is both the entry and the document.
+    const documentBefore = config.document === config.entry ? entryAfter : text(sources.document);
+    const notes = [];
+    const edits = [{ path: config.css, before: cssBefore, after: cssAfter }];
+    const documentAfter = documentBefore === null
+        ? null
+        : withDocumentWiring(documentBefore, theme, noFlashScript(namespace, 'system'), astro);
+    if (config.document === config.entry) {
+        edits.push({ path: config.entry, before: entryBefore, after: documentAfter ?? entryAfter });
+    }
+    else {
+        edits.push({ path: config.entry, before: entryBefore, after: entryAfter });
+        if (documentAfter !== null) {
+            edits.push({ path: config.document, before: text(sources.document), after: documentAfter });
+        }
+    }
+    if (documentAfter === null) {
+        notes.push(`No <html> and <head> in ${config.document}: add data-tx-theme="${theme}" to <html> and the no-flash script (texuli theme apply re-checks).`);
+    }
+    if (astro && entryBefore === null) {
+        notes.push(`Created ${config.entry}: wrap your pages in it so they get the theme.`);
+    }
+    edits.push({ path: CONFIG_FILE, before: configBefore, after: formatConfig(config) });
+    const result = await applyEdits(project, edits, dryRun);
+    return { ...result, notes: [...notes, ...result.notes], config };
+}

package/dist/cli-init/safe-path.d.ts

@@ -0,0 +1,2 @@
+/** Why `value` is not an acceptable project-relative path, or `null`. */
+export declare function projectPathError(name: string, value: unknown): string | null;

package/dist/cli-init/safe-path.js

@@ -0,0 +1,26 @@
+/// <reference types="node" />
+/**
+ * Path rules for `texuli init` and `texuli theme`: CLI and config paths must
+ * be relative, normalized and inside the project. Writes use the shared
+ * containment in `src/internal/paths.ts`.
+ */
+import { isAbsolute, normalize } from 'node:path';
+/** Why `value` is not an acceptable project-relative path, or `null`. */
+export function projectPathError(name, value) {
+    if (typeof value !== 'string' || value.length === 0)
+        return `${name} must be a non-empty path.`;
+    if (value.includes('\0'))
+        return `${name} must not contain NUL.`;
+    if (isAbsolute(value) || /^[A-Za-z]:[\\/]/.test(value) || value.startsWith('\\\\')) {
+        return `${name} must be relative to the project root (got absolute: ${value}).`;
+    }
+    const segments = value.split(/[/\\]/);
+    if (segments.some((segment) => segment === '..')) {
+        return `${name} must not contain '..' segments (got: ${value}).`;
+    }
+    const normalized = normalize(value).replace(/\\/g, '/');
+    if (normalized !== value.replace(/\\/g, '/') || segments.some((segment) => segment === '.')) {
+        return `${name} must be normalized (got: ${value}; use ${normalized}).`;
+    }
+    return null;
+}

package/dist/cli-init/theme-apply.d.ts

@@ -0,0 +1,2 @@
+import type { CommandResult, ThemeApplyOptions } from './types.js';
+export declare function applyProjectTheme(options: ThemeApplyOptions): Promise<CommandResult>;

package/dist/cli-init/theme-apply.js

@@ -0,0 +1,69 @@
+/// <reference types="node" />
+/**
+ * `texuli theme apply <id>`: switches an initialized project to another
+ * theme. It rewrites the theme block of the generated stylesheet and
+ * `data-tx-theme` on the document, then updates `texuli.config.json`.
+ */
+import { noFlashScript } from '@texuli/tokens/no-flash';
+import { CONFIG_FILE, formatConfig, isId, parseConfig } from "./config.js";
+import { openProject, readProjectFile } from "./files.js";
+import { applyEdits } from "./init.js";
+import { themeCss, themeExists } from "./themes.js";
+import { isGeneratedStylesheet, stylesheet, withDocumentWiring, withTheme } from "./wire.js";
+export async function applyProjectTheme(options) {
+    const dryRun = options.dryRun === true;
+    const fail = (errors) => ({
+        ok: false,
+        dryRun,
+        files: [],
+        errors,
+        notes: [],
+    });
+    const opened = openProject(options.cwd);
+    if (typeof opened === 'string')
+        return fail([opened]);
+    if (!isId(options.theme) || !(await themeExists(options.theme))) {
+        return fail([`Unknown theme: ${options.theme}. Run \`texuli theme list\`.`]);
+    }
+    const configText = await readProjectFile(opened, CONFIG_FILE, CONFIG_FILE);
+    if (configText === null)
+        return fail([`No ${CONFIG_FILE}: run \`texuli init\` first.`]);
+    if (typeof configText === 'object')
+        return fail([configText.error]);
+    const parsed = parseConfig(configText);
+    if ('errors' in parsed)
+        return fail(parsed.errors);
+    const config = parsed.config;
+    const css = await readProjectFile(opened, config.css, 'Stylesheet');
+    if (css !== null && typeof css === 'object')
+        return fail([css.error]);
+    const compiled = await themeCss(options.theme);
+    let cssAfter;
+    if (css !== null && isGeneratedStylesheet(css))
+        cssAfter = withTheme(css, options.theme, compiled);
+    else if (options.force === true || css === null)
+        cssAfter = stylesheet(options.theme, compiled);
+    else
+        return fail([`${config.css} lost its texuli markers: pass --force to regenerate it.`]);
+    const document = await readProjectFile(opened, config.document, 'Document');
+    if (document !== null && typeof document === 'object')
+        return fail([document.error]);
+    const edits = [{ path: config.css, before: css, after: cssAfter }];
+    const notes = [];
+    const documentAfter = document === null
+        ? null
+        : withDocumentWiring(document, options.theme, noFlashScript(config.namespace, 'system'), config.framework === 'astro');
+    if (document !== null && documentAfter !== null) {
+        edits.push({ path: config.document, before: document, after: documentAfter });
+    }
+    else {
+        notes.push(`Set data-tx-theme="${options.theme}" on <html> in ${config.document} yourself.`);
+    }
+    edits.push({
+        path: CONFIG_FILE,
+        before: configText,
+        after: formatConfig({ ...config, theme: options.theme }),
+    });
+    const result = await applyEdits(opened, edits, dryRun);
+    return { ...result, notes };
+}

package/dist/cli-init/themes.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The theme side of the CLI: the full Texuli theme library (210 themes),
+ * compiled CSS, a token preview and the WCAG 2.x AA report. Offline: every
+ * theme ships inside `@texuli/tokens`.
+ */
+export interface ThemeSummary {
+    id: string;
+    name: string;
+    collection: string;
+    contrastLevel: string;
+    darkFirst: boolean;
+    description: string;
+}
+export interface ThemePreview extends ThemeSummary {
+    mode: 'light' | 'dark';
+    /** Key tokens for the mode, by custom property name. */
+    tokens: Record<string, string>;
+    /** WCAG 2.x AA gate (both modes). */
+    aa: {
+        pass: boolean;
+        issues: number;
+        modes: {
+            mode: string;
+            pass: boolean;
+            issues: number;
+        }[];
+    };
+}
+/** The tokens a preview shows. */
+export declare const PREVIEW_TOKENS: readonly ["--tx-background", "--tx-foreground", "--tx-primary", "--tx-primary-foreground", "--tx-secondary", "--tx-accent", "--tx-muted", "--tx-muted-foreground", "--tx-border", "--tx-ring", "--tx-destructive", "--tx-success", "--tx-warning", "--tx-radius", "--tx-font-sans"];
+/** Every theme, or those matching `search` (all words must match). */
+export declare function listThemes(search?: string): Promise<ThemeSummary[]>;
+export declare function themeExists(id: string): Promise<boolean>;
+/** Compiled CSS for a theme (light and dark rules). */
+export declare function themeCss(id: string): Promise<string>;
+/** Key tokens and the AA report for one theme in one mode. */
+export declare function previewTheme(id: string, mode: 'light' | 'dark'): Promise<ThemePreview | null>;

package/dist/cli-init/themes.js

@@ -0,0 +1,83 @@
+/**
+ * The theme side of the CLI: the full Texuli theme library (210 themes),
+ * compiled CSS, a token preview and the WCAG 2.x AA report. Offline: every
+ * theme ships inside `@texuli/tokens`.
+ */
+import { compileThemeCss, themeVariables } from '@texuli/tokens';
+import { runAaGateOnTheme } from '@texuli/tokens/aa-gate';
+import { getFullThemeMeta, listFullThemeLibrary, loadFullLibraryTheme, searchFullThemeLibrary, } from '@texuli/tokens/library-expand';
+/** The tokens a preview shows. */
+export const PREVIEW_TOKENS = [
+    '--tx-background',
+    '--tx-foreground',
+    '--tx-primary',
+    '--tx-primary-foreground',
+    '--tx-secondary',
+    '--tx-accent',
+    '--tx-muted',
+    '--tx-muted-foreground',
+    '--tx-border',
+    '--tx-ring',
+    '--tx-destructive',
+    '--tx-success',
+    '--tx-warning',
+    '--tx-radius',
+    '--tx-font-sans',
+];
+function summary(meta) {
+    return {
+        id: meta.id,
+        name: meta.name,
+        collection: meta.collection,
+        contrastLevel: meta.contrastLevel,
+        darkFirst: meta.darkFirst,
+        description: meta.description,
+    };
+}
+/** Every theme, or those matching `search` (all words must match). */
+export async function listThemes(search) {
+    const metas = search?.trim()
+        ? await searchFullThemeLibrary(search)
+        : await listFullThemeLibrary();
+    return metas.map(summary);
+}
+export async function themeExists(id) {
+    return (await getFullThemeMeta(id)) !== undefined;
+}
+/** Compiled CSS for a theme (light and dark rules). */
+export async function themeCss(id) {
+    return compileThemeCss(await loadFullLibraryTheme(id));
+}
+/** Key tokens and the AA report for one theme in one mode. */
+export async function previewTheme(id, mode) {
+    const meta = await getFullThemeMeta(id);
+    if (!meta)
+        return null;
+    const theme = await loadFullLibraryTheme(id);
+    const vars = themeVariables({ theme, mode });
+    const tokens = {};
+    for (const name of PREVIEW_TOKENS)
+        if (vars[name] !== undefined)
+            tokens[name] = vars[name];
+    const report = runAaGateOnTheme({
+        id,
+        name: meta.name,
+        contrastLevel: meta.contrastLevel === 'AAA' ? 'AAA' : 'AA',
+        light: theme.light,
+        dark: theme.dark,
+    });
+    return {
+        ...summary(meta),
+        mode,
+        tokens,
+        aa: {
+            pass: report.pass,
+            issues: report.issueCount,
+            modes: report.modes.map((entry) => ({
+                mode: entry.mode,
+                pass: entry.pass,
+                issues: entry.issueCount,
+            })),
+        },
+    };
+}

package/dist/cli-init/types.d.ts

@@ -0,0 +1,50 @@
+/** Project kinds `texuli init` knows how to wire. */
+export type Framework = 'vite' | 'astro' | 'sveltekit';
+/** `texuli.config.json`, written by `init` and read by `theme apply`. */
+export interface TexuliConfig {
+    framework: Framework;
+    /** The generated stylesheet, relative to the project root. */
+    css: string;
+    /** The file that imports the stylesheet. */
+    entry: string;
+    /** The file whose `<html>` carries `data-tx-theme` and the no-flash script. */
+    document: string;
+    /** Theme id from the Texuli theme library. */
+    theme: string;
+    /** The appearance cache namespace for the no-flash script. */
+    namespace: string;
+}
+/** What happened (or would happen) to one file. */
+export interface FileChange {
+    /** Relative to the project root, with forward slashes. */
+    path: string;
+    action: 'create' | 'update' | 'unchanged';
+    bytes: number;
+}
+export interface CommandResult {
+    ok: boolean;
+    dryRun: boolean;
+    files: FileChange[];
+    errors: string[];
+    /** Short next steps for the person or agent. */
+    notes: string[];
+}
+export interface InitOptions {
+    cwd: string;
+    framework?: Framework;
+    theme?: string;
+    /** Stylesheet path relative to the project root (default per framework). */
+    css?: string;
+    namespace?: string;
+    force?: boolean;
+    dryRun?: boolean;
+}
+export type InitResult = CommandResult & {
+    config?: TexuliConfig;
+};
+export interface ThemeApplyOptions {
+    cwd: string;
+    theme: string;
+    force?: boolean;
+    dryRun?: boolean;
+}

package/dist/cli-init/types.js

@@ -0,0 +1 @@
+export {};

package/dist/cli-init/wire.d.ts

@@ -0,0 +1,20 @@
+/** First line of every stylesheet `texuli init` generates. */
+export declare const CSS_HEADER = "/* @texuli/init: generated by `texuli init` and `texuli theme apply`. Keep the markers. */";
+/** The generated stylesheet: base styles, then the theme between markers. */
+export declare function stylesheet(themeId: string, themeCss: string): string;
+/** Whether `source` is a stylesheet `texuli init` generated (and kept its markers). */
+export declare function isGeneratedStylesheet(source: string): boolean;
+/** Replaces the theme block of a generated stylesheet. */
+export declare function withTheme(source: string, themeId: string, themeCss: string): string;
+/** The import specifier from `entry` to `css` (both project-relative). */
+export declare function importSpecifier(entry: string, css: string): string;
+/** Adds `import '<specifier>';` to a JS, TS, Svelte or Astro entry (or creates one). */
+export declare function withCssImport(source: string | null, file: string, specifier: string): string;
+/**
+ * Puts the no-flash bootstrap first in `<head>` (between markers, replaced
+ * on re-run) and sets `data-tx-theme` on `<html>`. Returns `null` when the
+ * document has no `<html>` or `<head>` tag.
+ */
+export declare function withDocumentWiring(source: string, themeId: string, bootstrap: string, astro: boolean): string | null;
+/** The `data-tx-theme` a document declares, if any. */
+export declare function documentTheme(source: string): string | null;

package/dist/cli-init/wire.js

@@ -0,0 +1,90 @@
+/**
+ * Text transforms that wire Texuli into a project's files. Each is
+ * idempotent: applying it to its own output changes nothing. Nothing here
+ * touches the file system.
+ */
+import { posix } from 'node:path';
+/** First line of every stylesheet `texuli init` generates. */
+export const CSS_HEADER = '/* @texuli/init: generated by `texuli init` and `texuli theme apply`. Keep the markers. */';
+const THEME_START = /\/\* texuli:theme [a-z0-9-]+ \*\//;
+const THEME_BLOCK = /\/\* texuli:theme [a-z0-9-]+ \*\/[\s\S]*?\/\* \/texuli:theme \*\//;
+const BOOT_BLOCK = /<!-- texuli:no-flash -->[\s\S]*?<!-- \/texuli:no-flash -->/;
+/** The generated stylesheet: base styles, then the theme between markers. */
+export function stylesheet(themeId, themeCss) {
+    return `${CSS_HEADER}\n@import '@texuli/tokens/base.css';\n\n${themeBlock(themeId, themeCss)}\n`;
+}
+function themeBlock(themeId, themeCss) {
+    return `/* texuli:theme ${themeId} */\n${themeCss.trim()}\n/* /texuli:theme */`;
+}
+/** Whether `source` is a stylesheet `texuli init` generated (and kept its markers). */
+export function isGeneratedStylesheet(source) {
+    return source.startsWith(CSS_HEADER) && THEME_START.test(source) && THEME_BLOCK.test(source);
+}
+/** Replaces the theme block of a generated stylesheet. */
+export function withTheme(source, themeId, themeCss) {
+    return source.replace(THEME_BLOCK, () => themeBlock(themeId, themeCss));
+}
+/** The import specifier from `entry` to `css` (both project-relative). */
+export function importSpecifier(entry, css) {
+    const relative = posix.relative(posix.dirname(entry), css);
+    return relative.startsWith('.') ? relative : `./${relative}`;
+}
+function hasImport(source, specifier) {
+    return source.includes(`import '${specifier}'`) || source.includes(`import "${specifier}"`);
+}
+/** Adds `import '<specifier>';` to a JS, TS, Svelte or Astro entry (or creates one). */
+export function withCssImport(source, file, specifier) {
+    const line = `import '${specifier}';`;
+    if (file.endsWith('.svelte')) {
+        if (source === null) {
+            return `<script lang="ts">\n  ${line}\n  let { children } = $props();\n</script>\n\n{@render children()}\n`;
+        }
+        if (hasImport(source, specifier))
+            return source;
+        const script = /<script\b[^>]*>/.exec(source);
+        if (!script)
+            return `<script lang="ts">\n  ${line}\n</script>\n\n${source}`;
+        const at = script.index + script[0].length;
+        return `${source.slice(0, at)}\n  ${line}${source.slice(at)}`;
+    }
+    if (file.endsWith('.astro')) {
+        if (source === null)
+            return astroLayout(line);
+        if (hasImport(source, specifier))
+            return source;
+        if (source.startsWith('---'))
+            return source.replace(/^---[^\n]*\n/, (open) => `${open}${line}\n`);
+        return `---\n${line}\n---\n\n${source}`;
+    }
+    if (source === null)
+        return `${line}\n`;
+    return hasImport(source, specifier) ? source : `${line}\n${source}`;
+}
+/** A minimal Astro layout for projects that have none. */
+function astroLayout(importLine) {
+    return `---\n${importLine}\n---\n\n<!doctype html>\n<html lang="en">\n  <head>\n    <meta charset="utf-8" />\n    <meta name="viewport" content="width=device-width, initial-scale=1" />\n  </head>\n  <body>\n    <slot />\n  </body>\n</html>\n`;
+}
+/**
+ * Puts the no-flash bootstrap first in `<head>` (between markers, replaced
+ * on re-run) and sets `data-tx-theme` on `<html>`. Returns `null` when the
+ * document has no `<html>` or `<head>` tag.
+ */
+export function withDocumentWiring(source, themeId, bootstrap, astro) {
+    const html = /<html\b[^>]*>/i.exec(source);
+    const head = /<head\b[^>]*>/i.exec(source);
+    if (!html || !head)
+        return null;
+    const script = `<script${astro ? ' is:inline' : ''}>${bootstrap}</script>`;
+    const block = `<!-- texuli:no-flash -->\n    ${script}\n    <!-- /texuli:no-flash -->`;
+    let out = BOOT_BLOCK.test(source)
+        ? source.replace(BOOT_BLOCK, () => block)
+        : `${source.slice(0, head.index + head[0].length)}\n    ${block}${source.slice(head.index + head[0].length)}`;
+    out = out.replace(/<html\b[^>]*>/i, (tag) => /\sdata-tx-theme=/.test(tag)
+        ? tag.replace(/\sdata-tx-theme=(?:"[^"]*"|'[^']*'|[^\s>]+)/, ` data-tx-theme="${themeId}"`)
+        : tag.replace(/^<html/i, `<html data-tx-theme="${themeId}"`));
+    return out;
+}
+/** The `data-tx-theme` a document declares, if any. */
+export function documentTheme(source) {
+    return /<html\b[^>]*\sdata-tx-theme="([^"]*)"/i.exec(source)?.[1] ?? null;
+}