astro-lilypond 0.13.0 → 0.15.0

package/README.md

@@ -13,17 +13,13 @@ Read the docs: https://lilypond.ky.fyi
 
 ## Quick Start
 
-### 1. Install LilyPond
-
-Install the LilyPond binary directly from [lilypond.org](https://lilypond.org/download.html) or with `brew install lilypond` (Mac) or `apt install lilypond` (Linux).
-
-### 2. Install `astro-lilypond`
+### 1. Install `astro-lilypond`
 
 ```sh
 pnpm add astro-lilypond
 ```
 
-### 3. Add the integration to your Astro config
+### 2. Add the integration to your Astro config
 
 ```js
 // astro.config.mjs
@@ -35,7 +31,7 @@ export default defineConfig({
 });
 ```
 
-### 4. Write your music
+### 3. Write your music
 
 Write LilyPond code within fenced code blocks with the `lilypond`, `ly`, or `ily` language tag.
 

package/dist/binary/autoInstall.d.ts

@@ -0,0 +1,13 @@
+import type { LilypondVersion } from "../types/lilypondVersion.js";
+export interface AutoInstallOptions {
+    /**
+     * LilyPond version to download when none is found on `PATH`. Independent
+     * of `defaults.version`, which scores are compiled against.
+     * @default "2.26.0"
+     */
+    version?: LilypondVersion;
+}
+export declare function resolveAutoInstallOption(autoInstall: boolean | AutoInstallOptions | undefined): {
+    version?: LilypondVersion;
+    autoInstall: boolean;
+};

package/dist/binary/autoInstall.js

@@ -0,0 +1,6 @@
+export function resolveAutoInstallOption(autoInstall) {
+    return {
+        version: typeof autoInstall === "object" ? autoInstall.version : undefined,
+        autoInstall: autoInstall !== false,
+    };
+}

package/dist/binary/cacheDir.d.ts

@@ -0,0 +1 @@
+export declare function lilypondCacheDir(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): string;

package/dist/binary/cacheDir.js

@@ -0,0 +1,15 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+export function lilypondCacheDir(env = process.env, platform = process.platform) {
+    if (env.ASTRO_LILYPOND_CACHE_DIR)
+        return env.ASTRO_LILYPOND_CACHE_DIR;
+    if (platform === "darwin") {
+        return join(homedir(), "Library", "Caches", "astro-lilypond");
+    }
+    if (platform === "win32") {
+        const base = env.LOCALAPPDATA ?? join(homedir(), "AppData", "Local");
+        return join(base, "astro-lilypond", "Cache");
+    }
+    const base = env.XDG_CACHE_HOME ?? join(homedir(), ".cache");
+    return join(base, "astro-lilypond");
+}

package/dist/binary/downloadLilypond.d.ts

@@ -0,0 +1,15 @@
+import type { LilypondVersion } from "../types/lilypondVersion.js";
+export interface DownloadLilypondOptions {
+    version: LilypondVersion;
+    cacheDir?: string;
+    fetchImpl?: typeof fetch;
+    log?: (message: string) => void;
+}
+/**
+ * Downloads, verifies, and extracts a prebuilt LilyPond release into the
+ * cache dir, then returns the path to its `bin/lilypond[.exe]`. Returns
+ * `undefined` when LilyPond publishes no prebuilt for the current
+ * platform/arch. A previously-completed install for the same version is
+ * reused as-is.
+ */
+export declare function downloadLilypond({ version, cacheDir, fetchImpl, log, }: DownloadLilypondOptions): Promise<string | undefined>;

package/dist/binary/downloadLilypond.js

@@ -0,0 +1,129 @@
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { access, mkdir, mkdtemp, readdir, rename, rm, writeFile, } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { lilypondCacheDir } from "./cacheDir.js";
+import { resolvePlatformTarget } from "./platformTarget.js";
+const execFileAsync = promisify(execFile);
+function downloadUrlFor(version, platform, arch, archiveExt) {
+    const filename = `lilypond-${version}-${platform}-${arch}.${archiveExt}`;
+    return `https://gitlab.com/api/v4/projects/lilypond%2Flilypond/packages/generic/lilypond/${version}/${filename}`;
+}
+async function pathExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * `.zip` archives (Windows/mingw) use PowerShell's `Expand-Archive` rather
+ * than `tar`, since `tar -xf`'s zip support depends on a libarchive/bsdtar
+ * build resolving first on `PATH`, which isn't guaranteed on Windows.
+ */
+async function extractArchive(archivePath, extractDir, archiveExt) {
+    if (archiveExt === "zip") {
+        await execFileAsync("powershell.exe", [
+            "-NoProfile",
+            "-NonInteractive",
+            "-Command",
+            "Expand-Archive -LiteralPath $env:ASTRO_LILYPOND_ARCHIVE -DestinationPath $env:ASTRO_LILYPOND_EXTRACT_DIR -Force",
+        ], {
+            env: {
+                ...process.env,
+                ASTRO_LILYPOND_ARCHIVE: archivePath,
+                ASTRO_LILYPOND_EXTRACT_DIR: extractDir,
+            },
+        });
+        return;
+    }
+    await execFileAsync("tar", ["-xf", archivePath, "-C", extractDir]);
+}
+/**
+ * Downloads, verifies, and extracts a prebuilt LilyPond release into the
+ * cache dir, then returns the path to its `bin/lilypond[.exe]`. Returns
+ * `undefined` when LilyPond publishes no prebuilt for the current
+ * platform/arch. A previously-completed install for the same version is
+ * reused as-is.
+ */
+export async function downloadLilypond({ version, cacheDir = lilypondCacheDir(), fetchImpl = fetch, log = () => { }, }) {
+    const target = resolvePlatformTarget();
+    if (!target)
+        return undefined;
+    const { platform, arch, archiveExt, binaryName } = target;
+    const installDir = join(cacheDir, `lilypond-${version}-${platform}-${arch}`);
+    const markerPath = join(installDir, ".complete");
+    const binaryPath = join(installDir, "bin", binaryName);
+    if (await pathExists(markerPath))
+        return binaryPath;
+    const url = downloadUrlFor(version, platform, arch, archiveExt);
+    log(`astro-lilypond: downloading LilyPond ${version} (${platform}-${arch})…`);
+    const response = await fetchImpl(url);
+    if (!response.ok || !response.body) {
+        throw new Error(`failed to download LilyPond ${version} from ${url} (HTTP ${response.status})`);
+    }
+    const expectedSha256 = response.headers.get("x-checksum-sha256");
+    await mkdir(cacheDir, { recursive: true });
+    const workDir = await mkdtemp(join(cacheDir, ".tmp-"));
+    try {
+        const archivePath = join(workDir, `archive.${archiveExt}`);
+        const hash = createHash("sha256");
+        const chunks = [];
+        for await (const chunk of response.body) {
+            const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            hash.update(buf);
+            chunks.push(buf);
+        }
+        const data = Buffer.concat(chunks);
+        if (expectedSha256) {
+            const actualSha256 = hash.digest("hex");
+            if (actualSha256 !== expectedSha256) {
+                throw new Error(`checksum mismatch downloading LilyPond ${version} from ${url}\n` +
+                    `  expected ${expectedSha256}\n  got      ${actualSha256}`);
+            }
+        }
+        else {
+            log("astro-lilypond: download response had no checksum header — skipping integrity verification");
+        }
+        await writeFile(archivePath, data);
+        const extractDir = join(workDir, "extract");
+        await mkdir(extractDir, { recursive: true });
+        await extractArchive(archivePath, extractDir, archiveExt);
+        // The archive contains a single top-level `lilypond-<version>/` dir.
+        const [extractedRoot] = await readdir(extractDir);
+        if (!extractedRoot) {
+            throw new Error(`downloaded archive for LilyPond ${version} was empty`);
+        }
+        const extractedPath = join(extractDir, extractedRoot);
+        // Writing the marker inside the extracted tree makes the rename below
+        // move the binary and its "installed" marker into place atomically
+        // together, so a process killed mid-install can't leave a good install
+        // looking uninstalled.
+        await writeFile(join(extractedPath, ".complete"), "");
+        const reuseConcurrentInstall = async () => {
+            if (!(await pathExists(markerPath)))
+                return false;
+            log(`astro-lilypond: LilyPond ${version} was installed concurrently by another process; reusing it`);
+            return true;
+        };
+        if (await reuseConcurrentInstall())
+            return binaryPath;
+        try {
+            await rm(installDir, { recursive: true, force: true });
+            await rename(extractedPath, installDir);
+        }
+        catch (err) {
+            if (await reuseConcurrentInstall())
+                return binaryPath;
+            throw err;
+        }
+        log(`astro-lilypond: installed LilyPond ${version} to ${installDir}`);
+        return binaryPath;
+    }
+    finally {
+        await rm(workDir, { recursive: true, force: true });
+    }
+}

package/dist/binary/index.d.ts

@@ -0,0 +1,5 @@
+export { type AutoInstallOptions, resolveAutoInstallOption, } from "./autoInstall.js";
+export { lilypondCacheDir } from "./cacheDir.js";
+export { downloadLilypond } from "./downloadLilypond.js";
+export { resolvePlatformTarget } from "./platformTarget.js";
+export { DEFAULT_LILYPOND_VERSION, resolveLilypondBinary, } from "./resolveLilypondBinary.js";

package/dist/binary/index.js

@@ -0,0 +1,5 @@
+export { resolveAutoInstallOption, } from "./autoInstall.js";
+export { lilypondCacheDir } from "./cacheDir.js";
+export { downloadLilypond } from "./downloadLilypond.js";
+export { resolvePlatformTarget } from "./platformTarget.js";
+export { DEFAULT_LILYPOND_VERSION, resolveLilypondBinary, } from "./resolveLilypondBinary.js";

package/dist/binary/platformTarget.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A platform/arch combination LilyPond publishes a prebuilt archive for,
+ * per https://gitlab.com/lilypond/lilypond/-/releases.
+ */
+export interface PlatformTarget {
+    /** LilyPond's own platform token, as used in its release filenames. */
+    platform: "linux" | "darwin" | "mingw";
+    /** LilyPond's own arch token, as used in its release filenames. */
+    arch: "x86_64" | "arm64";
+    archiveExt: "tar.gz" | "zip";
+    /** Name of the `lilypond` executable inside the archive's `bin/` dir. */
+    binaryName: "lilypond" | "lilypond.exe";
+}
+export declare function resolvePlatformTarget(platform?: NodeJS.Platform, arch?: string): PlatformTarget | undefined;

package/dist/binary/platformTarget.js

@@ -0,0 +1,35 @@
+export function resolvePlatformTarget(platform = process.platform, arch = process.arch) {
+    if (platform === "linux" && arch === "x64") {
+        return {
+            platform: "linux",
+            arch: "x86_64",
+            archiveExt: "tar.gz",
+            binaryName: "lilypond",
+        };
+    }
+    if (platform === "darwin" && arch === "arm64") {
+        return {
+            platform: "darwin",
+            arch: "arm64",
+            archiveExt: "tar.gz",
+            binaryName: "lilypond",
+        };
+    }
+    if (platform === "darwin" && arch === "x64") {
+        return {
+            platform: "darwin",
+            arch: "x86_64",
+            archiveExt: "tar.gz",
+            binaryName: "lilypond",
+        };
+    }
+    if (platform === "win32" && arch === "x64") {
+        return {
+            platform: "mingw",
+            arch: "x86_64",
+            archiveExt: "zip",
+            binaryName: "lilypond.exe",
+        };
+    }
+    return undefined;
+}

package/dist/binary/resolveLilypondBinary.d.ts

@@ -0,0 +1,9 @@
+import type { LilypondVersion } from "../types/lilypondVersion.js";
+export declare const DEFAULT_LILYPOND_VERSION: LilypondVersion;
+export interface ResolveLilypondBinaryOptions {
+    version?: LilypondVersion;
+    autoInstall: boolean;
+    log?: (message: string) => void;
+    warn?: (message: string) => void;
+}
+export declare function resolveLilypondBinary({ version, autoInstall, log, warn, }: ResolveLilypondBinaryOptions): Promise<string>;

package/dist/binary/resolveLilypondBinary.js

@@ -0,0 +1,41 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { downloadLilypond } from "./downloadLilypond.js";
+import { resolvePlatformTarget } from "./platformTarget.js";
+const execFileAsync = promisify(execFile);
+export const DEFAULT_LILYPOND_VERSION = "2.26.0";
+const IS_ON_PATH_TIMEOUT_MS = 10_000;
+async function isOnPath() {
+    try {
+        await execFileAsync("lilypond", ["--version"], {
+            signal: AbortSignal.timeout(IS_ON_PATH_TIMEOUT_MS),
+        });
+        return true;
+    }
+    catch (err) {
+        const code = err?.code;
+        return code !== "ENOENT";
+    }
+}
+export async function resolveLilypondBinary({ version = DEFAULT_LILYPOND_VERSION, autoInstall, log = () => { }, warn = () => { }, }) {
+    if (await isOnPath())
+        return "lilypond";
+    if (!autoInstall) {
+        warn("astro-lilypond: `lilypond` binary not found on PATH — LilyPond blocks will render as errors. " +
+            "Install LilyPond and ensure it is on PATH, or enable the `autoInstall` option (on by default).");
+        return "lilypond";
+    }
+    if (!resolvePlatformTarget()) {
+        warn(`astro-lilypond: \`lilypond\` binary not found on PATH, and no prebuilt LilyPond ${version} ` +
+            `is available for ${process.platform}/${process.arch}. Install LilyPond manually and ensure it is on PATH.`);
+        return "lilypond";
+    }
+    try {
+        const binaryPath = await downloadLilypond({ version, log });
+        return binaryPath ?? "lilypond";
+    }
+    catch (err) {
+        throw new Error(`astro-lilypond: automatic LilyPond install failed — ${err instanceof Error ? err.message : String(err)}. ` +
+            "Install LilyPond manually and ensure it is on PATH, or set `autoInstall: false` to require a PATH install without attempting a download.", { cause: err });
+    }
+}

package/dist/index.d.ts

@@ -1,33 +1,85 @@
 import type { AstroIntegration } from "astro";
+import { type AstroComponentFactory } from "astro/runtime/server/index.js";
+import type { AutoInstallOptions } from "./binary/index.js";
 import { type PluginOptions } from "./plugins/index.js";
 import { type LilypondDefaults } from "./render.js";
+import { type LilypondMetadata } from "./utils/index.js";
 export declare const LY_EXTENSIONS: readonly [".ly", ".lilypond", ".ily"];
-export type { LilypondDefaults, PluginOptions as LilypondPluginOptions };
+export type { AstroComponentFactory, AutoInstallOptions, LilypondDefaults, LilypondMetadata, PluginOptions as LilypondPluginOptions, };
 export interface LilypondPage {
     src: string;
     width?: number;
     height?: number;
 }
-export interface LilypondContent {
+/**
+ * The result of a `.ly`/`.ily`/`.lilypond` import
+ * or `lilypondLoader()` collection entry.
+ */
+export interface LilypondScore {
+    source: string;
+    alt: string;
+    sourceName: string | undefined;
+    includePaths: string[];
+    assetTitle: string;
+    meta: LilypondMetadata;
+}
+export interface RenderOptions {
+    /**
+     * Output format for `Score`.
+     * @default "svg"
+     */
+    format?: "svg" | "png";
+    /**
+     * Crop `Score` to a single tightly-fit image instead of full pages.
+     * @default resolved from the integration's `defaults.crop`
+     */
+    crop?: boolean;
+    /**
+     * Render a downloadable PDF of the same score, returned as `pdf`.
+     * @default false
+     */
+    pdf?: boolean;
+}
+export interface LilypondImageResult {
     pages: LilypondPage[];
     alt?: string;
 }
+export interface LilypondPdfResult {
+    src: string;
+}
+export interface RenderResult {
+    Score: AstroComponentFactory;
+    pageCount: number;
+    pdf?: LilypondPdfResult;
+    meta: LilypondMetadata;
+    raw: string;
+}
+/**
+ * Renders a `LilypondScore` (from a `.ly`/`.ily`/`.lilypond` import,
+ * or a `lilypondLoader()` entry) to a renderable `<Score />` component.
+ */
+export declare function render(score: LilypondScore, options?: RenderOptions): Promise<RenderResult>;
+export declare function renderAll(scores: LilypondScore[], options?: RenderOptions): Promise<RenderResult[]>;
 export interface LilypondOptions extends PluginOptions {
     /**
-     * Output format.
+     * Output format used by Markdown fences and `lilypondLoader()` entries.
      * @default "svg"
      */
     format?: "svg" | "png";
     /**
-     * Defaults passed to each score.
-     * Defaults can still be overridden by individual `.ly` files.
+     * Defaults passed to each score; can be overridden at render time.
      */
     defaults?: LilypondDefaults;
     /**
-     * Milliseconds to wait for a single `lilypond` invocation before
-     * aborting it.
+     * Ms to wait for a single `lilypond` invocation before aborting.
      * @default 60000
      */
     timeout?: number;
+    /**
+     * When no `lilypond` binary is found on `PATH`, download a matching
+     * prebuilt release into a local cache and use that instead.
+     * @default true
+     */
+    autoInstall?: boolean | AutoInstallOptions;
 }
 export default function lilypond(options?: LilypondOptions): AstroIntegration;

package/dist/index.js

@@ -1,52 +1,101 @@
-import { execFile } from "node:child_process";
-import { promisify } from "node:util";
+import { createComponent, renderTemplate, unescapeHTML, } from "astro/runtime/server/index.js";
 import emitAssetIntegration from "astro-emit-asset";
 import { rehypePlugin, remarkPlugin, satteriPlugin, } from "./plugins/index.js";
-import { defaultOptions, render, resolveCrop, } from "./render.js";
-import { altTextFor, emitLilypondAsset, includePathsFor, lyTypeDeclarationsFor, parseLyHeader, parseLyImportQuery, prependVersion, RECOGNIZED_QUERY_PARAMS, resolveDefaults, sourceNameFor, titleFor, } from "./utils/index.js";
-const execFileAsync = promisify(execFile);
+import { render as renderScore, resolveCrop, } from "./render.js";
+import { getRenderState, resolveAndSetRenderState } from "./renderState.js";
+import { altTextFor, emitLilypondAsset, emitLilypondPdfAsset, includePathsFor, lyTypeDeclarationsFor, parseLyHeaderFields, prependVersion, renderedHtml, resolveDefaults, sourceNameFor, titleFor, toLilypondMetadata, } from "./utils/index.js";
 export const LY_EXTENSIONS = [".ly", ".lilypond", ".ily"];
-function lyFilePlugin(options) {
-    return {
-        name: "vite-plugin-astro-lilypond-ly",
-        enforce: "pre",
-        async transform(source, id) {
-            const query = parseLyImportQuery(id);
-            if (!query)
-                return;
-            const { pathname, cropOverride } = query;
-            if (!LY_EXTENSIONS.some((ext) => pathname.endsWith(ext)))
-                return;
-            const { version, resolution, crop: cropSetting, cropScale, } = resolveDefaults(options.defaults);
-            const crop = cropOverride ?? resolveCrop(cropSetting, "component");
-            const src = version ? prependVersion(source, version) : source;
-            const format = options.format ?? defaultOptions.format;
-            const includePaths = includePathsFor(pathname);
-            const sourceName = sourceNameFor(pathname);
-            const title = titleFor(sourceName);
-            const alt = altTextFor(parseLyHeader(source));
+function createScoreComponent(content) {
+    return createComponent((_result, props) => {
+        const alt = props.alt ?? content.alt ?? "";
+        const html = renderedHtml(content.pages, alt, {
+            class: props.class,
+            style: props.style,
+            pageLimit: props.pageLimit,
+        });
+        return renderTemplate `${unescapeHTML(html)}`;
+    });
+}
+/**
+ * Renders a `LilypondScore` (from a `.ly`/`.ily`/`.lilypond` import,
+ * or a `lilypondLoader()` entry) to a renderable `<Score />` component.
+ */
+export async function render(score, options = {}) {
+    const state = getRenderState();
+    const { resolution, crop: cropSetting, cropScale, } = resolveDefaults(state.defaults);
+    const format = options.format ?? "svg";
+    const crop = options.crop ?? resolveCrop(cropSetting, "component");
+    const [{ Score, pageCount }, pdf] = await Promise.all([
+        (async () => {
             const pages = await emitLilypondAsset({
-                title,
+                title: score.assetTitle,
                 format,
-                source: src,
+                source: score.source,
                 resolution,
                 crop,
                 sizeScale: crop ? cropScale : 1,
-                render: () => render(src, {
+                binaryPath: state.binaryPath,
+                render: () => renderScore(score.source, {
                     format,
                     crop,
-                    defaults: options.defaults,
-                    timeout: options.timeout,
-                    includePaths,
-                    sourceName,
+                    defaults: state.defaults,
+                    timeout: state.timeout,
+                    binaryPath: state.binaryPath,
+                    includePaths: score.includePaths,
+                    sourceName: score.sourceName,
                 }),
             });
-            const content = {
-                pages,
+            return {
+                Score: createScoreComponent({ pages, alt: score.alt }),
+                pageCount: pages.length,
+            };
+        })(),
+        options.pdf
+            ? emitLilypondPdfAsset({
+                title: score.assetTitle,
+                source: score.source,
+                binaryPath: state.binaryPath,
+                render: () => renderScore(score.source, {
+                    format: "pdf",
+                    crop: false,
+                    defaults: state.defaults,
+                    timeout: state.timeout,
+                    binaryPath: state.binaryPath,
+                    includePaths: score.includePaths,
+                    sourceName: score.sourceName,
+                }),
+            })
+            : Promise.resolve(undefined),
+    ]);
+    return { Score, pageCount, pdf, meta: score.meta, raw: score.source };
+}
+export async function renderAll(scores, options = {}) {
+    return Promise.all(scores.map((score) => render(score, options)));
+}
+function lyFilePlugin(options) {
+    return {
+        name: "vite-plugin-astro-lilypond-ly",
+        enforce: "pre",
+        async transform(source, id) {
+            if (!LY_EXTENSIONS.some((ext) => id.endsWith(ext)))
+                return;
+            const { version } = resolveDefaults(options.defaults);
+            const src = version ? prependVersion(source, version) : source;
+            const includePaths = includePathsFor(id);
+            const sourceName = sourceNameFor(id);
+            const assetTitle = titleFor(sourceName);
+            const meta = toLilypondMetadata(parseLyHeaderFields(source));
+            const alt = altTextFor(meta);
+            const score = {
+                source: src,
                 alt,
+                sourceName,
+                includePaths,
+                assetTitle,
+                meta,
             };
             return {
-                code: `export default ${JSON.stringify(content)}`,
+                code: `export default ${JSON.stringify(score)}`,
             };
         },
     };
@@ -56,10 +105,11 @@ export default function lilypond(options = {}) {
         name: "astro-lilypond",
         hooks: {
             "astro:config:setup": async ({ config, updateConfig, logger }) => {
-                await execFileAsync("lilypond", ["--version"]).catch((err) => {
-                    if (err.code === "ENOENT") {
-                        logger?.warn("astro-lilypond: `lilypond` binary not found — LilyPond blocks will render as errors. Install LilyPond and ensure it is on PATH.");
-                    }
+                options.binaryPath = await resolveAndSetRenderState({
+                    autoInstall: options.autoInstall,
+                    defaults: options.defaults,
+                    timeout: options.timeout,
+                    logger,
                 });
                 updateConfig({
                     integrations: [emitAssetIntegration()],
@@ -120,7 +170,7 @@ export default function lilypond(options = {}) {
             "astro:config:done": ({ injectTypes }) => {
                 injectTypes({
                     filename: "ly-types.d.ts",
-                    content: lyTypeDeclarationsFor(LY_EXTENSIONS, RECOGNIZED_QUERY_PARAMS),
+                    content: lyTypeDeclarationsFor(LY_EXTENSIONS),
                 });
             },
         },