astro-lilypond 0.12.0 → 0.14.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,8 +1,9 @@
 import type { AstroIntegration } from "astro";
+import { type AutoInstallOptions } from "./binary/index.js";
 import { type PluginOptions } from "./plugins/index.js";
 import { type LilypondDefaults } from "./render.js";
 export declare const LY_EXTENSIONS: readonly [".ly", ".lilypond", ".ily"];
-export type { LilypondDefaults, PluginOptions as LilypondPluginOptions };
+export type { AutoInstallOptions, LilypondDefaults, PluginOptions as LilypondPluginOptions, };
 export interface LilypondPage {
     src: string;
     width?: number;
@@ -14,7 +15,7 @@ export interface LilypondContent {
 }
 export interface LilypondOptions extends PluginOptions {
     /**
-     * Output format to be written to a file under `outputDir`.
+     * Output format.
      * @default "svg"
      */
     format?: "svg" | "png";
@@ -30,14 +31,12 @@ export interface LilypondOptions extends PluginOptions {
      */
     timeout?: number;
     /**
-     * Directory name, relative to Astro's `publicDir`, that rendered assets
-     * are written into by both `astro dev` and `astro build`. Filenames are
-     * content-addressed, so unchanged scores are reused instead of being
-     * re-rendered, and it's safe to commit this directory if you'd like
-     * faster rebuilds.
-     *
-     * @default "_lilypond"
+     * When no `lilypond` binary is found on `PATH`, download a matching
+     * prebuilt release into a local cache and use that instead. Set to
+     * `false` to only ever use a `PATH` install, or pass an object to pick
+     * which version gets downloaded.
+     * @default true
      */
-    outputDir?: string;
+    autoInstall?: boolean | AutoInstallOptions;
 }
 export default function lilypond(options?: LilypondOptions): AstroIntegration;

package/dist/index.js

@@ -1,13 +1,8 @@
-import { execFile } from "node:child_process";
-import { join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { promisify } from "node:util";
-import { pruneOrphanedAssets, pruneStaleAssets } from "./deleteAssets.js";
+import emitAssetIntegration from "astro-emit-asset";
+import { resolveAutoInstallOption, resolveLilypondBinary, } from "./binary/index.js";
 import { rehypePlugin, remarkPlugin, satteriPlugin, } from "./plugins/index.js";
 import { defaultOptions, render, resolveCrop, } from "./render.js";
-import { altTextFor, assetsUrlBaseFor, contentHashFor, includePathsFor, lyTypeDeclarationsFor, parseLyHeader, parseLyImportQuery, prependVersion, RECOGNIZED_QUERY_PARAMS, resolveDefaults, sourceNameFor, titleFor, } from "./utils/index.js";
-import { writeAssets } from "./writeAsset.js";
-const execFileAsync = promisify(execFile);
+import { altTextFor, emitLilypondAsset, includePathsFor, lyTypeDeclarationsFor, parseLyHeader, parseLyImportQuery, prependVersion, RECOGNIZED_QUERY_PARAMS, resolveDefaults, sourceNameFor, titleFor, } from "./utils/index.js";
 export const LY_EXTENSIONS = [".ly", ".lilypond", ".ily"];
 function lyFilePlugin(options) {
     return {
@@ -27,34 +22,27 @@ function lyFilePlugin(options) {
             const includePaths = includePathsFor(pathname);
             const sourceName = sourceNameFor(pathname);
             const title = titleFor(sourceName);
-            const hash = contentHashFor({ source: src, format, resolution, crop });
             const alt = altTextFor(parseLyHeader(source));
-            const assets = await writeAssets({
-                hash,
+            const pages = await emitLilypondAsset({
                 title,
                 format,
-                outputDir: options.assetsDir,
-                urlBase: options.assetsUrlBase,
+                source: src,
+                resolution,
+                crop,
                 sizeScale: crop ? cropScale : 1,
-                trackAsset: options.trackAsset,
-                getBuffers: () => render(src, {
+                binaryPath: options.binaryPath,
+                render: () => render(src, {
                     format,
                     crop,
                     defaults: options.defaults,
                     timeout: options.timeout,
+                    binaryPath: options.binaryPath,
                     includePaths,
                     sourceName,
                 }),
             });
-            // Keyed by the full id (including query) so `./score.ly` and
-            // `./score.ly?crop` are tracked as independent sources.
-            await options.pruneStaleAssets(id, assets.map((asset) => asset.fileName));
             const content = {
-                pages: assets.map((asset) => ({
-                    src: asset.url,
-                    width: asset.width,
-                    height: asset.height,
-                })),
+                pages,
                 alt,
             };
             return {
@@ -64,37 +52,18 @@ function lyFilePlugin(options) {
     };
 }
 export default function lilypond(options = {}) {
-    const referencedAssets = new Set();
-    const assetsBySource = new Map();
-    let assetsDir;
     return {
         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 resolveLilypondBinary({
+                    ...resolveAutoInstallOption(options.autoInstall),
+                    log: (message) => logger?.info(message),
+                    warn: (message) => logger?.warn(message),
                 });
-                const outputDirName = options.outputDir ?? "_lilypond";
-                const assetsUrlBase = assetsUrlBaseFor(config.base, outputDirName);
-                const resolvedAssetsDir = join(fileURLToPath(config.publicDir), outputDirName);
-                assetsDir = resolvedAssetsDir;
-                const resolvedOptions = {
-                    ...options,
-                    assetsDir,
-                    assetsUrlBase,
-                    trackAsset: (fileName) => referencedAssets.add(fileName),
-                    pruneStaleAssets: (sourceKey, fileNames) => pruneStaleAssets({
-                        assetsBySource,
-                        sourceKey,
-                        fileNames,
-                        outputDir: resolvedAssetsDir,
-                        logger,
-                    }),
-                };
                 updateConfig({
-                    vite: { plugins: [lyFilePlugin(resolvedOptions)] },
+                    integrations: [emitAssetIntegration()],
+                    vite: { plugins: [lyFilePlugin(options)] },
                 });
                 const existingProcessor = config.markdown?.processor;
                 if (existingProcessor?.name === "satteri") {
@@ -110,7 +79,7 @@ export default function lilypond(options = {}) {
                                 ...existingOptions,
                                 mdastPlugins: [
                                     ...(existingOptions.mdastPlugins ?? []),
-                                    satteriPlugin(resolvedOptions),
+                                    satteriPlugin(options),
                                 ],
                             }),
                         },
@@ -131,11 +100,11 @@ export default function lilypond(options = {}) {
                                 ...existingOptions,
                                 remarkPlugins: [
                                     ...(existingOptions.remarkPlugins ?? []),
-                                    [remarkPlugin, resolvedOptions],
+                                    [remarkPlugin, options],
                                 ],
                                 rehypePlugins: [
                                     ...(existingOptions.rehypePlugins ?? []),
-                                    [rehypePlugin, resolvedOptions],
+                                    [rehypePlugin, options],
                                 ],
                             }),
                         },
@@ -154,15 +123,6 @@ export default function lilypond(options = {}) {
                     content: lyTypeDeclarationsFor(LY_EXTENSIONS, RECOGNIZED_QUERY_PARAMS),
                 });
             },
-            "astro:build:done": async ({ logger }) => {
-                if (!assetsDir)
-                    return;
-                await pruneOrphanedAssets({
-                    dir: assetsDir,
-                    referenced: referencedAssets,
-                    logger,
-                });
-            },
         },
     };
 }

package/dist/loader.d.ts

@@ -1,5 +1,6 @@
 import type { Loader } from "astro/loaders";
 import { z } from "astro/zod";
+import { type AutoInstallOptions } from "./binary/index.js";
 import { type LilypondContent } from "./index.js";
 import type { PluginOptions } from "./plugins/index.js";
 import { type KnownLyHeaderFields } from "./utils/index.js";
@@ -28,14 +29,13 @@ export interface LilypondLoaderOptions extends PluginOptions {
      */
     generateId?: (options: GenerateIdOptions) => string;
     /**
-     * Directory name, relative to Astro's `publicDir`, that rendered assets
-     * are written into. Exclusive to this collection — the loader prunes
-     * anything under it that isn't currently referenced by one of its own
-     * entries, so don't point two different collections (or the `lilypond()`
-     * integration's own `outputDir`) at the same directory.
-     * @default `"_lilypond/<collection name>"`
+     * When no `lilypond` binary is found on `PATH`, download a matching
+     * prebuilt release into a local cache and use that instead. Set to
+     * `false` to only ever use a `PATH` install, or pass an object to pick
+     * which version gets downloaded.
+     * @default true
      */
-    outputDir?: string;
+    autoInstall?: boolean | AutoInstallOptions;
 }
 export interface LilypondHeaderData extends KnownLyHeaderFields {
     /** Header fields outside LilyPond's standard set (e.g. `mutopiacomposer`). */