@notegen/plugin-cli 0.1.0

package/dist/lib/archive.js

@@ -0,0 +1,257 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { Readable } from 'node:stream';
+import { deflateRawSync } from 'node:zlib';
+import * as yauzl from 'yauzl';
+import * as yazl from 'yazl';
+import { MAX_ARCHIVE_BYTES, MAX_ARCHIVE_ENTRIES, MAX_COMPRESSION_RATIO, MAX_ENTRY_BYTES, MAX_UNCOMPRESSED_BYTES, } from './constants.js';
+import { diagnostic, DiagnosticError } from './diagnostics.js';
+import { atomicWriteFile, assertRegularFile, fileSize } from './files.js';
+import { assertUniquePackagePaths, validatePackagePath, } from './path-rules.js';
+function archiveError(code, message, path) {
+    return new DiagnosticError(diagnostic({ code, message, path }));
+}
+const CRC32_TABLE = Uint32Array.from({ length: 256 }, (_, value) => {
+    let current = value;
+    for (let bit = 0; bit < 8; bit += 1) {
+        current = (current & 1) === 1 ? 0xedb88320 ^ (current >>> 1) : current >>> 1;
+    }
+    return current >>> 0;
+});
+function crc32(bytes) {
+    let value = 0xffffffff;
+    for (const byte of bytes) {
+        value = (CRC32_TABLE[(value ^ byte) & 0xff] ?? 0) ^ (value >>> 8);
+    }
+    return (value ^ 0xffffffff) >>> 0;
+}
+function extractedEntryCount(entries) {
+    const extracted = new Set();
+    for (const entry of entries) {
+        extracted.add(entry.path);
+        const segments = entry.path.split('/');
+        for (let index = 1; index < segments.length; index += 1) {
+            extracted.add(segments.slice(0, index).join('/'));
+        }
+    }
+    return extracted.size;
+}
+async function openZip(bytes, path) {
+    return new Promise((resolve, reject) => {
+        yauzl.fromBuffer(bytes, {
+            autoClose: true,
+            decodeStrings: true,
+            lazyEntries: true,
+            strictFileNames: true,
+            validateEntrySizes: true,
+        }, (error, zipFile) => {
+            if (error || !zipFile) {
+                reject(archiveError('archive.invalid', error?.message ?? 'The ZIP archive could not be opened', path));
+                return;
+            }
+            resolve(zipFile);
+        });
+    });
+}
+function openEntryStream(zipFile, entry) {
+    return new Promise((resolve, reject) => {
+        zipFile.openReadStream(entry, (error, stream) => {
+            if (error || !stream) {
+                reject(archiveError('archive.entry_unreadable', error?.message ?? 'The ZIP entry could not be read', entry.fileName));
+                return;
+            }
+            resolve(stream);
+        });
+    });
+}
+async function readStreamLimited(stream, maximum, path) {
+    const chunks = [];
+    let total = 0;
+    for await (const value of stream) {
+        const chunk = typeof value === 'string' ? Buffer.from(value) : Buffer.from(value);
+        total += chunk.length;
+        if (total > maximum) {
+            stream.destroy();
+            throw archiveError('archive.entry_too_large', `Archive entry exceeds ${maximum} bytes`, path);
+        }
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks, total);
+}
+function assertSafeZipMetadata(entry) {
+    if ((entry.generalPurposeBitFlag & 0x1) !== 0) {
+        throw archiveError('archive.encrypted', 'Encrypted ZIP entries are not supported', entry.fileName);
+    }
+    const directory = entry.fileName.endsWith('/');
+    if (entry.compressionMethod !== 0 && entry.compressionMethod !== 8) {
+        throw archiveError('archive.compression', 'Only stored and deflate ZIP entries are supported', entry.fileName);
+    }
+    if (entry.uncompressedSize > MAX_ENTRY_BYTES) {
+        throw archiveError('archive.entry_too_large', `Archive entry exceeds ${MAX_ENTRY_BYTES} bytes`, entry.fileName);
+    }
+    if (entry.uncompressedSize > 0
+        && (entry.compressedSize === 0
+            || (entry.uncompressedSize > 1024 * 1024
+                && entry.uncompressedSize / entry.compressedSize > MAX_COMPRESSION_RATIO))) {
+        throw archiveError('archive.compression_ratio', `Archive entry exceeds the ${MAX_COMPRESSION_RATIO}:1 compression-ratio limit`, entry.fileName);
+    }
+    const hostSystem = (entry.versionMadeBy >>> 8) & 0xff;
+    if (hostSystem === 3) {
+        const mode = (entry.externalFileAttributes >>> 16) & 0xffff;
+        const fileType = mode & 0o170000;
+        if ((fileType !== 0 && fileType !== 0o040000 && fileType !== 0o100000)
+            || (directory && fileType === 0o100000)
+            || (!directory && fileType === 0o040000)) {
+            throw archiveError('archive.special_file', 'Symbolic links and special files are not allowed', entry.fileName);
+        }
+        if (!directory && (mode & 0o111) !== 0) {
+            throw archiveError('archive.executable', 'Executable file modes are not allowed', entry.fileName);
+        }
+    }
+    else if (hostSystem === 0 && entry.externalFileAttributes !== 0) {
+        const attributesDescribeDirectory = (entry.externalFileAttributes & 0x10) !== 0;
+        if (attributesDescribeDirectory !== directory) {
+            throw archiveError('archive.file-type-mismatch', 'DOS ZIP attributes disagree with the entry path type', entry.fileName);
+        }
+    }
+    if (directory && entry.uncompressedSize !== 0) {
+        throw archiveError('archive.directory_payload', 'ZIP directory entries must not contain payload bytes', entry.fileName);
+    }
+    return directory;
+}
+export async function readPackageArchive(path) {
+    await assertRegularFile(path, 'Plugin archive');
+    const size = await fileSize(path);
+    if (size > MAX_ARCHIVE_BYTES) {
+        throw archiveError('archive.too_large', `Plugin archive exceeds ${MAX_ARCHIVE_BYTES} bytes`, path);
+    }
+    const archiveBytes = await readFile(path);
+    if (archiveBytes.byteLength > MAX_ARCHIVE_BYTES) {
+        throw archiveError('archive.too_large', `Plugin archive exceeds ${MAX_ARCHIVE_BYTES} bytes`, path);
+    }
+    const sha256 = createHash('sha256').update(archiveBytes).digest('hex');
+    const zipFile = await openZip(archiveBytes, path);
+    if (zipFile.entryCount > MAX_ARCHIVE_ENTRIES) {
+        zipFile.close();
+        throw archiveError('archive.too_many_entries', `Plugin archive contains more than ${MAX_ARCHIVE_ENTRIES} entries`, path);
+    }
+    const files = new Map();
+    const paths = [];
+    let totalUncompressed = 0;
+    await new Promise((resolve, reject) => {
+        let settled = false;
+        const failArchive = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            zipFile.close();
+            reject(error);
+        };
+        zipFile.once('error', (error) => {
+            failArchive(archiveError('archive.invalid', error.message, path));
+        });
+        zipFile.on('entry', (entry) => {
+            void (async () => {
+                const directory = assertSafeZipMetadata(entry);
+                const safePath = validatePackagePath(entry.fileName, {
+                    directory,
+                    label: 'ZIP entry path',
+                });
+                totalUncompressed += entry.uncompressedSize;
+                if (totalUncompressed > MAX_UNCOMPRESSED_BYTES) {
+                    throw archiveError('archive.uncompressed_too_large', `Expanded plugin archive exceeds ${MAX_UNCOMPRESSED_BYTES} bytes`, path);
+                }
+                paths.push({ path: safePath, directory });
+                assertUniquePackagePaths(paths);
+                if (directory) {
+                    zipFile.readEntry();
+                    return;
+                }
+                const stream = await openEntryStream(zipFile, entry);
+                const bytes = await readStreamLimited(stream, MAX_ENTRY_BYTES, safePath);
+                if (bytes.length !== entry.uncompressedSize) {
+                    throw archiveError('archive.size_mismatch', 'ZIP entry size does not match its central-directory metadata', safePath);
+                }
+                if (crc32(bytes) !== (entry.crc32 >>> 0)) {
+                    throw archiveError('archive.crc-mismatch', 'ZIP entry content does not match its CRC32 metadata', safePath);
+                }
+                files.set(safePath, bytes);
+                zipFile.readEntry();
+            })().catch(failArchive);
+        });
+        zipFile.once('end', () => {
+            if (settled)
+                return;
+            settled = true;
+            resolve();
+        });
+        zipFile.readEntry();
+    });
+    if (extractedEntryCount(paths) > MAX_ARCHIVE_ENTRIES) {
+        throw archiveError('archive.too_many_extracted_entries', `Extracted plugin archive would exceed ${MAX_ARCHIVE_ENTRIES} entries`, path);
+    }
+    return Object.freeze({ files, sha256, size: archiveBytes.byteLength });
+}
+async function outputStreamToBuffer(stream, maximum) {
+    const chunks = [];
+    let size = 0;
+    for await (const value of stream) {
+        const chunk = typeof value === 'string' ? Buffer.from(value) : Buffer.from(value);
+        size += chunk.length;
+        if (size > maximum) {
+            stream.destroy();
+            throw archiveError('archive.too_large', `Generated plugin archive exceeds ${maximum} bytes`);
+        }
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks, size);
+}
+export async function writePackageArchive(input, outputPath, options = {}) {
+    const files = [...input].map((file) => ({
+        path: validatePackagePath(file.path),
+        bytes: Buffer.from(file.bytes),
+    }));
+    if (files.length === 0) {
+        throw archiveError('archive.empty', 'A plugin archive cannot be empty');
+    }
+    if (files.length > MAX_ARCHIVE_ENTRIES) {
+        throw archiveError('archive.too_many_entries', `A plugin archive cannot contain more than ${MAX_ARCHIVE_ENTRIES} entries`);
+    }
+    assertUniquePackagePaths(files.map((file) => ({ path: file.path })));
+    if (extractedEntryCount(files.map((file) => ({ path: file.path }))) > MAX_ARCHIVE_ENTRIES) {
+        throw archiveError('archive.too_many_extracted_entries', `A plugin archive cannot expand to more than ${MAX_ARCHIVE_ENTRIES} entries`);
+    }
+    let expandedSize = 0;
+    for (const file of files) {
+        if (file.bytes.length > MAX_ENTRY_BYTES) {
+            throw archiveError('archive.entry_too_large', `Package file exceeds ${MAX_ENTRY_BYTES} bytes`, file.path);
+        }
+        expandedSize += file.bytes.length;
+    }
+    if (expandedSize > MAX_UNCOMPRESSED_BYTES) {
+        throw archiveError('archive.uncompressed_too_large', `Package payload exceeds ${MAX_UNCOMPRESSED_BYTES} bytes`);
+    }
+    files.sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
+    const zip = new yazl.ZipFile();
+    const timestamp = new Date('1980-01-01T00:00:00.000Z');
+    for (const file of files) {
+        const compressed = file.bytes.length <= 1024 * 1024
+            ? true
+            : file.bytes.length <= deflateRawSync(file.bytes, { level: 9 }).byteLength * MAX_COMPRESSION_RATIO;
+        zip.addBuffer(file.bytes, file.path, {
+            compress: compressed,
+            compressionLevel: 9,
+            forceZip64Format: false,
+            mode: 0o100644,
+            mtime: timestamp,
+        });
+    }
+    zip.end();
+    const bytes = await outputStreamToBuffer(zip.outputStream, MAX_ARCHIVE_BYTES);
+    await atomicWriteFile(outputPath, bytes, { force: options.force, mode: 0o644 });
+    return Object.freeze({
+        path: outputPath,
+        sha256: createHash('sha256').update(bytes).digest('hex'),
+        size: bytes.length,
+    });
+}

