@notegen/plugin-cli 0.1.0

package/dist/cli.js

@@ -0,0 +1,398 @@
+import { basename } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { Command, CommanderError, Option } from 'commander';
+import { EXIT_PROJECT_FAILURE, EXIT_SUCCESS, EXIT_UNSAFE_REFUSAL, EXIT_UNEXPECTED, EXIT_USAGE, } from './lib/constants.js';
+import { diagnostic, diagnosticsFromError, fail, formatDiagnostic, isDiagnosticError, } from './lib/diagnostics.js';
+import { createPluginProject, } from './lib/scaffold.js';
+import { buildPluginProject } from './lib/project.js';
+import { watchPluginProject } from './lib/watch.js';
+import { generatePublisherKeys, packPluginProject, signPluginArchive, validatePluginTarget, } from './lib/tasks.js';
+export const PLUGIN_CLI_VERSION = '0.1.0';
+function writeLine(stream, value = '') {
+    stream.write(`${value}\n`);
+}
+function printJson(io, value) {
+    writeLine(io.stdout, JSON.stringify(value, null, 2));
+}
+function isUnsafeRefusal(error) {
+    if (!isDiagnosticError(error))
+        return false;
+    const refusalCodes = new Set([
+        'create.target_invalid',
+        'create.target_not_empty',
+        'file.exists',
+        'file.not_regular',
+        'key.output-exists',
+        'key.same-output',
+        'output.unsafe',
+        'path.outside_project',
+        'path.symlink',
+        'sign.same-output',
+    ]);
+    return error.diagnostics.some((item) => refusalCodes.has(item.code));
+}
+function titleFromDirectory(directory) {
+    const name = basename(directory).replace(/[-_]+/g, ' ').trim();
+    return name.length === 0
+        ? 'NoteGen Plugin'
+        : name.replace(/\b[a-z]/g, (letter) => letter.toUpperCase());
+}
+async function completeCreateOptions(directory, options) {
+    if (options.id && options.name)
+        return { id: options.id, name: options.name };
+    if (options.yes || options.json) {
+        if (!options.id) {
+            fail('create.id-required', '--id is required when --yes or --json disables interactive prompts');
+        }
+        return { id: options.id, name: options.name ?? titleFromDirectory(directory) };
+    }
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        fail('create.non-interactive', 'Missing --id or --name in a non-interactive terminal');
+    }
+    const prompt = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const id = options.id ?? (await prompt.question('Plugin ID (for example com.example.my-plugin): ')).trim();
+        const fallbackName = titleFromDirectory(directory);
+        const nameInput = options.name ?? (await prompt.question(`Plugin name (${fallbackName}): `)).trim();
+        return { id, name: nameInput || fallbackName };
+    }
+    finally {
+        prompt.close();
+    }
+}
+function readPassphrase(environmentVariable) {
+    if (environmentVariable === undefined)
+        return undefined;
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$(?![\s\S])/u.test(environmentVariable)) {
+        fail('key.invalid-environment-variable', '--passphrase-env must name a valid environment variable');
+    }
+    const value = process.env[environmentVariable];
+    if (!value) {
+        fail('key.missing-passphrase', `Environment variable ${environmentVariable} is empty or unavailable`);
+    }
+    return value;
+}
+function addCompatibilityOptions(command) {
+    return command
+        .option('--api-version <version>', 'validate against a concrete NoteGen plugin API version')
+        .option('--app-version <version>', 'validate against a concrete NoteGen app version');
+}
+function addJsonOption(command) {
+    return command.option('--json', 'write a machine-readable JSON result');
+}
+function hasJsonOption(argv) {
+    const arguments_ = argv.slice(2);
+    const optionTerminator = arguments_.indexOf('--');
+    const options = optionTerminator === -1
+        ? arguments_
+        : arguments_.slice(0, optionTerminator);
+    return options.includes('--json');
+}
+function appCompatibilityStatus(appVersion) {
+    return appVersion === undefined
+        ? {
+            appCompatibilityChecked: false,
+            appCompatibilityNote: 'NoteGen app compatibility was not checked; pass --app-version to check minAppVersion.',
+        }
+        : {
+            appCompatibilityChecked: true,
+            appCompatibilityNote: `Compatibility checked against NoteGen ${appVersion}.`,
+        };
+}
+export function createCliProgram(io = { stdout: process.stdout, stderr: process.stderr }, options = {}) {
+    const program = new Command()
+        .name('notegen-plugin')
+        .description('Create, build, validate, package, sign, and verify NoteGen plugins.')
+        .version(PLUGIN_CLI_VERSION)
+        .exitOverride()
+        .configureOutput({
+        writeOut: (value) => {
+            if (options.jsonMode)
+                options.commanderOutput?.push(value);
+            else
+                io.stdout.write(value);
+        },
+        writeErr: (value) => {
+            if (!options.jsonMode)
+                io.stderr.write(value);
+        },
+    });
+    if (!options.jsonMode)
+        program.showHelpAfterError();
+    const createCommand = addJsonOption(program.command('create <directory>')
+        .description('create a new NoteGen plugin project')
+        .option('--id <plugin-id>', 'reverse-domain plugin ID')
+        .option('--name <name>', 'display name')
+        .option('--description <description>', 'short plugin description')
+        .addOption(new Option('--template <template>', 'starter template')
+        .choices(['command', 'editor-statistics'])
+        .default('command'))
+        .option('--min-app-version <version>', 'minimum NoteGen version', '0.37.0')
+        .option('--api-version <range>', 'supported plugin API range', '^0.1.0')
+        .addOption(new Option('--package-manager <manager>', 'generated project package manager')
+        .choices(['pnpm', 'npm'])
+        .default('pnpm'))
+        .option('--install', 'install generated project dependencies')
+        .option('--yes', 'disable prompts; --id is required'));
+    createCommand.action(async (directory) => {
+        const options = createCommand.opts();
+        const identity = await completeCreateOptions(directory, options);
+        const created = await createPluginProject({
+            directory,
+            ...identity,
+            ...(options.description === undefined ? {} : { description: options.description }),
+            template: options.template,
+            minAppVersion: options.minAppVersion,
+            apiVersion: options.apiVersion,
+            packageManager: options.packageManager,
+            install: options.install,
+            ...(options.json ? { installOutput: io.stderr } : {}),
+        });
+        if (options.json) {
+            printJson(io, { ok: true, command: 'create', ...created });
+            return;
+        }
+        writeLine(io.stdout, `Created NoteGen plugin project at ${created.directory}`);
+        writeLine(io.stdout, created.installed
+            ? `Dependencies installed with ${created.packageManager}.`
+            : `Run ${created.packageManager} install before building.`);
+    });
+    const validateCommand = addJsonOption(addCompatibilityOptions(program.command('validate [path]')
+        .description('validate a source project, development directory, or plugin archive')
+        .option('--public-key <file>', 'publisher public-key JSON or raw Base64 file')
+        .option('--require-signature', 'reject unsigned packages')));
+    validateCommand.action(async (path) => {
+        const options = validateCommand.opts();
+        const result = await validatePluginTarget({
+            ...(path === undefined ? {} : { target: path }),
+            ...(options.apiVersion === undefined ? {} : { apiVersion: options.apiVersion }),
+            ...(options.appVersion === undefined ? {} : { appVersion: options.appVersion }),
+            ...(options.publicKey === undefined ? {} : { publicKeyPath: options.publicKey }),
+            ...(options.requireSignature === undefined ? {} : { requireSignature: options.requireSignature }),
+        });
+        if (options.json) {
+            printJson(io, { ok: true, command: 'validate', ...result });
+            return;
+        }
+        writeLine(io.stdout, `Valid ${result.kind}: ${result.manifest.id}@${result.manifest.version}`);
+        writeLine(io.stdout, result.appCompatibilityNote);
+        if (result.signed) {
+            writeLine(io.stdout, result.signatureVerified
+                ? 'Publisher signature verified.'
+                : 'Signature is structurally valid; pass --public-key to verify its identity.');
+        }
+    });
+    const devCommand = addJsonOption(addCompatibilityOptions(program.command('dev [directory]')
+        .description('watch source changes and atomically replace the development package after successful builds')));
+    devCommand.action(async (directory) => {
+        const options = devCommand.opts();
+        const controller = new AbortController();
+        const stop = () => controller.abort();
+        process.once('SIGINT', stop);
+        process.once('SIGTERM', stop);
+        try {
+            await watchPluginProject({
+                ...(directory === undefined ? {} : { directory }),
+                ...(options.apiVersion === undefined ? {} : { apiVersion: options.apiVersion }),
+                ...(options.appVersion === undefined ? {} : { appVersion: options.appVersion }),
+                signal: controller.signal,
+                onBuilt: built => {
+                    const result = { ok: true, command: 'dev', pluginId: built.manifest.id, outputDirectory: built.outputDirectory };
+                    if (options.json)
+                        printJson(io, result);
+                    else
+                        writeLine(io.stdout, `Built ${built.manifest.id}. Watching source changes. Import and enable auto-reload for: ${built.outputDirectory}`);
+                },
+                onError: error => {
+                    const message = error instanceof Error ? error.message : String(error);
+                    if (options.json)
+                        printJson(io, { ok: false, command: 'dev', message });
+                    else
+                        writeLine(io.stderr, `${message}\nBuild did not finish cleanly; waiting for source changes. See the diagnostic for output recovery details.`);
+                },
+            });
+        }
+        finally {
+            process.removeListener('SIGINT', stop);
+            process.removeListener('SIGTERM', stop);
+        }
+    });
+    const buildCommand = addJsonOption(addCompatibilityOptions(program.command('build [directory]')
+        .description('bundle a plugin into an importable development directory')));
+    buildCommand.action(async (directory) => {
+        const options = buildCommand.opts();
+        const built = await buildPluginProject({
+            ...(directory === undefined ? {} : { directory }),
+            ...(options.apiVersion === undefined ? {} : { apiVersion: options.apiVersion }),
+            ...(options.appVersion === undefined ? {} : { appVersion: options.appVersion }),
+        });
+        const result = {
+            ok: true,
+            command: 'build',
+            pluginId: built.manifest.id,
+            version: built.manifest.version,
+            outputDirectory: built.outputDirectory,
+            ...appCompatibilityStatus(options.appVersion),
+        };
+        if (options.json)
+            printJson(io, result);
+        else {
+            writeLine(io.stdout, `Built ${result.pluginId}@${result.version}`);
+            writeLine(io.stdout, `Development import directory: ${result.outputDirectory}`);
+            writeLine(io.stdout, result.appCompatibilityNote);
+        }
+    });
+    const packCommand = addJsonOption(addCompatibilityOptions(program.command('pack [directory]')
+        .description('build and create an unsigned .notegen-plugin archive')
+        .option('--output <file>', 'unsigned archive output path')
+        .option('--force', 'overwrite an existing output archive')));
+    packCommand.action(async (directory) => {
+        const options = packCommand.opts();
+        const result = await packPluginProject({
+            ...(directory === undefined ? {} : { directory }),
+            ...(options.output === undefined ? {} : { output: options.output }),
+            ...(options.apiVersion === undefined ? {} : { apiVersion: options.apiVersion }),
+            ...(options.appVersion === undefined ? {} : { appVersion: options.appVersion }),
+            force: options.force,
+        });
+        const compatibility = appCompatibilityStatus(options.appVersion);
+        if (options.json)
+            printJson(io, { ok: true, command: 'pack', ...result, ...compatibility });
+        else {
+            writeLine(io.stdout, `Packed unsigned ${result.pluginId}@${result.version}`);
+            writeLine(io.stdout, `${result.path} (${result.sha256})`);
+            writeLine(io.stdout, 'Signing is a separate step; no private key was accessed.');
+            writeLine(io.stdout, compatibility.appCompatibilityNote);
+        }
+    });
+    const keygenCommand = addJsonOption(program.command('keygen')
+        .description('generate an Ed25519 publisher key pair')
+        .option('--output <directory>', 'key output directory (default: .notegen/keys)')
+        .option('--private-key <file>', 'private-key PEM output path')
+        .option('--public-key <file>', 'public-key JSON output path')
+        .option('--passphrase-env <name>', 'encrypt the private key using this environment variable')
+        .option('--force', 'overwrite both existing key files'));
+    keygenCommand.action(async () => {
+        const options = keygenCommand.opts();
+        const passphrase = readPassphrase(options.passphraseEnv);
+        const result = await generatePublisherKeys({
+            ...(options.output === undefined ? {} : { directory: options.output }),
+            ...(options.privateKey === undefined ? {} : { privateKeyPath: options.privateKey }),
+            ...(options.publicKey === undefined ? {} : { publicKeyPath: options.publicKey }),
+            ...(passphrase === undefined ? {} : { passphrase }),
+            force: options.force,
+        });
+        if (options.json)
+            printJson(io, { ok: true, command: 'keygen', ...result });
+        else {
+            writeLine(io.stdout, `Generated publisher key ${result.keyId}`);
+            writeLine(io.stdout, `Private key: ${result.privateKeyPath}`);
+            writeLine(io.stdout, `Public key: ${result.publicKeyPath}`);
+            writeLine(io.stdout, 'The private key contents were not printed. Keep that file offline.');
+        }
+    });
+    const signCommand = addJsonOption(addCompatibilityOptions(program.command('sign <unsigned-archive>')
+        .description('sign an already-built unsigned archive without executing or compiling it')
+        .requiredOption('--private-key <file>', 'publisher PKCS#8 PEM private key')
+        .option('--output <file>', 'signed archive output path')
+        .option('--passphrase-env <name>', 'read the private-key passphrase from this environment variable')
+        .option('--force', 'overwrite an existing signed archive')));
+    signCommand.action(async (archive) => {
+        const options = signCommand.opts();
+        const passphrase = readPassphrase(options.passphraseEnv);
+        const result = await signPluginArchive({
+            archive,
+            privateKeyPath: options.privateKey,
+            ...(options.output === undefined ? {} : { output: options.output }),
+            ...(passphrase === undefined ? {} : { passphrase }),
+            ...(options.apiVersion === undefined ? {} : { apiVersion: options.apiVersion }),
+            ...(options.appVersion === undefined ? {} : { appVersion: options.appVersion }),
+            force: options.force,
+        });
+        const compatibility = appCompatibilityStatus(options.appVersion);
+        if (options.json)
+            printJson(io, { ok: true, command: 'sign', ...result, ...compatibility });
+        else {
+            writeLine(io.stdout, `Signed ${result.pluginId}@${result.version} with ${result.keyId}`);
+            writeLine(io.stdout, `${result.path} (${result.sha256})`);
+            writeLine(io.stdout, compatibility.appCompatibilityNote);
+        }
+    });
+    const verifyCommand = addJsonOption(addCompatibilityOptions(program.command('verify <path>')
+        .description('verify a complete package directory or archive without executing plugin code')
+        .option('--public-key <file>', 'publisher public-key JSON or raw Base64 file')
+        .option('--require-signature', 'reject unsigned development packages')));
+    verifyCommand.action(async (path) => {
+        const options = verifyCommand.opts();
+        const result = await validatePluginTarget({
+            target: path,
+            completeDirectory: true,
+            ...(options.apiVersion === undefined ? {} : { apiVersion: options.apiVersion }),
+            ...(options.appVersion === undefined ? {} : { appVersion: options.appVersion }),
+            ...(options.publicKey === undefined ? {} : { publicKeyPath: options.publicKey }),
+            ...(options.requireSignature === undefined ? {} : { requireSignature: options.requireSignature }),
+        });
+        if (result.kind === 'project') {
+            fail('verify.incomplete-project', 'verify requires a built directory or archive; run build first', result.target);
+        }
+        if (options.json)
+            printJson(io, { ok: true, command: 'verify', ...result });
+        else {
+            writeLine(io.stdout, `Verified ${result.manifest.id}@${result.manifest.version}`);
+            writeLine(io.stdout, result.appCompatibilityNote);
+            writeLine(io.stdout, result.signed
+                ? result.signatureVerified
+                    ? 'Integrity and publisher signature are valid.'
+                    : 'Integrity and signature encoding are valid; publisher identity was not checked.'
+                : 'Integrity is valid; this development package is unsigned.');
+        }
+    });
+    return program;
+}
+export async function runCli(argv = process.argv, io = { stdout: process.stdout, stderr: process.stderr }) {
+    const jsonMode = hasJsonOption(argv);
+    const commanderOutput = [];
+    const program = createCliProgram(io, { jsonMode, commanderOutput });
+    try {
+        await program.parseAsync([...argv], { from: 'node' });
+        return EXIT_SUCCESS;
+    }
+    catch (error) {
+        if (error instanceof CommanderError) {
+            if (error.exitCode === 0) {
+                if (jsonMode) {
+                    printJson(io, {
+                        ok: true,
+                        command: error.code === 'commander.version' ? 'version' : 'help',
+                        output: commanderOutput.join('').trimEnd(),
+                    });
+                }
+                return EXIT_SUCCESS;
+            }
+            if (jsonMode) {
+                printJson(io, {
+                    ok: false,
+                    diagnostics: [diagnostic({
+                            code: 'cli.usage',
+                            message: error.message.replace(/^error:\s*/u, ''),
+                        })],
+                });
+            }
+            return EXIT_USAGE;
+        }
+        const diagnostics = diagnosticsFromError(error);
+        if (jsonMode)
+            printJson(io, { ok: false, diagnostics });
+        else
+            for (const item of diagnostics)
+                writeLine(io.stderr, formatDiagnostic(item));
+        if (isDiagnosticError(error)) {
+            return isUnsafeRefusal(error) ? EXIT_UNSAFE_REFUSAL : EXIT_PROJECT_FAILURE;
+        }
+        return EXIT_UNEXPECTED;
+    }
+}
+export async function runCreateCli(argv = process.argv, io = { stdout: process.stdout, stderr: process.stderr }) {
+    const forwarded = [argv[0] ?? 'node', argv[1] ?? 'create-notegen-plugin', 'create', ...argv.slice(2)];
+    return runCli(forwarded, io);
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export * from './cli.js';
+export * from './lib/archive.js';
+export { DEVELOPMENT_OUTPUT_DIRECTORY, EXIT_INTERRUPTED, EXIT_PROJECT_FAILURE, EXIT_SUCCESS, EXIT_UNEXPECTED, EXIT_UNSAFE_REFUSAL, EXIT_USAGE, PACKAGE_EXTENSION, RELEASE_OUTPUT_DIRECTORY, UNSIGNED_PACKAGE_EXTENSION, } from './lib/constants.js';
+export * from './lib/diagnostics.js';
+export * from './lib/integrity.js';
+export * from './lib/manifest.js';
+export * from './lib/package.js';
+export * from './lib/path-rules.js';
+export * from './lib/project.js';
+export * from './lib/scaffold.js';
+export * from './lib/signing.js';
+export * from './lib/tasks.js';
+export * from './lib/watch.js';

package/dist/index.js

@@ -0,0 +1,13 @@
+export * from './cli.js';
+export * from './lib/archive.js';
+export { DEVELOPMENT_OUTPUT_DIRECTORY, EXIT_INTERRUPTED, EXIT_PROJECT_FAILURE, EXIT_SUCCESS, EXIT_UNEXPECTED, EXIT_UNSAFE_REFUSAL, EXIT_USAGE, PACKAGE_EXTENSION, RELEASE_OUTPUT_DIRECTORY, UNSIGNED_PACKAGE_EXTENSION, } from './lib/constants.js';
+export * from './lib/diagnostics.js';
+export * from './lib/integrity.js';
+export * from './lib/manifest.js';
+export * from './lib/package.js';
+export * from './lib/path-rules.js';
+export * from './lib/project.js';
+export * from './lib/scaffold.js';
+export * from './lib/signing.js';
+export * from './lib/tasks.js';
+export * from './lib/watch.js';

package/dist/lib/archive.d.ts

@@ -0,0 +1,17 @@
+export interface PackageFile {
+    readonly path: string;
+    readonly bytes: Uint8Array;
+}
+export interface PackageArchive {
+    readonly files: ReadonlyMap<string, Buffer>;
+    readonly sha256: string;
+    readonly size: number;
+}
+export declare function readPackageArchive(path: string): Promise<PackageArchive>;
+export declare function writePackageArchive(input: Iterable<PackageFile>, outputPath: string, options?: {
+    readonly force?: boolean;
+}): Promise<{
+    readonly path: string;
+    readonly sha256: string;
+    readonly size: number;
+}>;