@poe-platform/safe-bash 0.1.782 → 0.1.783

package/dist/safe-bash/lazy-optional.js

@@ -0,0 +1,609 @@
+import { createGhCommands, ghMetadata } from "./lazy-gh.js";
+import { validatePandocOptions } from "../safe-bash-command-pandoc/options.js";
+import { createLazyCommandLoader, createLazyCommands, lazyCommandPlugin } from "./plugins/lazy-command.js";
+import { CommandRegistry } from "./contracts/command.js";
+const loadffmpeg = createLazyCommandLoader(() => import("./commands/ffmpeg/index.js"));
+const ffmpegMetadata = [
+    {
+        name: "ffmpeg",
+        description: "Multimedia converter, merger, and stream processor powered by pluggable ASTs"
+    },
+    {
+        name: "ffprobe",
+        description: "Multimedia stream analyzer powered by pluggable ASTs"
+    }
+];
+export const createFfmpegCommand = (...args) => {
+    const metadata = ffmpegMetadata.find((item) => item.name === "ffmpeg");
+    if (!metadata)
+        throw new TypeError("Unknown ffmpeg command");
+    return createLazyCommands([metadata], async () => {
+        const module = await loadffmpeg();
+        return () => [module.createFfmpegCommand(...args)];
+    })[0];
+};
+export const createFfprobeCommand = (...args) => {
+    const metadata = ffmpegMetadata.find((item) => item.name === "ffprobe");
+    if (!metadata)
+        throw new TypeError("Unknown ffmpeg command");
+    return createLazyCommands([metadata], async () => {
+        const module = await loadffmpeg();
+        return () => [module.createFfprobeCommand(...args)];
+    })[0];
+};
+export const createFfmpegCommands = (...args) => {
+    const definitions = createLazyCommands(ffmpegMetadata, async () => {
+        const module = await loadffmpeg();
+        return () => module.createFfmpegCommands(...args);
+    });
+    return Object.freeze(Object.assign([definitions[0], definitions[1]], {
+        ffmpeg: definitions[0],
+        ffprobe: definitions[1]
+    }));
+};
+export const ffmpegCommands = (options = {}) => lazyCommandPlugin("ffmpeg-commands", createFfmpegCommands(options), options.replace ?? false);
+const loadgit = createLazyCommandLoader(() => import("./commands/git/index.js"));
+const gitMetadata = [
+    {
+        name: "git",
+        description: "Git repositories in the virtual filesystem"
+    }
+];
+export const gitCommands = (options = {}) => lazyCommandPlugin("git-commands", createGitCommands(options), options.replace ?? false);
+export const createGitCommands = (...args) => {
+    const definitions = createLazyCommands(gitMetadata, async () => {
+        const module = await loadgit();
+        return () => module.createGitCommands(...args);
+    });
+    return definitions;
+};
+export const createGitCommand = (...args) => {
+    const metadata = gitMetadata.find((item) => item.name === "git");
+    if (!metadata)
+        throw new TypeError("Unknown git command");
+    return createLazyCommands([metadata], async () => {
+        const module = await loadgit();
+        return () => [module.createGitCommand(...args)];
+    })[0];
+};
+const loadsoffice = createLazyCommandLoader(() => import("./commands/soffice/index.js"));
+const sofficeMetadata = [
+    {
+        name: "soffice",
+        description: "Headless document/spreadsheet/presentation to PDF and CSV converter via @poe-code/pdf-ast"
+    },
+    {
+        name: "libreoffice",
+        description: "Headless LibreOffice document/spreadsheet/presentation to PDF converter via @poe-code/pdf-ast"
+    }
+];
+export const createSofficeCommand = (...args) => {
+    const metadata = sofficeMetadata.find((item) => item.name === "soffice");
+    if (!metadata)
+        throw new TypeError("Unknown soffice command");
+    return createLazyCommands([metadata], async () => {
+        const module = await loadsoffice();
+        return () => [module.createSofficeCommand(...args)];
+    })[0];
+};
+export const sofficeCommands = (options = {}) => lazyCommandPlugin("soffice", createSofficeCommands(options), options.replace ?? false);
+export const createSofficeCommands = (...args) => {
+    const definitions = createLazyCommands(sofficeMetadata, async () => {
+        const module = await loadsoffice();
+        return () => module.createSofficeCommands(...args);
+    });
+    return definitions;
+};
+const loadpandoc = createLazyCommandLoader(() => import("./commands/pandoc/implementation.js"));
+const pandocMetadata = [
+    {
+        name: "pandoc",
+        description: "Convert documents with the original bounded TypeScript SDK"
+    }
+];
+export const pandocCommands = (options = {}) => {
+    let hasCommand;
+    const command = createPandocCommand(options, (name) => hasCommand?.(name) ?? false);
+    return {
+        name: "pandoc",
+        setup(host) {
+            hasCommand = (name) => host.commands.has(name);
+            host.commands.register(command, { replace: options.replace ?? false });
+        }
+    };
+};
+export const createPandocCommands = (...args) => {
+    validatePandocOptions(args[0] === undefined ? {} : args[0]);
+    const definitions = createLazyCommands(pandocMetadata, async () => {
+        const module = await loadpandoc();
+        return () => module.createPandocCommands(...args);
+    });
+    return definitions;
+};
+export const createPandocCommand = (...args) => {
+    validatePandocOptions(args[0] === undefined ? {} : args[0]);
+    const metadata = pandocMetadata.find((item) => item.name === "pandoc");
+    if (!metadata)
+        throw new TypeError("Unknown pandoc command");
+    return createLazyCommands([metadata], async () => {
+        const module = await loadpandoc();
+        return () => [module.createPandocCommand(...args)];
+    })[0];
+};
+const loadssconvert = createLazyCommandLoader(() => import("../safe-bash-command-ssconvert/index.js"));
+const loadSelectedSsconvert = createLazyCommandLoader(() => import("../safe-bash-command-ssconvert/commands.js"));
+const ssconvertMetadata = [
+    {
+        name: "ssconvert",
+        description: "Explicitly bound TypeScript spreadsheet conversion engine"
+    }
+];
+export const createSsconvertCommand = (...args) => {
+    const metadata = ssconvertMetadata.find((item) => item.name === "ssconvert");
+    if (!metadata)
+        throw new TypeError("Unknown ssconvert command");
+    return createLazyCommands([metadata], async () => {
+        const module = await (args[0]?.formats === undefined
+            ? loadssconvert()
+            : loadSelectedSsconvert());
+        return () => [module.createSsconvertCommand(...args)];
+    })[0];
+};
+export const ssconvertCommands = (options = {}) => lazyCommandPlugin("ssconvert-commands", createSsconvertCommands(options), options.replace ?? false);
+export const createSsconvertCommands = (...args) => {
+    const definitions = createLazyCommands(ssconvertMetadata, async () => {
+        const module = await (args[0]?.formats === undefined
+            ? loadssconvert()
+            : loadSelectedSsconvert());
+        return () => module.createSsconvertCommands(...args);
+    });
+    return definitions;
+};
+const loadpdfinfo = createLazyCommandLoader(() => import("./commands/pdfinfo/index.js"));
+const pdfinfoMetadata = [
+    {
+        name: "pdfinfo",
+        description: "Extract PDF metadata, page boxes, encryption, and structure via @poe-code/pdf-ast"
+    },
+    {
+        name: "pdfunite",
+        description: "Merge multiple PDF documents into a single PDF via @poe-code/pdf-ast"
+    },
+    {
+        name: "pdfseparate",
+        description: "Split PDF pages into individual PDF files via @poe-code/pdf-ast"
+    },
+    {
+        name: "pdffonts",
+        description: "List fonts used in a PDF document via @poe-code/pdf-ast"
+    },
+    {
+        name: "pdfdetach",
+        description: "List and extract embedded file attachments from PDF documents via @poe-code/pdf-ast"
+    }
+];
+export const createPdfinfoCommand = (...args) => {
+    const metadata = pdfinfoMetadata.find((item) => item.name === "pdfinfo");
+    if (!metadata)
+        throw new TypeError("Unknown pdfinfo command");
+    return createLazyCommands([metadata], async () => {
+        const module = await loadpdfinfo();
+        return () => [module.createPdfinfoCommand(...args)];
+    })[0];
+};
+export const pdfinfoCommands = (options = {}) => lazyCommandPlugin("pdfinfo", createPdfinfoCommands(options), options.replace ?? false);
+export const createPdfinfoCommands = (...args) => {
+    const definitions = createLazyCommands(pdfinfoMetadata, async () => {
+        const module = await loadpdfinfo();
+        return () => module.createPdfinfoCommands(...args);
+    });
+    return definitions;
+};
+const loadpdftotext = createLazyCommandLoader(() => import("./commands/pdftotext/index.js"));
+const pdftotextMetadata = [
+    {
+        name: "pdftotext",
+        description: "Extract PDF text, layout, XHTML bounding boxes, and TSV via @poe-code/pdf-ast"
+    },
+    {
+        name: "pdftohtml",
+        description: "Convert PDF pages into HTML or XML layout documents via @poe-code/pdf-ast"
+    }
+];
+export const createPdftotextCommand = (...args) => {
+    const metadata = pdftotextMetadata.find((item) => item.name === "pdftotext");
+    if (!metadata)
+        throw new TypeError("Unknown pdftotext command");
+    return createLazyCommands([metadata], async () => {
+        const module = await loadpdftotext();
+        return () => [module.createPdftotextCommand(...args)];
+    })[0];
+};
+export const pdftotextCommands = (options = {}) => lazyCommandPlugin("pdftotext", createPdftotextCommands(options), options.replace ?? false);
+export const createPdftotextCommands = (...args) => {
+    const definitions = createLazyCommands(pdftotextMetadata, async () => {
+        const module = await loadpdftotext();
+        return () => module.createPdftotextCommands(...args);
+    });
+    return definitions;
+};
+const loadpdfimages = createLazyCommandLoader(() => import("./commands/pdfimages/index.js"));
+const pdfimagesMetadata = [
+    {
+        name: "pdfimages",
+        description: "List and extract embedded images from PDF pages via @poe-code/pdf-ast"
+    }
+];
+export const createPdfimagesCommand = (...args) => {
+    const metadata = pdfimagesMetadata.find((item) => item.name === "pdfimages");
+    if (!metadata)
+        throw new TypeError("Unknown pdfimages command");
+    return createLazyCommands([metadata], async () => {
+        const module = await loadpdfimages();
+        return () => [module.createPdfimagesCommand(...args)];
+    })[0];
+};
+export const pdfimagesCommands = (options = {}) => lazyCommandPlugin("pdfimages", createPdfimagesCommands(options), options.replace ?? false);
+export const createPdfimagesCommands = (...args) => {
+    const definitions = createLazyCommands(pdfimagesMetadata, async () => {
+        const module = await loadpdfimages();
+        return () => module.createPdfimagesCommands(...args);
+    });
+    return definitions;
+};
+const loadpdftoppm = createLazyCommandLoader(() => import("./commands/pdftoppm/index.js"));
+const pdftoppmMetadata = [
+    {
+        name: "pdftoppm",
+        description: "Render PDF pages to PNG, PPM, PGM, PBM, or SVG via @poe-code/pdf-ast"
+    },
+    {
+        name: "pdftocairo",
+        description: "Render PDF pages to PNG, JPEG, TIFF, PDF, PS, EPS, or SVG via @poe-code/pdf-ast"
+    }
+];
+export const createPdftoppmCommand = (...args) => {
+    const metadata = pdftoppmMetadata.find((item) => item.name === "pdftoppm");
+    if (!metadata)
+        throw new TypeError("Unknown pdftoppm command");
+    return createLazyCommands([metadata], async () => {
+        const module = await loadpdftoppm();
+        return () => [module.createPdftoppmCommand(...args)];
+    })[0];
+};
+export const pdftoppmCommands = (options = {}) => lazyCommandPlugin("pdftoppm", createPdftoppmCommands(options), options.replace ?? false);
+export const createPdftoppmCommands = (...args) => {
+    const definitions = createLazyCommands(pdftoppmMetadata, async () => {
+        const module = await loadpdftoppm();
+        return () => module.createPdftoppmCommands(...args);
+    });
+    return definitions;
+};
+const loadpdftk = createLazyCommandLoader(() => import("./commands/pdftk/index.js"));
+const pdftkMetadata = [
+    {
+        name: "pdftk",
+        description: "Manipulate PDF documents, fill/flatten AcroForms, and assemble pages via @poe-code/pdf-ast"
+    }
+];
+export const createPdftkCommand = (...args) => {
+    const metadata = pdftkMetadata.find((item) => item.name === "pdftk");
+    if (!metadata)
+        throw new TypeError("Unknown pdftk command");
+    return createLazyCommands([metadata], async () => {
+        const module = await loadpdftk();
+        return () => [module.createPdftkCommand(...args)];
+    })[0];
+};
+export const pdftkCommands = (options = {}) => lazyCommandPlugin("pdftk", createPdftkCommands(options), options.replace ?? false);
+export const createPdftkCommands = (...args) => {
+    const definitions = createLazyCommands(pdftkMetadata, async () => {
+        const module = await loadpdftk();
+        return () => module.createPdftkCommands(...args);
+    });
+    return definitions;
+};
+const loadqpdf = createLazyCommandLoader(() => import("./commands/qpdf/index.js"));
+const qpdfMetadata = [
+    {
+        name: "qpdf",
+        description: "Structural PDF inspection, encryption, page selection, and transformation via @poe-code/pdf-ast"
+    }
+];
+export const createQpdfCommand = (...args) => {
+    const metadata = qpdfMetadata.find((item) => item.name === "qpdf");
+    if (!metadata)
+        throw new TypeError("Unknown qpdf command");
+    return createLazyCommands([metadata], async () => {
+        const module = await loadqpdf();
+        return () => [module.createQpdfCommand(...args)];
+    })[0];
+};
+export const qpdfCommands = (options = {}) => lazyCommandPlugin("qpdf", createQpdfCommands(options), options.replace ?? false);
+export const createQpdfCommands = (...args) => {
+    const definitions = createLazyCommands(qpdfMetadata, async () => {
+        const module = await loadqpdf();
+        return () => module.createQpdfCommands(...args);
+    });
+    return definitions;
+};
+const loadsips = createLazyCommandLoader(() => import("./commands/sips/index.js"));
+const sipsMetadata = [
+    {
+        name: "sips",
+        description: "Scriptable image processing system powered by @poe-code/image-ast"
+    }
+];
+export const createSipsCommand = (...args) => {
+    const metadata = sipsMetadata.find((item) => item.name === "sips");
+    if (!metadata)
+        throw new TypeError("Unknown sips command");
+    return createLazyCommands([metadata], async () => {
+        const module = await loadsips();
+        return () => [module.createSipsCommand(...args)];
+    })[0];
+};
+export const sipsCommands = (options = {}) => lazyCommandPlugin("sips", createSipsCommands(options), options.replace ?? false);
+export const createSipsCommands = (...args) => {
+    const definitions = createLazyCommands(sipsMetadata, async () => {
+        const module = await loadsips();
+        return () => module.createSipsCommands(...args);
+    });
+    return definitions;
+};
+const loadimagemagick = createLazyCommandLoader(() => import("./commands/imagemagick/index.js"));
+const imagemagickMetadata = [
+    {
+        name: "magick",
+        description: "ImageMagick v7 image processor powered by @poe-code/image-ast"
+    },
+    {
+        name: "convert",
+        description: "ImageMagick convert pipeline powered by @poe-code/image-ast"
+    },
+    {
+        name: "mogrify",
+        description: "ImageMagick in-place batch image processor powered by @poe-code/image-ast"
+    },
+    {
+        name: "composite",
+        description: "ImageMagick overlay composition tool powered by @poe-code/image-ast"
+    },
+    {
+        name: "montage",
+        description: "ImageMagick contact-sheet grid generator powered by @poe-code/image-ast"
+    },
+    {
+        name: "identify",
+        description: "ImageMagick image metadata inspector powered by @poe-code/image-ast"
+    },
+    {
+        name: "compare",
+        description: "ImageMagick image comparison and diff generator powered by @poe-code/image-ast"
+    }
+];
+export const createMagickCommand = (...args) => {
+    const metadata = imagemagickMetadata.find((item) => item.name === "magick");
+    if (!metadata)
+        throw new TypeError("Unknown imagemagick command");
+    return createLazyCommands([metadata], async () => {
+        const module = await loadimagemagick();
+        return () => [module.createMagickCommand(...args)];
+    })[0];
+};
+export const imagemagickCommands = (options = {}) => lazyCommandPlugin("imagemagick", createImagemagickCommands(options), options.replace ?? false);
+export const createImagemagickCommands = (...args) => {
+    const definitions = createLazyCommands(imagemagickMetadata, async () => {
+        const module = await loadimagemagick();
+        return () => module.createImagemagickCommands(...args);
+    });
+    return definitions;
+};
+export const createImagemagickCommand = (...args) => {
+    const metadata = imagemagickMetadata.find((item) => item.name === "magick");
+    if (!metadata)
+        throw new TypeError("Unknown imagemagick command");
+    return createLazyCommands([metadata], async () => {
+        const module = await loadimagemagick();
+        return () => [module.createImagemagickCommand(...args)];
+    })[0];
+};
+const loadwkhtmltopdf = createLazyCommandLoader(() => import("./commands/wkhtmltopdf/index.js"));
+const wkhtmltopdfMetadata = [
+    {
+        name: "wkhtmltopdf",
+        description: "Bounded static HTML-to-PDF adapter with a built-in PDF AST renderer"
+    }
+];
+export const createWkhtmltopdfCommand = (...args) => {
+    const metadata = wkhtmltopdfMetadata.find((item) => item.name === "wkhtmltopdf");
+    if (!metadata)
+        throw new TypeError("Unknown wkhtmltopdf command");
+    return createLazyCommands([metadata], async () => {
+        const module = await loadwkhtmltopdf();
+        return () => [module.createWkhtmltopdfCommand(...args)];
+    })[0];
+};
+export const wkhtmltopdfCommands = (options = {}) => lazyCommandPlugin("wkhtmltopdf", createWkhtmltopdfCommands(options), options.replace ?? false);
+export const createWkhtmltopdfCommands = (...args) => {
+    const definitions = createLazyCommands(wkhtmltopdfMetadata, async () => {
+        const module = await loadwkhtmltopdf();
+        return () => module.createWkhtmltopdfCommands(...args);
+    });
+    return definitions;
+};
+const loadcsvkit = createLazyCommandLoader(() => import("./commands/csvkit/index.js"));
+const csvkitMetadata = [
+    {
+        name: "csvclean",
+        description: "csvkit 2.2.0 csvclean; compatibility gaps return status 78"
+    },
+    {
+        name: "csvcut",
+        description: "csvkit 2.2.0 csvcut; compatibility gaps return status 78",
+        fallback: true
+    },
+    {
+        name: "csvformat",
+        description: "csvkit 2.2.0 csvformat; compatibility gaps return status 78"
+    },
+    {
+        name: "csvgrep",
+        description: "csvkit 2.2.0 csvgrep; compatibility gaps return status 78",
+        fallback: true
+    },
+    {
+        name: "csvjoin",
+        description: "csvkit 2.2.0 csvjoin; compatibility gaps return status 78"
+    },
+    {
+        name: "csvjson",
+        description: "csvkit 2.2.0 csvjson; compatibility gaps return status 78"
+    },
+    {
+        name: "csvlook",
+        description: "csvkit 2.2.0 csvlook; compatibility gaps return status 78"
+    },
+    {
+        name: "csvpy",
+        description: "csvkit 2.2.0 csvpy; compatibility gaps return status 78"
+    },
+    {
+        name: "csvsort",
+        description: "csvkit 2.2.0 csvsort; compatibility gaps return status 78"
+    },
+    {
+        name: "csvsql",
+        description: "csvkit 2.2.0 csvsql; compatibility gaps return status 78"
+    },
+    {
+        name: "csvstack",
+        description: "csvkit 2.2.0 csvstack; compatibility gaps return status 78"
+    },
+    {
+        name: "csvstat",
+        description: "csvkit 2.2.0 csvstat; compatibility gaps return status 78"
+    },
+    {
+        name: "in2csv",
+        description: "csvkit 2.2.0 in2csv; compatibility gaps return status 78"
+    },
+    {
+        name: "sql2csv",
+        description: "csvkit 2.2.0 sql2csv; compatibility gaps return status 78"
+    }
+];
+export const csvkitCommands = (options = {}) => lazyCommandPlugin("csvkit-commands", createCsvkitCommands(options), options.replace ?? false);
+export const createCsvkitCommands = (...args) => {
+    const definitions = createLazyCommands(csvkitMetadata, async () => {
+        const module = await loadcsvkit();
+        return () => module.createCsvkitCommands(...args);
+    });
+    return definitions;
+};
+export const createCsvkitCommand = (...args) => {
+    const metadata = csvkitMetadata.find((item) => item.name === (args[0]?.name ?? "csvclean"));
+    if (!metadata)
+        throw new TypeError("Unknown csvkit command");
+    return createLazyCommands([metadata], async () => {
+        const module = await loadcsvkit();
+        return () => [module.createCsvkitCommand(...args)];
+    })[0];
+};
+export { createGhCommand, createGhCommands, ghCommands } from "./lazy-gh.js";
+/** Extension contract for trusted, statically bundled command code. */
+export { createLazyCommandLoader, createLazyCommands, lazyCommandPlugin } from "./plugins/lazy-command.js";
+const optionalFamilies = {
+    ffmpeg: {
+        metadata: ffmpegMetadata,
+        create: (options) => createFfmpegCommands(options.ffmpeg)
+    },
+    git: {
+        metadata: gitMetadata,
+        create: (options) => createGitCommands(options.git)
+    },
+    soffice: {
+        metadata: sofficeMetadata,
+        create: (options) => createSofficeCommands(options.soffice)
+    },
+    pandoc: {
+        metadata: pandocMetadata,
+        create: (options) => createPandocCommands(options.pandoc)
+    },
+    ssconvert: {
+        metadata: ssconvertMetadata,
+        create: (options) => createSsconvertCommands(options.ssconvert)
+    },
+    pdfinfo: {
+        metadata: pdfinfoMetadata,
+        create: (options) => createPdfinfoCommands(options.pdfinfo)
+    },
+    pdftotext: {
+        metadata: pdftotextMetadata,
+        create: (options) => createPdftotextCommands(options.pdftotext)
+    },
+    pdfimages: {
+        metadata: pdfimagesMetadata,
+        create: (options) => createPdfimagesCommands(options.pdfimages)
+    },
+    pdftoppm: {
+        metadata: pdftoppmMetadata,
+        create: (options) => createPdftoppmCommands(options.pdftoppm)
+    },
+    pdftk: {
+        metadata: pdftkMetadata,
+        create: (options) => createPdftkCommands(options.pdftk)
+    },
+    qpdf: {
+        metadata: qpdfMetadata,
+        create: (options) => createQpdfCommands(options.qpdf)
+    },
+    sips: {
+        metadata: sipsMetadata,
+        create: (options) => createSipsCommands(options.sips)
+    },
+    imagemagick: {
+        metadata: imagemagickMetadata,
+        create: (options) => createImagemagickCommands(options.imagemagick)
+    },
+    wkhtmltopdf: {
+        metadata: wkhtmltopdfMetadata,
+        create: (options) => createWkhtmltopdfCommands(options.wkhtmltopdf)
+    },
+    csvkit: {
+        metadata: csvkitMetadata,
+        create: (options) => createCsvkitCommands(options.csvkit)
+    },
+    gh: {
+        metadata: ghMetadata,
+        create: (options) => createGhCommands(options.gh)
+    }
+};
+export const optionalCommandCatalog = Object.freeze(Object.entries(optionalFamilies).flatMap(([family, entry]) => entry.metadata.map((metadata) => Object.freeze({ family: family, ...metadata }))));
+export function createOptionalCommands(options = {}) {
+    const names = new Set(options.commands ?? []);
+    for (const name of names)
+        if (!optionalCommandCatalog.some((metadata) => metadata.name === name)) {
+            throw new TypeError(`Unknown optional command: ${name}`);
+        }
+    const families = new Set(options.families ?? []);
+    for (const family of families)
+        if (!Object.hasOwn(optionalFamilies, family)) {
+            throw new TypeError(`Unknown optional command family: ${family}`);
+        }
+    const definitions = [];
+    for (const [family, entry] of Object.entries(optionalFamilies)) {
+        const fullFamily = options.profile === "full" || families.has(family);
+        if (!fullFamily && !entry.metadata.some((metadata) => names.has(metadata.name)))
+            continue;
+        definitions.push(...entry
+            .create(options.configuration ?? {})
+            .filter((command) => fullFamily || names.has(command.name))
+            .map((command) => options.profile === "full" ? Object.freeze({ ...command, fallback: true }) : command));
+    }
+    return new CommandRegistry(definitions).list();
+}
+export function optionalCommands(options = {}) {
+    return lazyCommandPlugin("optional-commands", createOptionalCommands(options), options.replace ?? false);
+}
+//# sourceMappingURL=lazy-optional.js.map