package/dist/lib/constants.d.ts

@@ -0,0 +1,16 @@
+export declare const PACKAGE_EXTENSION = ".notegen-plugin";
+export declare const UNSIGNED_PACKAGE_EXTENSION = ".unsigned.notegen-plugin";
+export declare const DEVELOPMENT_OUTPUT_DIRECTORY = ".notegen/package";
+export declare const RELEASE_OUTPUT_DIRECTORY = ".notegen/releases";
+export declare const MAX_ARCHIVE_BYTES: number;
+export declare const MAX_UNCOMPRESSED_BYTES: number;
+export declare const MAX_ENTRY_BYTES: number;
+export declare const MAX_ENTRY_FILE_BYTES: number;
+export declare const MAX_ARCHIVE_ENTRIES = 256;
+export declare const MAX_COMPRESSION_RATIO = 100;
+export declare const EXIT_SUCCESS = 0;
+export declare const EXIT_PROJECT_FAILURE = 1;
+export declare const EXIT_USAGE = 2;
+export declare const EXIT_UNSAFE_REFUSAL = 3;
+export declare const EXIT_UNEXPECTED = 70;
+export declare const EXIT_INTERRUPTED = 130;

package/dist/lib/constants.js

@@ -0,0 +1,16 @@
+export const PACKAGE_EXTENSION = '.notegen-plugin';
+export const UNSIGNED_PACKAGE_EXTENSION = '.unsigned.notegen-plugin';
+export const DEVELOPMENT_OUTPUT_DIRECTORY = '.notegen/package';
+export const RELEASE_OUTPUT_DIRECTORY = '.notegen/releases';
+export const MAX_ARCHIVE_BYTES = 20 * 1024 * 1024;
+export const MAX_UNCOMPRESSED_BYTES = 50 * 1024 * 1024;
+export const MAX_ENTRY_BYTES = 10 * 1024 * 1024;
+export const MAX_ENTRY_FILE_BYTES = 5 * 1024 * 1024;
+export const MAX_ARCHIVE_ENTRIES = 256;
+export const MAX_COMPRESSION_RATIO = 100;
+export const EXIT_SUCCESS = 0;
+export const EXIT_PROJECT_FAILURE = 1;
+export const EXIT_USAGE = 2;
+export const EXIT_UNSAFE_REFUSAL = 3;
+export const EXIT_UNEXPECTED = 70;
+export const EXIT_INTERRUPTED = 130;

