@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/furnace/deploy.js

@@ -0,0 +1,414 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Deploying components into an engine.
+ *
+ * Deployment is a comparison of two states: what the project's components
+ * want the engine to hold (each component file at its engine path, CSS
+ * fragments inlined; the jar.mn lines; the customElements.js entries) and
+ * what the engine holds. Whatever differs is written, in one transaction
+ * together with the deployment record, so an error, a signal or a crash
+ * leaves the engine and its record as they were, and the next run undoes an
+ * interrupted one before planning.
+ *
+ * The record (`furnace-deployment.json` in the workspace's state directory)
+ * says what each component deployed. It describes the engine, not the
+ * project, and serves one purpose the comparison cannot: knowing what to
+ * take away. A file a component no longer has, or every file of a component
+ * no longer configured, is removed; an override's file is put back to the
+ * upstream bytes at the engine's `HEAD`. Everything else is decided from the
+ * bytes on disk, so a reset engine, a hand edit or a lost record is repaired
+ * by the next run, and an unchanged component costs a read and a hash.
+ */
+import { join, posix } from 'node:path';
+import { markerComment } from '../config/index.js';
+import { listTree, readBlobs } from '../git/index.js';
+import { ExitCode } from '../kernel/errors.js';
+import { listDir, pathInfo, readBytes, readBytesIfExists, readTextIfExists, resolveContained, } from '../kernel/fs.js';
+import { hash } from '../kernel/hash.js';
+import { recoverJournal, transaction } from '../kernel/journal.js';
+import { readJsonIfExists, stringifyJson } from '../kernel/json.js';
+import { withLock } from '../kernel/lock.js';
+import { s } from '../kernel/schema.js';
+import { elementJarEntry } from '../register/index.js';
+import { componentDir, CUSTOM_ELEMENTS_JS, fragmentsDir, ftlDir, furnaceError, jarSourceDir, loadFurnaceConfig, WIDGETS_JAR, } from './config.js';
+import { expandFragments } from './fragments.js';
+import { elementEntries, missingJarFiles, planJar, registerElement, unregisterElement, } from './registration.js';
+const DeployedComponent = s.object({
+    kind: s.enum(['custom', 'override']),
+    /** Engine path to the SHA-256 of the bytes deployed there. */
+    files: s.record(s.string()),
+    /** Listed in customElements.js. */
+    registered: s.boolean(),
+    /** The jar.mn source directory the component's lines point into. */
+    jarDir: s.string().optional(),
+});
+const DeploymentRecord = s.object({
+    version: s.literal(1),
+    components: s.record(DeployedComponent),
+});
+const RECORD_FILE = 'furnace-deployment.json';
+const JOURNAL_FILE = 'furnace-deployment.journal';
+const LOCK_DIR = 'furnace.lock';
+function missingComponent(kind, name) {
+    return furnaceError('furnace-component-missing', `furnace.json lists ${kind} component "${name}", but components/${kind === 'custom' ? 'custom' : 'overrides'}/${name}/ does not exist.`, {
+        hint: `Restore the directory, or remove the component with "fireforge furnace remove ${name}".`,
+    });
+}
+/** The regular files of a component directory, by name. */
+async function sourceFiles(dir) {
+    if ((await pathInfo(dir))?.kind !== 'directory')
+        return undefined;
+    return (await listDir(dir)).filter((entry) => entry.kind === 'file').map((entry) => entry.name);
+}
+/** Whether an override of this type deploys the file. */
+export function overrideDeploys(type, file) {
+    if (file === 'override.json')
+        return false;
+    return type === 'css-only' ? file.endsWith('.css') : /\.(?:mjs|css|ftl)$/.test(file);
+}
+async function wantedOverride(project, config, name, entry) {
+    const dir = componentDir(project, 'override', name);
+    const names = await sourceFiles(dir);
+    if (names === undefined)
+        throw missingComponent('override', name);
+    const files = new Map();
+    for (const file of names.filter((candidate) => overrideDeploys(entry.type, candidate))) {
+        const target = file.endsWith('.ftl') ? ftlDir(config) : entry.basePath;
+        files.set(`${target}/${file}`, await readBytes(join(dir, file)));
+    }
+    if (files.size === 0) {
+        throw furnaceError('furnace-component-empty', `Override "${name}" has no file to deploy (${entry.type === 'css-only' ? '.css' : '.mjs, .css or .ftl'}).`);
+    }
+    return { name, kind: 'override', files, registered: false, jar: [] };
+}
+async function wantedCustom(project, config, name, entry) {
+    const dir = componentDir(project, 'custom', name);
+    const names = await sourceFiles(dir);
+    if (names === undefined)
+        throw missingComponent('custom', name);
+    const jarDir = jarSourceDir(entry.targetPath);
+    const files = new Map();
+    const jar = [];
+    for (const file of names.filter((candidate) => /\.(?:mjs|css)$/.test(candidate))) {
+        let content = await readBytes(join(dir, file));
+        if (file.endsWith('.css')) {
+            content = Buffer.from(await expandFragments(content.toString('utf8'), fragmentsDir(project)));
+        }
+        files.set(`${entry.targetPath}/${file}`, content);
+        jar.push(elementJarEntry(jarDir, file));
+    }
+    if (entry.localized && entry.sharedFtl === undefined && names.includes(`${name}.ftl`)) {
+        files.set(`${ftlDir(config)}/${name}.ftl`, await readBytes(join(dir, `${name}.ftl`)));
+    }
+    // Without its module the entry would name a script that does not exist.
+    const registered = entry.register && names.includes(`${name}.mjs`);
+    return { name, kind: 'custom', files, registered, jarDir, jar };
+}
+async function wantedComponents(project, config) {
+    const wanted = [];
+    for (const [name, entry] of Object.entries(config.overrides)) {
+        wanted.push(await wantedOverride(project, config, name, entry));
+    }
+    for (const [name, entry] of Object.entries(config.custom)) {
+        wanted.push(await wantedCustom(project, config, name, entry));
+    }
+    return wanted;
+}
+/**
+ * The engine files every configured component deploys, read from the
+ * project's component sources without an engine.
+ *
+ * @param project - The project
+ * @param config - Its component configuration
+ * @returns Per component, the content by engine path
+ * @throws `furnace-component-missing` or `furnace-component-empty` (exit code 9)
+ */
+export async function componentFiles(project, config) {
+    return (await wantedComponents(project, config)).map(({ name, files }) => ({ name, files }));
+}
+async function readRecord(workspace) {
+    const path = join(workspace.stateDir, RECORD_FILE);
+    const record = await readJsonIfExists(path, DeploymentRecord, {
+        code: 'furnace-deployment-invalid',
+        exitCode: ExitCode.CONFIG_ERROR,
+        hint: `Delete ${path} and run "fireforge furnace apply"; files of components removed since the last deployment then stay in the engine.`,
+    });
+    return record ?? { version: 1, components: {} };
+}
+/** Compares one component's files with the engine, filling the plan. */
+async function planFiles(workspace, wanted, previous, plan) {
+    const reasons = [];
+    const hashes = {};
+    for (const [path, content] of wanted.files) {
+        const digest = hash(content);
+        hashes[path] = digest;
+        const engine = await readBytesIfExists(await resolveContained(workspace.engineDir, path));
+        if (engine !== undefined && hash(engine) === digest)
+            continue;
+        plan.writes.set(path, content);
+        const recorded = previous?.kind === wanted.kind ? previous.files[path] : undefined;
+        reasons.push(recorded === undefined
+            ? `${path} is not deployed`
+            : recorded !== digest
+                ? `${path} changed in the project`
+                : `${path} ${engine === undefined ? 'is missing from' : 'was changed in'} the engine`);
+    }
+    return { reasons, hashes };
+}
+/** Records the engine paths of a deployed component that are no longer wanted, with their owner's kind. */
+function planRemovals(previous, keep, gone) {
+    const paths = Object.keys(previous.files).filter((path) => keep?.has(path) !== true);
+    for (const path of paths)
+        gone.set(path, previous.kind);
+    return paths;
+}
+/**
+ * What to do with each path taken away: a custom component's file is
+ * deleted, an override's is put back to upstream (deleted where upstream
+ * has none). A path another component now writes is left to that write.
+ */
+async function resolveRemovals(workspace, gone, writes) {
+    const paths = [...gone.keys()].filter((path) => !writes.has(path));
+    const restore = paths.filter((path) => gone.get(path) === 'override');
+    const upstream = restore.length === 0 ? new Map() : await upstreamFiles(workspace, restore);
+    return new Map(paths.map((path) => [path, upstream.get(path) ?? null]));
+}
+async function assertOverrideTargets(workspace, config) {
+    for (const [name, entry] of Object.entries(config.overrides)) {
+        const target = await resolveContained(workspace.engineDir, entry.basePath);
+        if ((await pathInfo(target))?.kind !== 'directory') {
+            throw furnaceError('furnace-override-target-missing', `Override "${name}" replaces files in ${entry.basePath}, which the engine does not have.`, { hint: 'Correct its basePath in furnace.json, or remove the override.' });
+        }
+    }
+}
+async function readEngineFile(workspace, path) {
+    const text = await readTextIfExists(join(workspace.engineDir, path));
+    if (text !== undefined)
+        return text;
+    throw furnaceError('furnace-engine-incomplete', `The engine has no ${path}.`, {
+        hint: 'Components register in it; restore the engine from upstream.',
+    });
+}
+/** Plans the jar.mn lines, attributing missing ones to their components. */
+async function planJarFile(workspace, wanted, ownedDirs, reasons) {
+    const lines = wanted.flatMap((component) => component.jar);
+    if (lines.length === 0 && ownedDirs.length === 0)
+        return undefined;
+    const text = await readEngineFile(workspace, WIDGETS_JAR);
+    const next = planJar(text, lines, ownedDirs);
+    if (next === text)
+        return undefined;
+    for (const component of wanted) {
+        const missing = missingJarFiles(text, component.jar);
+        if (missing.length > 0) {
+            reasons
+                .get(component.name)
+                ?.push(`${WIDGETS_JAR} lacks ${missing.map((file) => file.target).join(', ')}`);
+        }
+    }
+    return next;
+}
+/** Plans the customElements.js entries: owned tags no longer wanted go, wanted tags are listed. */
+async function planElements(workspace, marker, wantedTags, ownedTags, reasons) {
+    if (wantedTags.length === 0 && ownedTags.length === 0)
+        return undefined;
+    const text = await readEngineFile(workspace, CUSTOM_ELEMENTS_JS);
+    let next = text;
+    for (const tag of ownedTags.filter((owned) => !wantedTags.includes(owned))) {
+        next = unregisterElement(next, tag);
+    }
+    const listed = new Set(elementEntries(text)
+        .filter((entry) => entry.module)
+        .map((entry) => entry.tag));
+    for (const tag of wantedTags) {
+        const before = next;
+        next = registerElement(next, tag, marker);
+        if (!listed.has(tag) && next !== before) {
+            reasons.get(tag)?.push(`${CUSTOM_ELEMENTS_JS} does not list it as a module element`);
+        }
+    }
+    return next === text ? undefined : next;
+}
+async function makePlan(project, workspace, config) {
+    const previous = await readRecord(workspace);
+    const wanted = await wantedComponents(project, config);
+    await assertOverrideTargets(workspace, config);
+    const plan = {
+        writes: new Map(),
+        removals: new Map(),
+        jar: undefined,
+        elements: undefined,
+        record: { version: 1, components: {} },
+        recordChanged: false,
+        components: [],
+    };
+    const reasons = new Map();
+    const gone = new Map();
+    for (const component of wanted) {
+        const before = previous.components[component.name];
+        const files = await planFiles(workspace, component, before, plan);
+        if (before !== undefined) {
+            const keep = before.kind === component.kind ? component.files : undefined;
+            const dropped = planRemovals(before, keep, gone);
+            files.reasons.push(...dropped.map((path) => `${path} is no longer part of it`));
+        }
+        reasons.set(component.name, files.reasons);
+        plan.record.components[component.name] = {
+            kind: component.kind,
+            files: files.hashes,
+            registered: component.registered,
+            ...(component.jarDir === undefined ? {} : { jarDir: component.jarDir }),
+        };
+    }
+    const configured = new Set(wanted.map((component) => component.name));
+    const removed = Object.entries(previous.components).filter(([name]) => !configured.has(name));
+    for (const [, before] of removed)
+        planRemovals(before, undefined, gone);
+    plan.removals = await resolveRemovals(workspace, gone, plan.writes);
+    const ownedDirs = [
+        ...new Set([
+            ...wanted.map((component) => component.jarDir),
+            ...Object.values(previous.components).map((c) => c.jarDir),
+        ].filter((dir) => dir !== undefined)),
+    ];
+    plan.jar = await planJarFile(workspace, wanted, ownedDirs, reasons);
+    const wantedTags = wanted
+        .filter((component) => component.registered)
+        .map((component) => component.name);
+    const ownedTags = Object.entries(previous.components)
+        .filter(([, before]) => before.registered)
+        .map(([name]) => name);
+    plan.elements = await planElements(workspace, markerComment(project.config), wantedTags, ownedTags, reasons);
+    plan.components = [
+        ...wanted.map((component) => {
+            const why = reasons.get(component.name) ?? [];
+            return {
+                name: component.name,
+                kind: component.kind,
+                status: why.length === 0 ? 'current' : 'outdated',
+                reasons: why,
+            };
+        }),
+        ...removed.map(([name, before]) => ({
+            name,
+            kind: before.kind,
+            status: 'removed',
+            reasons: ['it is no longer in furnace.json'],
+        })),
+    ];
+    plan.recordChanged = JSON.stringify(plan.record) !== JSON.stringify(previous);
+    return plan;
+}
+function engineChanges(plan) {
+    return (plan.writes.size > 0 ||
+        plan.removals.size > 0 ||
+        plan.jar !== undefined ||
+        plan.elements !== undefined);
+}
+function summarize(plan) {
+    return {
+        changed: engineChanges(plan),
+        components: plan.components,
+        written: [
+            ...plan.writes.keys(),
+            ...[...plan.removals].filter(([, bytes]) => bytes !== null).map(([path]) => path),
+            ...(plan.jar === undefined ? [] : [WIDGETS_JAR]),
+            ...(plan.elements === undefined ? [] : [CUSTOM_ELEMENTS_JS]),
+        ].sort(),
+        removed: [...plan.removals.keys()].sort(),
+    };
+}
+/**
+ * Deploys the project's components into a workspace's engine: writes every
+ * component file whose engine copy differs, removes what components no
+ * longer have, and brings jar.mn and customElements.js in line, all in one
+ * transaction with the deployment record. Unchanged components cost a read
+ * and a hash; with nothing to change nothing is written.
+ *
+ * @param project - The project whose `furnace.json` and `components/` are deployed
+ * @param workspace - The engine to deploy into
+ * @param options - See {@link ApplyOptions}
+ * @throws `furnace-component-missing`, `furnace-override-target-missing`,
+ *   `furnace-fragment-missing`, `furnace-engine-incomplete`, `manifest-invalid`
+ *   (a jar.mn conflict) or `furnace-custom-elements-unreadable`; the engine is then unchanged
+ */
+export async function applyComponents(project, workspace, options = {}) {
+    const journal = join(workspace.stateDir, JOURNAL_FILE);
+    const lockOptions = {
+        label: 'furnace deployment',
+        ...(options.waitMs === undefined ? {} : { waitMs: options.waitMs }),
+    };
+    return withLock(join(workspace.stateDir, LOCK_DIR), lockOptions, async () => {
+        if (options.dryRun !== true)
+            await recoverJournal(journal);
+        const plan = await makePlan(project, workspace, await loadFurnaceConfig(project));
+        const result = summarize(plan);
+        if (options.dryRun === true || (!result.changed && !plan.recordChanged))
+            return result;
+        await transaction(journal, 'the component deployment', async (tx) => {
+            const at = (path) => resolveContained(workspace.engineDir, path);
+            for (const [path, content] of plan.writes)
+                await tx.write(await at(path), content);
+            for (const [path, upstream] of plan.removals) {
+                if (upstream === null)
+                    await tx.remove(await at(path));
+                else
+                    await tx.write(await at(path), upstream);
+            }
+            if (plan.jar !== undefined)
+                await tx.write(join(workspace.engineDir, WIDGETS_JAR), plan.jar);
+            if (plan.elements !== undefined) {
+                await tx.write(join(workspace.engineDir, CUSTOM_ELEMENTS_JS), plan.elements);
+            }
+            await tx.write(join(workspace.stateDir, RECORD_FILE), stringifyJson(plan.record));
+        });
+        return result;
+    });
+}
+/**
+ * Compares the deployed components with the project without changing
+ * anything: the question a build asks before deciding to apply first.
+ *
+ * @param project - The project
+ * @param workspace - The engine to compare
+ */
+export async function deploymentStatus(project, workspace) {
+    const plan = await makePlan(project, workspace, await loadFurnaceConfig(project));
+    return { current: !engineChanges(plan), components: plan.components };
+}
+/**
+ * The upstream bytes of engine paths at the engine's `HEAD`.
+ *
+ * @param workspace - The engine
+ * @param paths - Engine paths
+ * @returns Content by path; a path upstream does not have is absent
+ */
+export async function upstreamFiles(workspace, paths) {
+    const blobs = await readBlobs(workspace.engineDir, paths.map((path) => `HEAD:${path}`));
+    return new Map(paths.flatMap((path) => {
+        const blob = blobs.get(`HEAD:${path}`);
+        return blob === undefined ? [] : [[path, blob]];
+    }));
+}
+/**
+ * The upstream files of an engine directory at `HEAD`, by name (one level).
+ *
+ * @param workspace - The engine
+ * @param dir - Engine directory
+ */
+export async function upstreamDirectory(workspace, dir) {
+    const entries = await listTree(workspace.engineDir, 'HEAD', { paths: [dir] });
+    return entries
+        .filter((entry) => entry.type === 'blob' && posix.dirname(entry.path) === dir)
+        .map((entry) => posix.basename(entry.path));
+}
+/** The deployed content each component file wants, for comparing with the engine. */
+export async function deployedContent(project, config, name) {
+    const entry = config.custom[name];
+    if (entry !== undefined)
+        return (await wantedCustom(project, config, name, entry)).files;
+    const override = config.overrides[name];
+    return override === undefined
+        ? new Map()
+        : (await wantedOverride(project, config, name, override)).files;
+}

package/dist/src/furnace/diff.js

@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `furnace diff`: how the project's components differ from what they are
+ * compared with. A custom component is compared with its deployed copy in
+ * the engine, an override with the stock files at the engine's `HEAD`.
+ */
+import { join } from 'node:path';
+import { gitResult } from '../git/index.js';
+import { ensureDir, makeTempDir, readBytesIfExists, remove, writeFile } from '../kernel/fs.js';
+import { components, findComponent, furnaceError, loadFurnaceConfig, } from './config.js';
+import { deployedContent, upstreamFiles } from './deploy.js';
+/**
+ * A unified diff of one component, or of every component: `engine/<path>`
+ * (custom) or `upstream/<path>` (override) against `project/<path>`, by
+ * engine path.
+ *
+ * @param project - The project
+ * @param workspace - The engine
+ * @param name - One component; all when omitted
+ * @returns The diff text; empty when nothing differs
+ */
+export async function componentDiff(project, workspace, name) {
+    const config = await loadFurnaceConfig(project);
+    const selected = name === undefined ? components(config) : [findComponent(config, name)];
+    const scratch = await makeTempDir('fireforge-furnace-diff-');
+    try {
+        let text = '';
+        for (const [kind, side] of [
+            ['custom', 'engine'],
+            ['override', 'upstream'],
+        ]) {
+            const dir = join(scratch, kind);
+            await ensureDir(join(dir, side));
+            await ensureDir(join(dir, 'project'));
+            for (const component of selected.filter((candidate) => candidate.kind === kind)) {
+                const wanted = await deployedContent(project, config, component.name);
+                const before = kind === 'override' ? await upstreamFiles(workspace, [...wanted.keys()]) : undefined;
+                for (const [path, content] of wanted) {
+                    await writeFile(join(dir, 'project', path), content, { durable: false });
+                    const old = before === undefined
+                        ? await readBytesIfExists(join(workspace.engineDir, path))
+                        : before.get(path);
+                    if (old !== undefined)
+                        await writeFile(join(dir, side, path), old, { durable: false });
+                }
+            }
+            const args = ['diff', '--no-index', '--no-color', '--no-prefix', '--', side, 'project'];
+            const result = await gitResult(args, { cwd: dir });
+            if (result.exitCode > 1) {
+                throw furnaceError('furnace-diff-failed', `git diff failed: ${result.stderr.trim()}`);
+            }
+            text += result.stdout.toString('utf8');
+        }
+        return text;
+    }
+    finally {
+        await remove(scratch);
+    }
+}

package/dist/src/furnace/edit.js

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Edits of the files a project tracks: `components/`, `furnace.json`, the
+ * typing files, and the engine files a component brings along (its tests
+ * and their manifests). Each command's edits run as one transaction under
+ * the project's Furnace edit lock, so a failure or a signal leaves every
+ * file as it was. A dry run runs the same edits against a transaction that
+ * only records what it is asked to change.
+ *
+ * An engine file the project tracks is stored differently per mode: in
+ * patch mode it is `engine/<path>` itself, in source mode `src/<path>`
+ * behind an override record. Furnace never asks which; the caller hands it
+ * a {@link TrackedFiles} that knows.
+ */
+import { join, relative } from 'node:path';
+import { toPosixPath } from '../kernel/fs.js';
+import { transaction } from '../kernel/journal.js';
+import { withLock } from '../kernel/lock.js';
+/** A transaction that passes every change on to `inner` (or, without one, drops it) and records the paths. */
+function recording(inner, paths) {
+    const note = (path) => {
+        if (!paths.includes(path))
+            paths.push(path);
+    };
+    return {
+        async write(path, content, options) {
+            note(path);
+            await inner?.write(path, content, options);
+        },
+        async remove(path) {
+            note(path);
+            await inner?.remove(path);
+        },
+        async change(changed, mutate) {
+            changed.forEach(note);
+            await inner?.change(changed, mutate);
+        },
+    };
+}
+/**
+ * Runs `body` as one transaction under the project's Furnace edit lock and
+ * reports the paths it changed.
+ *
+ * @param project - The project
+ * @param label - What is being done, for messages
+ * @param options - See {@link EditOptions}
+ * @param body - Makes the edits through the transaction and returns notes for the operator
+ */
+export async function editProject(project, label, options, body) {
+    const { root, stateDir } = project.paths;
+    const paths = [];
+    const report = (notes) => ({
+        paths: paths.map((path) => toPosixPath(relative(root, path))),
+        notes,
+    });
+    if (options.dryRun === true)
+        return report(await body(recording(undefined, paths)));
+    const lock = {
+        label: 'furnace edit',
+        ...(options.waitMs === undefined ? {} : { waitMs: options.waitMs }),
+    };
+    const notes = await withLock(join(stateDir, 'furnace-edit.lock'), lock, () => transaction(join(stateDir, 'furnace-edit.journal'), label, (tx) => body(recording(tx, paths))));
+    return report(notes);
+}

package/dist/src/furnace/fragments.js

@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Shared CSS fragments. Shadow DOM makes every widget stylesheet carry its
+ * own copy of genuinely shared rules, so a component stylesheet names a
+ * fragment of `components/shared/` with an include directive on its own
+ * line (`src/syntax` reads the markers). The deployed copy has the fragment
+ * inlined after the directive and fenced by its end marker; the project's
+ * source keeps only the directive. Editing a fragment therefore changes the
+ * deployed content of every includer, which is what makes them stale.
+ */
+import { join } from 'node:path';
+import { readTextIfExists } from '../kernel/fs.js';
+import { fragmentEnd, fragmentExpansions, fragmentInclude, fragmentIncludes, } from '../syntax/index.js';
+import { furnaceError } from './config.js';
+/** Drops fenced expansions, leaving the bare directives, so expansion is idempotent. */
+function stripExpansions(css) {
+    const lines = css.split('\n');
+    const dropped = new Set();
+    for (const [start, end] of fragmentExpansions(lines)) {
+        for (let at = start + 1; at <= end; at++)
+            dropped.add(at);
+    }
+    return lines.filter((_, at) => !dropped.has(at));
+}
+/**
+ * The deployed form of a stylesheet: every directive followed by the
+ * fragment's current text and its end marker.
+ *
+ * @param css - Stylesheet text (a source, or an earlier expansion)
+ * @param sharedDir - The fragments directory
+ * @throws `furnace-fragment-missing` for a fragment that does not exist, or one that includes another
+ */
+export async function expandFragments(css, sharedDir) {
+    const lines = stripExpansions(css);
+    if (!lines.some((line) => fragmentInclude(line) !== undefined))
+        return css;
+    const out = [];
+    for (const line of lines) {
+        out.push(line);
+        const name = fragmentInclude(line);
+        if (name === undefined)
+            continue;
+        const text = await readTextIfExists(join(sharedDir, name));
+        if (text === undefined) {
+            throw furnaceError('furnace-fragment-missing', `CSS fragment "${name}" does not exist in components/shared/.`, { hint: 'Create the fragment or remove the @fireforge-include directive.' });
+        }
+        if (fragmentIncludes(text).length > 0) {
+            throw furnaceError('furnace-fragment-missing', `CSS fragment "${name}" includes another fragment; fragments do not nest.`);
+        }
+        out.push(text.replace(/\n$/, ''), fragmentEnd(name));
+    }
+    return out.join('\n');
+}

package/dist/src/furnace/index.js

@@ -0,0 +1,19 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Furnace: the fork's UI components. Their sources live in the project
+ * (`components/`, described by `furnace.json`); Furnace deploys them into an
+ * engine it is given, validates them, scaffolds and renames them, and
+ * generates the typing files that make them typed for their users.
+ *
+ * Furnace never asks which mode a project is in. Deployment takes the
+ * engine to deploy into ({@link FurnaceWorkspace}); edits of engine files
+ * the project tracks go through the caller's `TrackedFiles`.
+ */
+export { componentHostFiles, loadFurnaceConfig } from './config.js';
+export { applyComponents, componentFiles, deploymentStatus, } from './deploy.js';
+export { componentDiff } from './diff.js';
+export {} from './edit.js';
+export { createComponent, overrideComponent, removeComponent, renameComponent, updateTypingFiles, } from './operations.js';
+export { TEST_STYLES } from './scaffold.js';
+export { typingDrift } from './typing.js';
+export { validateComponents, validationPasses } from './validate.js';