package/dist/safe-bash/plugins/composition.d.ts

@@ -1,4 +1,4 @@
-import { type GhCommandOptions } from "../commands/gh/index.js";
+import { type GhCommandOptions } from "../lazy-gh.js";
 import { type CommandDefinition, type CommandHandler } from "../contracts/index.js";
 import { type ExecutionCommandsOptions, type StandardCommandsOptions } from "../commands/standard.js";
 import { type TextProgramOptions } from "../commands/text-programs/index.js";

package/dist/safe-bash/plugins/composition.js

@@ -1,4 +1,4 @@
-import { createGhCommands } from "../commands/gh/index.js";
+import { createGhCommands } from "../lazy-gh.js";
 import { CommandRegistry } from "../contracts/index.js";
 import { PublicDiagnostic } from "../diagnostics.js";
 import { createStandardCommandsWithGrep } from "../commands/standard.js";

package/dist/safe-bash/plugins/lazy-command.d.ts

@@ -0,0 +1,9 @@
+import type { CommandDefinition, VirtualShellPlugin } from "../contracts/index.js";
+/** A static, trusted loader. Share code, never invocation context or authority. */
+export declare function createLazyCommandLoader<T>(load: () => Promise<T>): () => Promise<T>;
+export type LazyCommandMetadata = Omit<CommandDefinition, "execute" | "runtimeIdentity">;
+export type LazyCommandFactory = () => readonly CommandDefinition[];
+/** Factories run per invocation; only the loader's immutable code is shared. */
+export declare function createLazyCommands(metadata: readonly LazyCommandMetadata[], load: () => Promise<LazyCommandFactory>): readonly CommandDefinition[];
+export declare function lazyCommandPlugin(name: string, commands: readonly CommandDefinition[], replace?: boolean): VirtualShellPlugin;
+//# sourceMappingURL=lazy-command.d.ts.map

