@notegen/plugin-cli 0.1.0

package/dist/lib/files.js

@@ -0,0 +1,396 @@
+import { constants as fsConstants } from 'node:fs';
+import { chmod, copyFile, link, lstat, mkdir, mkdtemp, readFile, realpath, rename, rm, stat, writeFile, } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { tmpdir } from 'node:os';
+import { randomBytes } from 'node:crypto';
+import { diagnostic, DiagnosticError } from './diagnostics.js';
+export async function pathExists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        const cause = error;
+        if (cause.code === 'ENOENT')
+            return false;
+        throw new DiagnosticError(diagnostic({
+            code: 'path.inspection-failed',
+            message: 'Unable to inspect path existence',
+            path,
+        }));
+    }
+}
+export async function assertRegularFile(path, label = 'File') {
+    let metadata;
+    try {
+        metadata = await lstat(path);
+    }
+    catch (error) {
+        const cause = error;
+        if (cause.code !== 'ENOENT') {
+            throw new DiagnosticError(diagnostic({
+                code: 'file.inspection-failed',
+                message: `Unable to inspect ${label.toLowerCase()}`,
+                path,
+            }));
+        }
+        throw new DiagnosticError(diagnostic({
+            code: 'file.missing',
+            message: `${label} does not exist`,
+            path,
+        }));
+    }
+    if (!metadata.isFile() || metadata.isSymbolicLink()) {
+        throw new DiagnosticError(diagnostic({
+            code: 'file.not_regular',
+            message: `${label} must be a regular file and cannot be a symbolic link`,
+            path,
+        }));
+    }
+}
+export async function assertDirectory(path, label = 'Directory') {
+    let metadata;
+    try {
+        metadata = await lstat(path);
+    }
+    catch (error) {
+        const cause = error;
+        if (cause.code !== 'ENOENT') {
+            throw new DiagnosticError(diagnostic({
+                code: 'directory.inspection-failed',
+                message: `Unable to inspect ${label.toLowerCase()}`,
+                path,
+            }));
+        }
+        throw new DiagnosticError(diagnostic({
+            code: 'directory.missing',
+            message: `${label} does not exist`,
+            path,
+        }));
+    }
+    if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+        throw new DiagnosticError(diagnostic({
+            code: 'directory.not_regular',
+            message: `${label} must be a directory and cannot be a symbolic link`,
+            path,
+        }));
+    }
+}
+export function assertInside(parent, candidate, label = 'Path') {
+    const parentPath = resolve(parent);
+    const candidatePath = resolve(candidate);
+    const child = relative(parentPath, candidatePath);
+    if (child === '' || (!child.startsWith(`..${sep}`) && child !== '..' && !isAbsolute(child))) {
+        return;
+    }
+    throw new DiagnosticError(diagnostic({
+        code: 'path.outside_project',
+        message: `${label} must stay inside ${parentPath}`,
+        path: candidatePath,
+    }));
+}
+export async function assertNoSymlinkComponents(parent, candidate, label = 'Path') {
+    const root = resolve(parent);
+    const target = resolve(candidate);
+    assertInside(root, target, label);
+    const child = relative(root, target);
+    if (child === '')
+        return;
+    const segments = child.split(sep);
+    let current = root;
+    for (let index = 0; index < segments.length; index += 1) {
+        current = join(current, segments[index] ?? '');
+        let metadata;
+        try {
+            metadata = await lstat(current);
+        }
+        catch (error) {
+            const cause = error;
+            if (cause.code === 'ENOENT')
+                return;
+            throw error;
+        }
+        if (metadata.isSymbolicLink()) {
+            throw new DiagnosticError(diagnostic({
+                code: 'path.symlink',
+                message: `${label} cannot contain symbolic links`,
+                path: current,
+            }));
+        }
+        if (index < segments.length - 1 && !metadata.isDirectory()) {
+            throw new DiagnosticError(diagnostic({
+                code: 'path.parent_not_directory',
+                message: `${label} has a parent that is not a directory`,
+                path: current,
+            }));
+        }
+    }
+}
+export async function readUtf8File(path, label = 'File') {
+    await assertRegularFile(path, label);
+    const bytes = await readFile(path);
+    const decoded = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    if (decoded.includes('\0')) {
+        throw new DiagnosticError(diagnostic({
+            code: 'file.nul_byte',
+            message: `${label} must not contain NUL bytes`,
+            path,
+        }));
+    }
+    return decoded;
+}
+export async function writeFileExclusive(path, contents, mode) {
+    await atomicWriteFiles([{
+            path,
+            contents,
+            ...(mode === undefined ? {} : { mode }),
+        }]);
+}
+export async function atomicWriteFile(path, contents, options = {}) {
+    await atomicWriteFiles([{
+            path,
+            contents,
+            ...(options.mode === undefined ? {} : { mode: options.mode }),
+        }], { force: options.force });
+}
+/**
+ * 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 async function atomicWriteFiles(input, options = {}) {
+    const transactionId = randomBytes(12).toString('hex');
+    const files = input.map((item, index) => {
+        const output = resolve(item.path);
+        return {
+            output,
+            temporary: join(dirname(output), `.${transactionId}-${index}.tmp`),
+            backup: join(dirname(output), `.${transactionId}-${index}.previous`),
+            contents: item.contents,
+            ...(item.mode === undefined ? {} : { mode: item.mode }),
+            existed: false,
+            backedUp: false,
+            committed: false,
+        };
+    });
+    if (new Set(files.map((item) => item.output)).size !== files.length) {
+        throw new DiagnosticError(diagnostic({
+            code: 'file.duplicate-output',
+            message: 'A transactional write cannot target the same file more than once',
+        }));
+    }
+    let completed = false;
+    try {
+        for (const item of files) {
+            await mkdir(dirname(item.output), { recursive: true });
+            try {
+                const metadata = await lstat(item.output);
+                item.existed = true;
+                if (!metadata.isFile() || metadata.isSymbolicLink()) {
+                    throw new DiagnosticError(diagnostic({
+                        code: 'file.not_regular',
+                        message: 'Refusing to replace a non-regular file',
+                        path: item.output,
+                    }));
+                }
+                if (!options.force) {
+                    throw new DiagnosticError(diagnostic({
+                        code: 'file.exists',
+                        message: 'Refusing to overwrite an existing file',
+                        path: item.output,
+                        hint: 'Choose another output path or pass --force after reviewing the target.',
+                    }));
+                }
+            }
+            catch (error) {
+                const cause = error;
+                if (cause.code !== 'ENOENT')
+                    throw error;
+            }
+            await writeFile(item.temporary, item.contents, {
+                flag: 'wx',
+                ...(item.mode === undefined ? {} : { mode: item.mode }),
+            });
+            if (item.mode !== undefined)
+                await chmod(item.temporary, item.mode);
+        }
+        for (const item of files) {
+            if (item.existed) {
+                await rename(item.output, item.backup);
+                item.backedUp = true;
+            }
+        }
+        for (const item of files) {
+            // A hard link is an atomic no-clobber publish because the staged file is
+            // in the same directory (and therefore on the same filesystem).
+            await link(item.temporary, item.output);
+            item.committed = true;
+            await rm(item.temporary, { force: true });
+        }
+        completed = true;
+        const retainedBackups = [];
+        for (const item of files) {
+            if (!item.backedUp)
+                continue;
+            try {
+                await rm(item.backup, { force: true });
+                item.backedUp = false;
+            }
+            catch {
+                retainedBackups.push(item.backup);
+            }
+        }
+        if (retainedBackups.length > 0) {
+            throw new DiagnosticError(diagnostic({
+                code: 'file.backup-cleanup-failed',
+                message: 'The new files were published, but an old backup could not be removed',
+                path: retainedBackups.join(', '),
+                hint: 'The new files are active. Securely remove the listed .previous backup files.',
+            }));
+        }
+    }
+    catch (error) {
+        if (completed)
+            throw error;
+        const recoveryFailures = [];
+        for (const item of [...files].reverse()) {
+            if (item.committed) {
+                try {
+                    await rm(item.output, { force: true });
+                    item.committed = false;
+                }
+                catch {
+                    recoveryFailures.push(item.output);
+                }
+            }
+        }
+        for (const item of [...files].reverse()) {
+            if (item.backedUp) {
+                await rename(item.backup, item.output).then(() => {
+                    item.backedUp = false;
+                }).catch(() => {
+                    recoveryFailures.push(item.backup);
+                });
+            }
+        }
+        for (const item of files) {
+            await rm(item.temporary, { force: true }).catch(() => {
+                recoveryFailures.push(item.temporary);
+            });
+        }
+        if (recoveryFailures.length > 0) {
+            throw new DiagnosticError(diagnostic({
+                code: 'file.transaction-recovery-failed',
+                message: 'A transactional write failed and cleanup or recovery was incomplete',
+                path: recoveryFailures.join(', '),
+                hint: 'Keep any listed .previous files; they contain the recoverable originals.',
+            }));
+        }
+        throw error;
+    }
+    finally {
+        for (const item of files) {
+            await rm(item.temporary, { force: true }).catch(() => undefined);
+            if (completed && item.backedUp)
+                await rm(item.backup, { force: true }).catch(() => undefined);
+        }
+    }
+}
+export async function replaceDirectoryAtomically(destination, populate) {
+    const output = resolve(destination);
+    await mkdir(dirname(output), { recursive: true });
+    const temporary = await mkdtemp(join(dirname(output), '.notegen-stage-'));
+    const previous = `${output}.previous-${randomBytes(8).toString('hex')}`;
+    let movedPrevious = false;
+    let published = false;
+    try {
+        await populate(temporary);
+        if (await pathExists(output)) {
+            const existing = await lstat(output);
+            if (!existing.isDirectory() || existing.isSymbolicLink()) {
+                throw new DiagnosticError(diagnostic({
+                    code: 'output.unsafe',
+                    message: 'Development output must be a real directory',
+                    path: output,
+                }));
+            }
+            await rename(output, previous);
+            movedPrevious = true;
+        }
+        await rename(temporary, output);
+        published = true;
+        if (movedPrevious) {
+            try {
+                await rm(previous, { recursive: true, force: true });
+                movedPrevious = false;
+            }
+            catch {
+                throw new DiagnosticError(diagnostic({
+                    code: 'output.backup-cleanup-failed',
+                    message: 'The new development output is active, but its previous backup could not be removed',
+                    path: previous,
+                    hint: 'Review the new output, then remove the listed previous backup manually.',
+                }));
+            }
+        }
+    }
+    catch (error) {
+        if (!published && movedPrevious) {
+            let outputExists = false;
+            try {
+                await lstat(output);
+                outputExists = true;
+            }
+            catch (inspectionError) {
+                const cause = inspectionError;
+                if (cause.code !== 'ENOENT') {
+                    throw new DiagnosticError(diagnostic({
+                        code: 'output.transaction-recovery-failed',
+                        message: 'Publishing failed and the destination could not be inspected during recovery',
+                        path: previous,
+                        hint: 'Keep the listed previous backup; it contains the recoverable original output.',
+                    }));
+                }
+            }
+            if (outputExists) {
+                throw new DiagnosticError(diagnostic({
+                    code: 'output.transaction-recovery-failed',
+                    message: 'Publishing failed because the destination changed, so the previous output was preserved separately',
+                    path: previous,
+                    hint: 'Keep the listed previous backup and reconcile it with the current destination manually.',
+                }));
+            }
+            try {
+                await rename(previous, output);
+                movedPrevious = false;
+            }
+            catch {
+                throw new DiagnosticError(diagnostic({
+                    code: 'output.transaction-recovery-failed',
+                    message: 'Publishing failed and the previous development output could not be restored',
+                    path: previous,
+                    hint: 'Keep the listed previous backup; it contains the recoverable original output.',
+                }));
+            }
+        }
+        throw error;
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+export async function makeTemporaryDirectory(prefix) {
+    return mkdtemp(join(tmpdir(), prefix));
+}
+export async function copyRegularFile(source, destination) {
+    await assertRegularFile(source);
+    await mkdir(dirname(destination), { recursive: true });
+    await copyFile(source, destination, fsConstants.COPYFILE_EXCL);
+}
+export async function canonicalPath(path) {
+    return realpath(resolve(path));
+}
+export async function fileSize(path) {
+    return (await stat(path)).size;
+}

package/dist/lib/integrity.d.ts

@@ -0,0 +1,20 @@
+export declare const INTEGRITY_VERSION: 1;
+export declare const INTEGRITY_ALGORITHM: "sha256";
+export declare const MAX_SIGNATURE_FILE_BYTES: number;
+export interface IntegrityFileV1 {
+    readonly path: string;
+    readonly size: number;
+    readonly sha256: string;
+}
+export interface IntegrityManifestV1 {
+    readonly version: 1;
+    readonly algorithm: 'sha256';
+    readonly files: readonly IntegrityFileV1[];
+}
+export type PackageFileMap = ReadonlyMap<string, Uint8Array>;
+export declare function sha256Hex(bytes: Uint8Array): string;
+export declare function isLowercaseSha256(value: unknown): value is string;
+export declare function createIntegrityManifest(files: PackageFileMap): IntegrityManifestV1;
+export declare function serializeIntegrityManifest(integrity: IntegrityManifestV1): string;
+export declare function validateIntegrityManifest(value: unknown, actualFiles?: PackageFileMap): IntegrityManifestV1;
+export declare function parseIntegrityManifest(input: string | Uint8Array, actualFiles?: PackageFileMap): IntegrityManifestV1;

package/dist/lib/integrity.js

@@ -0,0 +1,162 @@
+import { createHash } from 'node:crypto';
+import { MAX_ARCHIVE_ENTRIES, MAX_ENTRY_BYTES, MAX_UNCOMPRESSED_BYTES, } from './constants.js';
+import { fail } from './diagnostics.js';
+import { assertUniquePackagePaths, countPackageEntries, packagePathCollisionKey, validatePackagePath, } from './path-rules.js';
+import { assertJsonIntegerToken, isJsonObject, parseStrictJson } from './strict-json.js';
+export const INTEGRITY_VERSION = 1;
+export const INTEGRITY_ALGORITHM = 'sha256';
+export const MAX_SIGNATURE_FILE_BYTES = 8 * 1_024;
+function objectValue(value, path) {
+    if (!isJsonObject(value))
+        fail('integrity.expected-object', `${path} must be an object`, path);
+    return value;
+}
+function assertAllowedKeys(object, allowed, path) {
+    const accepted = new Set(allowed);
+    const unknown = Object.keys(object).find((key) => !accepted.has(key));
+    if (unknown !== undefined) {
+        fail('integrity.unknown-field', `${path}.${unknown} is not supported`, `${path}.${unknown}`);
+    }
+}
+function required(object, key, path) {
+    if (!Object.hasOwn(object, key))
+        fail('integrity.missing-field', `${path}.${key} is required`, `${path}.${key}`);
+    return object[key];
+}
+function safeUnsignedInteger(value, path) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+        fail('integrity.invalid-size', `${path} must be a non-negative safe integer`, path);
+    }
+    return value;
+}
+export function sha256Hex(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+export function isLowercaseSha256(value) {
+    return typeof value === 'string' && /^[0-9a-f]{64}$(?![\s\S])/u.test(value);
+}
+function payloadFiles(files) {
+    return new Map([...files.entries()].filter(([path]) => path !== 'integrity.json' && path !== 'signature.sig'));
+}
+function validateActualFiles(files) {
+    const entries = [...files.entries()];
+    assertUniquePackagePaths(entries.map(([path]) => ({ path })));
+    let total = 0;
+    for (const [rawPath, bytes] of entries) {
+        const path = validatePackagePath(rawPath, { label: rawPath });
+        if (bytes.byteLength > MAX_ENTRY_BYTES) {
+            fail('package.file-too-large', `${path} exceeds the 10 MiB file limit`, path);
+        }
+        total += bytes.byteLength;
+        if (total > MAX_UNCOMPRESSED_BYTES) {
+            fail('package.too-large', 'Package exceeds the 50 MiB uncompressed limit', path);
+        }
+    }
+    if (countPackageEntries(entries.map(([path]) => path)) > MAX_ARCHIVE_ENTRIES) {
+        fail('package.too-many-entries', `Package exceeds the ${MAX_ARCHIVE_ENTRIES}-entry limit`);
+    }
+    const signature = files.get('signature.sig');
+    if (signature && signature.byteLength > MAX_SIGNATURE_FILE_BYTES) {
+        fail('package.signature-too-large', 'signature.sig exceeds the 8 KiB limit', 'signature.sig');
+    }
+}
+export function createIntegrityManifest(files) {
+    validateActualFiles(files);
+    const payload = payloadFiles(files);
+    if (!payload.has('plugin.json')) {
+        fail('integrity.missing-plugin-manifest', 'Integrity manifest must cover plugin.json', 'plugin.json');
+    }
+    const entries = [...payload.entries()]
+        .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+        .map(([path, bytes]) => ({
+        path: validatePackagePath(path, { label: path }),
+        size: bytes.byteLength,
+        sha256: sha256Hex(bytes),
+    }));
+    return {
+        version: INTEGRITY_VERSION,
+        algorithm: INTEGRITY_ALGORITHM,
+        files: entries,
+    };
+}
+export function serializeIntegrityManifest(integrity) {
+    return `${JSON.stringify(integrity, null, 2)}\n`;
+}
+export function validateIntegrityManifest(value, actualFiles) {
+    const integrity = objectValue(value, '$');
+    assertAllowedKeys(integrity, ['version', 'algorithm', 'files'], '$');
+    if (required(integrity, 'version', '$') !== INTEGRITY_VERSION) {
+        fail('integrity.unsupported-version', 'integrity.json version must be 1', '$.version');
+    }
+    assertJsonIntegerToken(integrity, 'version', '$.version');
+    if (required(integrity, 'algorithm', '$') !== INTEGRITY_ALGORITHM) {
+        fail('integrity.unsupported-algorithm', 'integrity.json algorithm must be sha256', '$.algorithm');
+    }
+    const rawFiles = required(integrity, 'files', '$');
+    if (!Array.isArray(rawFiles))
+        fail('integrity.expected-array', '$.files must be an array', '$.files');
+    const declared = new Map();
+    const folded = new Set();
+    let declaredBytes = 0;
+    for (const [index, rawFile] of rawFiles.entries()) {
+        const pathLabel = `$.files[${index}]`;
+        const file = objectValue(rawFile, pathLabel);
+        assertAllowedKeys(file, ['path', 'size', 'sha256'], pathLabel);
+        const rawPath = required(file, 'path', pathLabel);
+        if (typeof rawPath !== 'string')
+            fail('integrity.invalid-path', `${pathLabel}.path must be a string`, `${pathLabel}.path`);
+        const path = validatePackagePath(rawPath, { label: `${pathLabel}.path` });
+        const size = safeUnsignedInteger(required(file, 'size', pathLabel), `${pathLabel}.size`);
+        assertJsonIntegerToken(file, 'size', `${pathLabel}.size`);
+        const digest = required(file, 'sha256', pathLabel);
+        if (!isLowercaseSha256(digest)) {
+            fail('integrity.invalid-digest', `${pathLabel}.sha256 must be a lowercase SHA-256 digest`, `${pathLabel}.sha256`);
+        }
+        const collisionKey = packagePathCollisionKey(path);
+        if (path === 'integrity.json'
+            || path === 'signature.sig'
+            || declared.has(path)
+            || folded.has(collisionKey)) {
+            fail('integrity.duplicate-or-forbidden-path', `${pathLabel}.path is duplicated or forbidden`, `${pathLabel}.path`);
+        }
+        if (size > MAX_ENTRY_BYTES) {
+            fail('package.file-too-large', `${path} exceeds the 10 MiB file limit`, `${pathLabel}.size`);
+        }
+        declaredBytes += size;
+        if (declaredBytes > MAX_UNCOMPRESSED_BYTES) {
+            fail('package.too-large', 'Declared payload exceeds the 50 MiB uncompressed limit', '$.files');
+        }
+        folded.add(collisionKey);
+        declared.set(path, { path, size, sha256: digest });
+    }
+    if (!declared.has('plugin.json')) {
+        fail('integrity.missing-plugin-manifest', 'Integrity manifest must cover plugin.json', '$.files');
+    }
+    assertUniquePackagePaths([...declared.keys()].map((path) => ({ path })));
+    if (countPackageEntries([...declared.keys(), 'integrity.json']) > MAX_ARCHIVE_ENTRIES) {
+        fail('package.too-many-entries', `Package exceeds the ${MAX_ARCHIVE_ENTRIES}-entry limit`, '$.files');
+    }
+    if (actualFiles) {
+        validateActualFiles(actualFiles);
+        const actualPayload = payloadFiles(actualFiles);
+        if (declared.size !== actualPayload.size) {
+            fail('integrity.file-set-mismatch', 'Payload file set does not exactly match integrity.json', '$.files');
+        }
+        for (const [path, declaration] of declared) {
+            const bytes = actualPayload.get(path);
+            if (!bytes)
+                fail('integrity.missing-file', `integrity.json references missing file ${path}`, path);
+            if (bytes.byteLength !== declaration.size || sha256Hex(bytes) !== declaration.sha256) {
+                fail('integrity.content-mismatch', `${path} does not match its size or SHA-256 digest`, path);
+            }
+        }
+        const undeclared = [...actualPayload.keys()].find((path) => !declared.has(path));
+        if (undeclared !== undefined) {
+            fail('integrity.undeclared-file', `Package contains undeclared payload ${undeclared}`, undeclared);
+        }
+    }
+    return integrity;
+}
+export function parseIntegrityManifest(input, actualFiles) {
+    return validateIntegrityManifest(parseStrictJson(input, 'integrity.json'), actualFiles);
+}

package/dist/lib/manifest.d.ts

@@ -0,0 +1,13 @@
+import { type PluginManifestV1 } from '@notegen/plugin-api';
+export interface ManifestValidationOptions {
+    /** Concrete host API version. Defaults to the API package's current version. */
+    readonly apiVersion?: string;
+    /** Concrete NoteGen version. Compatibility is checked only when supplied. */
+    readonly appVersion?: string;
+    /** Package payload, keyed by canonical relative path. Enables file and locale checks. */
+    readonly files?: ReadonlyMap<string, Uint8Array>;
+}
+export declare function satisfiesPluginApiRequirement(supported: string, requirement: string): boolean;
+export declare function validateLocaleMessages(value: unknown, path?: string): Readonly<Record<string, string>>;
+export declare function validatePluginManifest(value: unknown, options?: ManifestValidationOptions): PluginManifestV1;
+export declare function parsePluginManifest(input: string | Uint8Array, options?: ManifestValidationOptions): PluginManifestV1;