package/dist/lib/diagnostics.d.ts

@@ -0,0 +1,25 @@
+export type DiagnosticSeverity = 'error' | 'warning';
+export interface Diagnostic {
+    readonly severity: DiagnosticSeverity;
+    readonly code: string;
+    readonly message: string;
+    readonly path?: string;
+    readonly hint?: string;
+}
+export interface DiagnosticInput {
+    readonly severity?: DiagnosticSeverity;
+    readonly code: string;
+    readonly message: string;
+    readonly path?: string;
+    readonly hint?: string;
+}
+export declare function diagnostic(input: DiagnosticInput): Diagnostic;
+export declare class DiagnosticError extends Error {
+    readonly diagnostics: readonly Diagnostic[];
+    constructor(diagnostics: Diagnostic | readonly Diagnostic[]);
+}
+export declare function fail(code: string, message: string, path?: string, hint?: string): never;
+export declare function isDiagnosticError(value: unknown): value is DiagnosticError;
+export declare function hasDiagnosticErrors(diagnostics: readonly Diagnostic[]): boolean;
+export declare function formatDiagnostic(value: Diagnostic): string;
+export declare function diagnosticsFromError(error: unknown): readonly Diagnostic[];

package/dist/lib/diagnostics.js

@@ -0,0 +1,49 @@
+export function diagnostic(input) {
+    return Object.freeze({
+        severity: input.severity ?? 'error',
+        code: input.code,
+        message: input.message,
+        ...(input.path === undefined ? {} : { path: input.path }),
+        ...(input.hint === undefined ? {} : { hint: input.hint }),
+    });
+}
+export class DiagnosticError extends Error {
+    diagnostics;
+    constructor(diagnostics) {
+        const values = Array.isArray(diagnostics)
+            ? diagnostics
+            : [diagnostics];
+        const first = values[0];
+        super(first?.message ?? 'NoteGen plugin validation failed');
+        this.name = 'DiagnosticError';
+        this.diagnostics = Object.freeze([...values]);
+    }
+}
+export function fail(code, message, path, hint) {
+    throw new DiagnosticError(diagnostic({ code, message, path, hint }));
+}
+export function isDiagnosticError(value) {
+    return value instanceof DiagnosticError;
+}
+export function hasDiagnosticErrors(diagnostics) {
+    return diagnostics.some((item) => item.severity === 'error');
+}
+export function formatDiagnostic(value) {
+    const location = value.path ? ` ${value.path}` : '';
+    const hint = value.hint ? `\n  hint: ${value.hint}` : '';
+    return `${value.severity.toUpperCase()} [${value.code}]${location}: ${value.message}${hint}`;
+}
+export function diagnosticsFromError(error) {
+    if (isDiagnosticError(error))
+        return error.diagnostics;
+    if (error instanceof Error) {
+        return [diagnostic({
+                code: 'internal.unexpected',
+                message: error.message || error.name,
+            })];
+    }
+    return [diagnostic({
+            code: 'internal.unexpected',
+            message: typeof error === 'string' ? error : 'Unexpected failure',
+        })];
+}