package/dist/safe-bash/plugins/lazy-command.js

@@ -0,0 +1,57 @@
+import { commandRuntimeIdentity } from "../contracts/command.js";
+/** A static, trusted loader. Share code, never invocation context or authority. */
+export function createLazyCommandLoader(load) {
+    let pending;
+    return () => (pending ??= Promise.resolve()
+        .then(load)
+        .catch((error) => {
+        pending = undefined;
+        throw error;
+    }));
+}
+async function waitForCode(pending, signal) {
+    signal.throwIfAborted();
+    let abort;
+    const cancelled = new Promise((_resolve, reject) => {
+        abort = () => reject(signal.reason);
+        signal.addEventListener("abort", abort, { once: true });
+    });
+    try {
+        return await Promise.race([pending, cancelled]);
+    }
+    finally {
+        signal.removeEventListener("abort", abort);
+    }
+}
+/** Factories run per invocation; only the loader's immutable code is shared. */
+export function createLazyCommands(metadata, load) {
+    return Object.freeze(metadata.map((item) => Object.freeze({
+        ...item,
+        runtimeIdentity: commandRuntimeIdentity,
+        async execute(context) {
+            context.signal.throwIfAborted();
+            const factory = await waitForCode(load(), context.signal);
+            context.signal.throwIfAborted();
+            const definition = factory().find((command) => command.name === item.name);
+            if (!definition)
+                throw new Error(`Lazy command loader did not provide ${item.name}`);
+            return definition.execute(context);
+        }
+    })));
+}
+export function lazyCommandPlugin(name, commands, replace = false) {
+    return {
+        name,
+        setup(host) {
+            if (!replace)
+                for (const command of commands) {
+                    const existing = host.commands.get(command.name);
+                    if (existing && !(command.fallback && !existing.fallback))
+                        throw new Error(`Command already registered: ${command.name}`);
+                }
+            for (const command of commands)
+                host.commands.register(command, { replace });
+        }
+    };
+}
+//# sourceMappingURL=lazy-command.js.map