@notegen/plugin-cli 0.1.0

package/dist/lib/package.js

@@ -0,0 +1,229 @@
+import { lstat, readFile, readdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { decodePackageSignature, assertPackageSignature } from './signing.js';
+import { MAX_ARCHIVE_ENTRIES, MAX_ENTRY_BYTES, MAX_UNCOMPRESSED_BYTES, } from './constants.js';
+import { MAX_SIGNATURE_FILE_BYTES, parseIntegrityManifest, } from './integrity.js';
+import { parsePluginManifest } from './manifest.js';
+import { parseStrictJson, isJsonObject } from './strict-json.js';
+import { assertDirectory, assertInside } from './files.js';
+import { diagnostic, DiagnosticError, fail } from './diagnostics.js';
+import { assertUniquePackagePaths, validatePackagePath } from './path-rules.js';
+function requiredFile(files, path) {
+    const bytes = files.get(path);
+    if (!bytes)
+        fail('package.missing-file', `Plugin package is missing ${path}`, path);
+    return bytes;
+}
+function decodeUtf8(bytes, path) {
+    try {
+        const value = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+        if (value.includes('\0'))
+            fail('package.nul-byte', `${path} contains a NUL byte`, path);
+        return value;
+    }
+    catch (error) {
+        if (error instanceof DiagnosticError)
+            throw error;
+        fail('package.invalid-utf8', `${path} must contain valid UTF-8`, path);
+    }
+}
+function validateOptionalPackageJson(files) {
+    const bytes = files.get('package.json');
+    if (!bytes)
+        return;
+    const value = parseStrictJson(bytes, 'package.json');
+    if (!isJsonObject(value))
+        return;
+    const scripts = value.scripts;
+    if (!isJsonObject(scripts))
+        return;
+    for (const name of ['preinstall', 'install', 'postinstall']) {
+        if (Object.hasOwn(scripts, name)) {
+            fail('package.install-script', `Plugin packages must not contain the ${name} lifecycle script`, `package.json#scripts.${name}`);
+        }
+    }
+}
+export function validatePackageFiles(files, options = {}) {
+    const pluginBytes = requiredFile(files, 'plugin.json');
+    const integrityBytes = requiredFile(files, 'integrity.json');
+    const manifestValue = parseStrictJson(pluginBytes, 'plugin.json');
+    const integrityValue = parseStrictJson(integrityBytes, 'integrity.json');
+    const integrity = parseIntegrityManifest(integrityBytes, files);
+    const manifest = parsePluginManifest(pluginBytes, {
+        files,
+        ...(options.apiVersion === undefined ? {} : { apiVersion: options.apiVersion }),
+        ...(options.appVersion === undefined ? {} : { appVersion: options.appVersion }),
+    });
+    validateOptionalPackageJson(files);
+    const signatureBytes = files.get('signature.sig');
+    const signature = signatureBytes ? decodeUtf8(signatureBytes, 'signature.sig') : undefined;
+    if (signature !== undefined)
+        decodePackageSignature(signature);
+    if (options.requireSignature && signature === undefined) {
+        fail('signature.missing', 'Signed plugin package is missing signature.sig', 'signature.sig');
+    }
+    if (options.publicKey !== undefined && signature === undefined) {
+        fail('signature.missing', 'A public key was provided but the package has no signature.sig', 'signature.sig');
+    }
+    if (options.publicKey !== undefined && signature !== undefined) {
+        assertPackageSignature(manifestValue, integrityValue, signature, options.publicKey);
+    }
+    return Object.freeze({
+        manifest,
+        manifestValue,
+        integrity,
+        integrityValue,
+        files,
+        signature,
+        signatureVerified: options.publicKey !== undefined,
+    });
+}
+async function readSafePackageFile(root, relativePath, maximumBytes = MAX_ENTRY_BYTES) {
+    const segments = relativePath.split('/');
+    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 {
+            throw new DiagnosticError(diagnostic({
+                code: 'package.missing-file',
+                message: `Plugin package is missing ${relativePath}`,
+                path: current,
+            }));
+        }
+        if (metadata.isSymbolicLink()) {
+            throw new DiagnosticError(diagnostic({
+                code: 'package.symlink',
+                message: 'Plugin package paths cannot contain symbolic links',
+                path: current,
+            }));
+        }
+        const final = index === segments.length - 1;
+        if (final ? !metadata.isFile() : !metadata.isDirectory()) {
+            throw new DiagnosticError(diagnostic({
+                code: 'package.file-type',
+                message: final ? 'Package payload must be a regular file' : 'Package path parent must be a directory',
+                path: current,
+            }));
+        }
+        if (final && (metadata.mode & 0o111) !== 0) {
+            throw new DiagnosticError(diagnostic({
+                code: 'package.executable',
+                message: 'Executable package files are not allowed',
+                path: current,
+            }));
+        }
+        if (final && metadata.size > maximumBytes) {
+            throw new DiagnosticError(diagnostic({
+                code: 'package.file-too-large',
+                message: `Package file exceeds ${maximumBytes} bytes`,
+                path: current,
+            }));
+        }
+    }
+    assertInside(root, current, 'Package file');
+    const bytes = await readFile(current);
+    if (bytes.byteLength > maximumBytes) {
+        fail('package.file-too-large', `Package file exceeds ${maximumBytes} bytes`, current);
+    }
+    return bytes;
+}
+export async function readPackageDirectory(directory) {
+    const root = resolve(directory);
+    await assertDirectory(root, 'Plugin package directory');
+    const manifestBytes = await readSafePackageFile(root, 'plugin.json');
+    const integrityBytes = await readSafePackageFile(root, 'integrity.json');
+    const integrity = parseIntegrityManifest(integrityBytes);
+    const files = new Map([
+        ['plugin.json', manifestBytes],
+        ['integrity.json', integrityBytes],
+    ]);
+    for (const item of integrity.files) {
+        if (!files.has(item.path)) {
+            files.set(item.path, await readSafePackageFile(root, item.path));
+        }
+    }
+    const signaturePath = join(root, 'signature.sig');
+    let hasSignature = false;
+    try {
+        await lstat(signaturePath);
+        hasSignature = true;
+    }
+    catch (error) {
+        const cause = error;
+        if (cause.code !== 'ENOENT') {
+            throw new DiagnosticError(diagnostic({
+                code: 'package.signature-inspection-failed',
+                message: 'Unable to inspect development plugin signature.sig',
+                path: signaturePath,
+            }));
+        }
+    }
+    if (hasSignature) {
+        files.set('signature.sig', await readSafePackageFile(root, 'signature.sig', MAX_SIGNATURE_FILE_BYTES));
+    }
+    return files;
+}
+/** Reads every entry in a complete package directory, unlike development import. */
+export async function readCompletePackageDirectory(directory) {
+    const root = resolve(directory);
+    await assertDirectory(root, 'Complete plugin package directory');
+    const files = new Map();
+    const entries = [];
+    let totalBytes = 0;
+    const visit = async (relativeDirectory) => {
+        const current = relativeDirectory === ''
+            ? root
+            : join(root, ...relativeDirectory.split('/'));
+        const names = await readdir(current);
+        names.sort((left, right) => left < right ? -1 : left > right ? 1 : 0);
+        for (const name of names) {
+            const relativePath = relativeDirectory === '' ? name : `${relativeDirectory}/${name}`;
+            const path = join(current, name);
+            const metadata = await lstat(path);
+            if (metadata.isSymbolicLink()) {
+                fail('package.symlink', 'Complete package directories cannot contain symbolic links', path);
+            }
+            const directoryEntry = metadata.isDirectory();
+            if (!directoryEntry && !metadata.isFile()) {
+                fail('package.file-type', 'Complete package directories cannot contain special files', path);
+            }
+            const packagePath = validatePackagePath(relativePath, {
+                directory: directoryEntry,
+                label: relativePath,
+            });
+            entries.push({ path: packagePath, directory: directoryEntry });
+            if (entries.length > MAX_ARCHIVE_ENTRIES) {
+                fail('package.too-many-entries', `Package exceeds the ${MAX_ARCHIVE_ENTRIES}-entry limit`, path);
+            }
+            assertUniquePackagePaths(entries);
+            if (directoryEntry) {
+                await visit(packagePath);
+                continue;
+            }
+            if ((metadata.mode & 0o111) !== 0) {
+                fail('package.executable', 'Executable package files are not allowed', path);
+            }
+            const maximum = packagePath === 'signature.sig'
+                ? MAX_SIGNATURE_FILE_BYTES
+                : MAX_ENTRY_BYTES;
+            if (metadata.size > maximum) {
+                fail('package.file-too-large', `Package file exceeds ${maximum} bytes`, path);
+            }
+            const bytes = await readFile(path);
+            if (bytes.byteLength !== metadata.size || bytes.byteLength > maximum) {
+                fail('package.changed', 'Package file changed while it was being read', path);
+            }
+            totalBytes += bytes.byteLength;
+            if (totalBytes > MAX_UNCOMPRESSED_BYTES) {
+                fail('package.too-large', 'Package exceeds the 50 MiB uncompressed limit', path);
+            }
+            files.set(packagePath, bytes);
+        }
+    };
+    await visit('');
+    return files;
+}