package/dist/lib/files.d.ts

@@ -0,0 +1,30 @@
+export declare function pathExists(path: string): Promise<boolean>;
+export declare function assertRegularFile(path: string, label?: string): Promise<void>;
+export declare function assertDirectory(path: string, label?: string): Promise<void>;
+export declare function assertInside(parent: string, candidate: string, label?: string): void;
+export declare function assertNoSymlinkComponents(parent: string, candidate: string, label?: string): Promise<void>;
+export declare function readUtf8File(path: string, label?: string): Promise<string>;
+export declare function writeFileExclusive(path: string, contents: string | Uint8Array, mode?: number): Promise<void>;
+export declare function atomicWriteFile(path: string, contents: string | Uint8Array, options?: {
+    readonly force?: boolean;
+    readonly mode?: number;
+}): Promise<void>;
+export interface AtomicFileWrite {
+    readonly path: string;
+    readonly contents: string | Uint8Array;
+    readonly mode?: number;
+}
+/**
+ * Publishes a related set of files as one recoverable transaction. Each target
+ * is linked from a fully written sibling file, and any replaced files are kept
+ * until every new target has been committed. If a later commit fails, already
+ * committed targets are removed and the previous set is restored.
+ */
+export declare function atomicWriteFiles(input: readonly AtomicFileWrite[], options?: {
+    readonly force?: boolean;
+}): Promise<void>;
+export declare function replaceDirectoryAtomically(destination: string, populate: (temporary: string) => Promise<void>): Promise<void>;
+export declare function makeTemporaryDirectory(prefix: string): Promise<string>;
+export declare function copyRegularFile(source: string, destination: string): Promise<void>;
+export declare function canonicalPath(path: string): Promise<string>;
+export declare function fileSize(path: string): Promise<number>;