package/dist/lib/path-rules.d.ts

@@ -0,0 +1,23 @@
+export declare const MAX_PACKAGE_PATH_BYTES = 1024;
+export declare const MAX_PACKAGE_SEGMENT_BYTES = 240;
+export declare const MAX_PACKAGE_PATH_DEPTH = 12;
+export interface PackagePathOptions {
+    readonly directory?: boolean;
+    readonly label?: string;
+}
+export interface PackagePathEntry {
+    readonly path: string;
+    readonly directory?: boolean;
+}
+export declare function utf8ByteLength(value: string): number;
+export declare function hasControlCharacter(value: string): boolean;
+export declare function packagePathCollisionKey(path: string): string;
+export declare function isForbiddenPackageFilePath(path: string): boolean;
+/** Validates and returns the canonical forward-slash package path. */
+export declare function validatePackagePath(raw: string, options?: PackagePathOptions): string;
+/**
+ * Enforces exact and case/NFC collision rules as well as the file-as-parent
+ * prohibition used by the desktop host.
+ */
+export declare function assertUniquePackagePaths(entries: readonly PackagePathEntry[]): void;
+export declare function countPackageEntries(filePaths: readonly string[]): number;

package/dist/lib/path-rules.js

@@ -0,0 +1,153 @@
+import { fail } from './diagnostics.js';
+export const MAX_PACKAGE_PATH_BYTES = 1_024;
+export const MAX_PACKAGE_SEGMENT_BYTES = 240;
+export const MAX_PACKAGE_PATH_DEPTH = 12;
+const RESERVED_SEGMENTS = new Set([
+    '.notegen',
+    'node_modules',
+    '.git',
+    '.hg',
+    '.svn',
+    '.cache',
+]);
+const FORBIDDEN_FILE_SUFFIXES = Object.freeze([
+    '.exe', '.dll', '.dylib', '.so', '.node', '.wasm', '.msi', '.dmg', '.pkg',
+    '.deb', '.rpm', '.apk', '.ipa', '.app', '.jar', '.class', '.bat', '.cmd',
+    '.ps1', '.sh', '.map', '.pem', '.p12', '.pfx',
+]);
+const INVALID_PORTABLE_CHARACTERS = /[<>:"|?*]/u;
+const CONTROL_CHARACTER = /\p{Cc}/u;
+export function utf8ByteLength(value) {
+    return Buffer.byteLength(value, 'utf8');
+}
+export function hasControlCharacter(value) {
+    return CONTROL_CHARACTER.test(value);
+}
+function asciiUppercase(value) {
+    return value.replace(/[a-z]/g, (character) => character.toUpperCase());
+}
+function isWindowsReservedName(segment) {
+    const stem = asciiUppercase(segment.replace(/[. ]+$/u, '').split('.')[0] ?? '');
+    return stem === 'CON'
+        || stem === 'PRN'
+        || stem === 'AUX'
+        || stem === 'NUL'
+        || stem === 'CLOCK$'
+        || stem === 'CONIN$'
+        || stem === 'CONOUT$'
+        || /^(?:COM|LPT)(?:[1-9¹²³])$(?![\s\S])/u.test(stem);
+}
+export function packagePathCollisionKey(path) {
+    return path.toLowerCase().normalize('NFC');
+}
+export function isForbiddenPackageFilePath(path) {
+    const lower = path.toLowerCase();
+    return FORBIDDEN_FILE_SUFFIXES.some((suffix) => lower.endsWith(suffix));
+}
+/** Validates and returns the canonical forward-slash package path. */
+export function validatePackagePath(raw, options = {}) {
+    const label = options.label ?? 'package path';
+    const directory = options.directory === true;
+    if (raw.length === 0
+        || raw.startsWith('/')
+        || raw.startsWith('\\')
+        || raw.includes('\\')
+        || hasControlCharacter(raw)) {
+        fail('path.unsafe', `${label} is not a safe relative package path`, label);
+    }
+    let path = raw;
+    if (directory) {
+        if (path.endsWith('/'))
+            path = path.slice(0, -1);
+    }
+    else if (path.endsWith('/')) {
+        fail('path.file-trailing-slash', `${label} is a file path and must not end in /`, label);
+    }
+    if (path.length === 0
+        || utf8ByteLength(path) > MAX_PACKAGE_PATH_BYTES
+        || path.includes('//')) {
+        fail('path.unsafe', `${label} is empty, duplicated, or too long`, label);
+    }
+    const segments = path.split('/');
+    if (segments.length > MAX_PACKAGE_PATH_DEPTH) {
+        fail('path.too-deep', `${label} exceeds the ${MAX_PACKAGE_PATH_DEPTH}-segment nesting limit`, label);
+    }
+    for (const segment of segments) {
+        if (segment.length === 0
+            || utf8ByteLength(segment) > MAX_PACKAGE_SEGMENT_BYTES
+            || segment === '.'
+            || segment === '..'
+            || segment.normalize('NFC') !== segment
+            || segment.endsWith('.')
+            || segment.endsWith(' ')
+            || INVALID_PORTABLE_CHARACTERS.test(segment)
+            || isWindowsReservedName(segment)) {
+            fail('path.non-portable', `${label} contains a non-canonical or non-portable segment`, label);
+        }
+        const lower = segment.toLowerCase();
+        if (RESERVED_SEGMENTS.has(lower)
+            || lower === '.env'
+            || lower.startsWith('.env.')) {
+            fail('path.reserved', `${label} contains a reserved or sensitive segment`, label);
+        }
+    }
+    if (!directory && isForbiddenPackageFilePath(path)) {
+        fail('path.forbidden-file', `${label} has an executable, native, or sensitive suffix`, label);
+    }
+    return path;
+}
+/**
+ * Enforces exact and case/NFC collision rules as well as the file-as-parent
+ * prohibition used by the desktop host.
+ */
+export function assertUniquePackagePaths(entries) {
+    const exact = new Map();
+    const folded = new Map();
+    for (const entry of entries) {
+        const directory = entry.directory === true;
+        const path = validatePackagePath(entry.path, { directory, label: entry.path });
+        if (exact.has(path)) {
+            fail('path.duplicate', `Package contains the path more than once: ${path}`, path);
+        }
+        exact.set(path, directory);
+        // ZIPs need not contain directory entries. Check their implicit parents as
+        // well, otherwise A/x.json and a/y.json pass here but cannot be installed
+        // consistently on case-sensitive and case-insensitive filesystems.
+        const segments = path.split('/');
+        for (let index = 1; index <= segments.length; index += 1) {
+            const expandedPath = segments.slice(0, index).join('/');
+            const collisionKey = packagePathCollisionKey(expandedPath);
+            const previous = folded.get(collisionKey);
+            if (previous !== undefined && previous !== expandedPath) {
+                fail('path.case-collision', `Package paths collide by case or Unicode normalization: ${previous}, ${expandedPath}`, path);
+            }
+            folded.set(collisionKey, expandedPath);
+        }
+    }
+    const files = new Set([...exact.entries()]
+        .filter(([, directory]) => !directory)
+        .map(([path]) => path));
+    for (const [path, directory] of exact) {
+        const segments = path.split('/');
+        for (let index = 1; index < segments.length; index += 1) {
+            const parent = segments.slice(0, index).join('/');
+            if (files.has(parent)) {
+                fail('path.file-as-parent', `Package file is also used as a directory: ${parent}`, path);
+            }
+        }
+        if (directory && files.has(path)) {
+            fail('path.file-directory-collision', `Package path is both a file and directory: ${path}`, path);
+        }
+    }
+}
+export function countPackageEntries(filePaths) {
+    const directories = new Set();
+    for (const raw of filePaths) {
+        const path = validatePackagePath(raw, { label: raw });
+        const segments = path.split('/');
+        for (let index = 1; index < segments.length; index += 1) {
+            directories.add(segments.slice(0, index).join('/'));
+        }
+    }
+    return filePaths.length + directories.size;
+}

package/dist/lib/project.d.ts

@@ -0,0 +1,21 @@
+import type { PluginManifestV1 } from '@notegen/plugin-api';
+import { type ValidatedPluginPackage } from './package.js';
+export interface BuildPluginProjectOptions {
+    readonly directory?: string;
+    readonly apiVersion?: string;
+    readonly appVersion?: string;
+}
+export interface BuiltPluginProject {
+    readonly projectDirectory: string;
+    readonly outputDirectory: string;
+    readonly sourcePath: string;
+    readonly manifest: PluginManifestV1;
+    readonly package: ValidatedPluginPackage;
+}
+export interface ValidatedPluginProjectSource {
+    readonly projectDirectory: string;
+    readonly sourcePath: string;
+    readonly manifest: PluginManifestV1;
+}
+export declare function buildPluginProject(options?: BuildPluginProjectOptions): Promise<BuiltPluginProject>;
+export declare function validatePluginProjectSource(options?: BuildPluginProjectOptions): Promise<ValidatedPluginProjectSource>;

package/dist/lib/project.js

@@ -0,0 +1,209 @@
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { build as esbuild } from 'esbuild';
+import { init, parse } from 'es-module-lexer';
+import { DEVELOPMENT_OUTPUT_DIRECTORY } from './constants.js';
+import { diagnostic, DiagnosticError, fail } from './diagnostics.js';
+import { assertDirectory, assertInside, assertNoSymlinkComponents, assertRegularFile, replaceDirectoryAtomically, writeFileExclusive, } from './files.js';
+import { createIntegrityManifest, serializeIntegrityManifest, } from './integrity.js';
+import { parsePluginManifest } from './manifest.js';
+import { validatePackageFiles } from './package.js';
+import { validatePackagePath } from './path-rules.js';
+import { isJsonObject, parseStrictJson } from './strict-json.js';
+async function readProjectConfiguration(projectDirectory) {
+    const packageJsonPath = join(projectDirectory, 'package.json');
+    let value;
+    try {
+        value = parseStrictJson(await readFile(packageJsonPath), 'package.json');
+    }
+    catch (error) {
+        const cause = error;
+        if (cause.code === 'ENOENT')
+            return { source: 'src/main.ts' };
+        throw error;
+    }
+    if (!isJsonObject(value))
+        fail('project.invalid-package-json', 'package.json must be an object', packageJsonPath);
+    const notegen = value.notegen;
+    if (notegen === undefined)
+        return { source: 'src/main.ts' };
+    if (!isJsonObject(notegen)) {
+        fail('project.invalid-config', 'package.json notegen must be an object', 'package.json#notegen');
+    }
+    const unknown = Object.keys(notegen).find((key) => key !== 'source');
+    if (unknown !== undefined) {
+        fail('project.unknown-config', `Unknown NoteGen project option ${unknown}`, `package.json#notegen.${unknown}`);
+    }
+    if (typeof notegen.source !== 'string') {
+        fail('project.invalid-source', 'package.json notegen.source must be a string', 'package.json#notegen.source');
+    }
+    return {
+        source: validatePackagePath(notegen.source, { label: 'package.json#notegen.source' }),
+    };
+}
+async function readProjectPayloadFile(projectDirectory, packagePath) {
+    const path = resolve(projectDirectory, ...packagePath.split('/'));
+    assertInside(projectDirectory, path, 'Project payload');
+    await assertNoSymlinkComponents(projectDirectory, path, 'Project payload');
+    await assertRegularFile(path, `Plugin payload ${packagePath}`);
+    return readFile(path);
+}
+async function collectUsageFiles(projectDirectory, files) {
+    const names = (await readdir(projectDirectory)).filter(name => /^USAGE(?:\.[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*)?\.md$/.test(name));
+    if (names.length > 50)
+        fail('project.usage-limit', 'At most 50 usage translations are allowed');
+    for (const name of names) {
+        const path = join(projectDirectory, name);
+        await assertNoSymlinkComponents(projectDirectory, path, 'Usage guide');
+        if ((await stat(path)).size > 131_072)
+            fail('project.usage-limit', 'Usage guide exceeds 128 KiB', name);
+        const bytes = await readProjectPayloadFile(projectDirectory, name);
+        if (bytes.length > 131_072)
+            fail('project.usage-limit', 'Usage guide exceeds 128 KiB', name);
+        try {
+            new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+        }
+        catch {
+            fail('project.invalid-usage', 'Usage guide must be UTF-8 Markdown', name);
+        }
+        files.set(name, bytes);
+    }
+}
+function assertSelfContainedModule(source) {
+    const parsed = parse(source);
+    const imports = parsed[0];
+    const exports = parsed[1];
+    if (imports.some((item) => item.type !== 'import-meta')) {
+        fail('build.residual-import', 'Bundled entry still contains a static or dynamic module import', 'dist/main.js', 'Bundle every dependency into the entry; NoteGen does not resolve plugin imports at runtime.');
+    }
+    const names = new Set(exports.flatMap((item) => 'name' in item ? [item.name] : []));
+    if (!names.has('activate')) {
+        fail('build.missing-activate', 'Plugin entry must export a named activate function', 'dist/main.js');
+    }
+}
+async function bundleEntry(sourcePath, entryPath) {
+    let result;
+    try {
+        result = await esbuild({
+            entryPoints: [sourcePath],
+            bundle: true,
+            write: false,
+            format: 'esm',
+            platform: 'neutral',
+            target: ['es2022'],
+            charset: 'utf8',
+            legalComments: 'none',
+            sourcemap: false,
+            treeShaking: true,
+            splitting: false,
+            mainFields: ['module', 'main'],
+            conditions: ['import', 'module', 'default'],
+            outfile: entryPath,
+            logLevel: 'silent',
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'esbuild failed';
+        throw new DiagnosticError(diagnostic({
+            code: 'build.failed',
+            message,
+            path: sourcePath,
+        }));
+    }
+    const javascript = result.outputFiles.filter((file) => file.path.endsWith('.js'));
+    if (result.outputFiles.length !== 1 || javascript.length !== 1) {
+        fail('build.multiple-outputs', 'Plugin build must produce exactly one JavaScript file', sourcePath, 'Inline imported assets or remove loaders that create additional files.');
+    }
+    const bytes = Buffer.from(javascript[0]?.contents ?? new Uint8Array());
+    if (bytes.byteLength === 0)
+        fail('build.empty-entry', 'Plugin entry build is empty', sourcePath);
+    if (bytes.byteLength > 5 * 1_048_576) {
+        fail('build.entry-too-large', 'Plugin entry exceeds the 5 MiB limit', sourcePath);
+    }
+    await init();
+    const decoded = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    assertSelfContainedModule(decoded);
+    return bytes;
+}
+export async function buildPluginProject(options = {}) {
+    const projectDirectory = resolve(options.directory ?? process.cwd());
+    await assertDirectory(projectDirectory, 'Plugin project');
+    const manifestBytes = await readProjectPayloadFile(projectDirectory, 'plugin.json');
+    const manifest = parsePluginManifest(manifestBytes, {
+        ...(options.apiVersion === undefined ? {} : { apiVersion: options.apiVersion }),
+        ...(options.appVersion === undefined ? {} : { appVersion: options.appVersion }),
+    });
+    const configuration = await readProjectConfiguration(projectDirectory);
+    const sourcePath = resolve(projectDirectory, ...configuration.source.split('/'));
+    assertInside(projectDirectory, sourcePath, 'Plugin source');
+    await assertNoSymlinkComponents(projectDirectory, sourcePath, 'Plugin source');
+    await assertRegularFile(sourcePath, 'Plugin source entry');
+    const entry = validatePackagePath(manifest.entry, { label: '$.entry' });
+    const bundle = await bundleEntry(sourcePath, entry);
+    const files = new Map([
+        ['plugin.json', manifestBytes],
+        [entry, bundle],
+    ]);
+    for (const localePath of Object.values(manifest.locales ?? {})) {
+        if (!files.has(localePath)) {
+            files.set(localePath, await readProjectPayloadFile(projectDirectory, localePath));
+        }
+    }
+    await collectUsageFiles(projectDirectory, files);
+    const integrity = createIntegrityManifest(files);
+    files.set('integrity.json', Buffer.from(serializeIntegrityManifest(integrity), 'utf8'));
+    const validated = validatePackageFiles(files, {
+        ...(options.apiVersion === undefined ? {} : { apiVersion: options.apiVersion }),
+        ...(options.appVersion === undefined ? {} : { appVersion: options.appVersion }),
+    });
+    const outputDirectory = join(projectDirectory, DEVELOPMENT_OUTPUT_DIRECTORY);
+    assertInside(projectDirectory, outputDirectory, 'Development output');
+    await assertNoSymlinkComponents(projectDirectory, outputDirectory, 'Development output');
+    await replaceDirectoryAtomically(outputDirectory, async (temporary) => {
+        for (const [path, bytes] of files) {
+            await writeFileExclusive(join(temporary, ...path.split('/')), bytes, 0o644);
+        }
+    });
+    return Object.freeze({
+        projectDirectory,
+        outputDirectory,
+        sourcePath,
+        manifest,
+        package: validated,
+    });
+}
+export async function validatePluginProjectSource(options = {}) {
+    const projectDirectory = resolve(options.directory ?? process.cwd());
+    await assertDirectory(projectDirectory, 'Plugin project');
+    const manifestBytes = await readProjectPayloadFile(projectDirectory, 'plugin.json');
+    const manifest = parsePluginManifest(manifestBytes, {
+        ...(options.apiVersion === undefined ? {} : { apiVersion: options.apiVersion }),
+        ...(options.appVersion === undefined ? {} : { appVersion: options.appVersion }),
+    });
+    const configuration = await readProjectConfiguration(projectDirectory);
+    const sourcePath = resolve(projectDirectory, ...configuration.source.split('/'));
+    assertInside(projectDirectory, sourcePath, 'Plugin source');
+    await assertNoSymlinkComponents(projectDirectory, sourcePath, 'Plugin source');
+    await assertRegularFile(sourcePath, 'Plugin source entry');
+    // Source preflight cannot require the configured built entry yet. Supply a
+    // harmless placeholder for that one package file so the authoritative
+    // manifest validator can still parse locale payloads and verify that the
+    // default locale covers every contribution reference.
+    const sourceValidationFiles = new Map([
+        [manifest.entry, Buffer.from('// source-project preflight placeholder\n', 'utf8')],
+    ]);
+    for (const localePath of Object.values(manifest.locales ?? {})) {
+        sourceValidationFiles.set(localePath, await readProjectPayloadFile(projectDirectory, localePath));
+    }
+    await collectUsageFiles(projectDirectory, sourceValidationFiles);
+    const validatedManifest = parsePluginManifest(manifestBytes, {
+        files: sourceValidationFiles,
+        ...(options.apiVersion === undefined ? {} : { apiVersion: options.apiVersion }),
+        ...(options.appVersion === undefined ? {} : { appVersion: options.appVersion }),
+    });
+    return Object.freeze({
+        projectDirectory,
+        sourcePath,
+        manifest: validatedManifest,
+    });
+}

package/dist/lib/scaffold.d.ts

@@ -0,0 +1,22 @@
+export type PluginTemplate = 'command' | 'editor-statistics';
+export type PackageManager = 'pnpm' | 'npm';
+export interface CreatePluginProjectOptions {
+    readonly directory: string;
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly template?: PluginTemplate;
+    readonly minAppVersion?: string;
+    readonly apiVersion?: string;
+    readonly packageManager?: PackageManager;
+    readonly install?: boolean;
+    /** Receives package-manager stdout and stderr; defaults to inherited stdio. */
+    readonly installOutput?: Pick<NodeJS.WritableStream, 'write'>;
+}
+export interface CreatedPluginProject {
+    readonly directory: string;
+    readonly files: readonly string[];
+    readonly packageManager: PackageManager;
+    readonly installed: boolean;
+}
+export declare function createPluginProject(options: CreatePluginProjectOptions): Promise<CreatedPluginProject>;