@poetora/cli 0.0.1 → 0.1.2

package/.turbo/turbo-build.log

@@ -0,0 +1,4 @@
+
+> @poetora/cli@0.1.1 build /home/runner/work/poetora/poetora/packages/cli
+> tsc --project tsconfig.build.json
+

package/LICENSE

@@ -0,0 +1,93 @@
+Copyright (c) 2025 Poetora
+
+Elastic License 2.0
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor’s trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+_As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim._
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/bin/accessibility.js

@@ -87,8 +87,8 @@ export function checkDocsColors(colors, background, navigation) {
         darkOnLightContrast,
         ...anchorResults.flatMap((anchor) => [anchor.lightContrast, anchor.darkContrast]),
     ].filter(Boolean);
-    const hasFailure = results.some((result) => result.recommendation === 'fail');
-    const hasWarning = results.some((result) => result.recommendation === 'warning');
+    const hasFailure = results.some((result) => result?.recommendation === 'fail');
+    const hasWarning = results.some((result) => result?.recommendation === 'warning');
     let overallScore;
     if (hasFailure) {
         overallScore = 'fail';

package/bin/cli-builder.d.ts

@@ -0,0 +1,8 @@
+import type { Argv } from 'yargs';
+export declare class CliBuilder {
+    private readonly packageName;
+    private logger;
+    constructor(packageName?: string);
+    build(): Argv;
+    run(): Promise<void>;
+}

package/bin/cli-builder.js

@@ -0,0 +1,178 @@
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import { CheckCommand, DevCommand, InitCommand, LinkCommand, UpdateCommand, } from './commands/index.js';
+import { AccessibilityCheckService, LinkService, OpenApiCheckService, PortService, TemplateService, UpdateService, VersionService, } from './services/index.js';
+import { ConsoleLogger } from './utils/index.js';
+export class CliBuilder {
+    packageName;
+    logger;
+    constructor(packageName = 'poet') {
+        this.packageName = packageName;
+        this.logger = new ConsoleLogger();
+    }
+    build() {
+        const versionService = new VersionService(this.packageName);
+        const portService = new PortService(this.logger);
+        const templateService = new TemplateService();
+        const openApiCheckService = new OpenApiCheckService(this.logger);
+        const accessibilityCheckService = new AccessibilityCheckService();
+        const linkService = new LinkService(this.logger);
+        const updateService = new UpdateService(this.logger, versionService, this.packageName);
+        const devCommand = new DevCommand(this.logger, versionService, portService, this.packageName);
+        const initCommand = new InitCommand(this.logger, templateService, this.packageName);
+        const checkCommand = new CheckCommand(this.logger, openApiCheckService, accessibilityCheckService, this.packageName);
+        const linkCommand = new LinkCommand(this.logger, linkService, this.packageName);
+        const updateCommand = new UpdateCommand(this.logger, updateService, this.packageName);
+        return (yargs(hideBin(process.argv))
+            .scriptName(this.packageName)
+            .command('dev', 'initialize a local preview environment', (yargs) => yargs
+            .option('port', {
+            type: 'number',
+            description: 'port to run the preview server on',
+            default: 3000,
+        })
+            .option('open', {
+            type: 'boolean',
+            default: true,
+            description: 'open a local preview in the browser',
+        })
+            .option('local-schema', {
+            type: 'boolean',
+            default: false,
+            hidden: true,
+            description: 'use a locally hosted schema file (note: only https protocol is supported in production)',
+        })
+            .option('client-version', {
+            type: 'string',
+            hidden: true,
+            description: 'the version of the client to use for cli testing',
+        })
+            .option('groups', {
+            type: 'array',
+            description: 'Mock user groups for local development and testing',
+            example: '--groups admin user',
+        })
+            .option('disable-openapi', {
+            type: 'boolean',
+            default: false,
+            description: 'Disable OpenAPI file generation',
+        }), async (argv) => {
+            try {
+                await devCommand.run(argv);
+            }
+            catch (error) {
+                this.logger.error(error instanceof Error ? error.message : 'Unknown error');
+                process.exit(1);
+            }
+        })
+            .command(['new [directory]', 'init [directory]'], 'Create a new Poetora documentation site', (yargs) => yargs.positional('directory', {
+            describe: 'The directory to initialize your documentation',
+            type: 'string',
+            default: '.',
+        }), async (argv) => {
+            try {
+                await initCommand.run({ directory: argv.directory });
+            }
+            catch (error) {
+                this.logger.error(error instanceof Error ? error.message : 'Unknown error');
+                process.exit(1);
+            }
+        })
+            .command('openapi-check <filename>', 'check if an OpenAPI spec is valid', (yargs) => yargs
+            .positional('filename', {
+            describe: 'the filename of the OpenAPI spec (e.g. ./openapi.yaml) or the URL to the OpenAPI spec',
+            type: 'string',
+            demandOption: true,
+        })
+            .option('local-schema', {
+            type: 'boolean',
+            default: false,
+            description: 'use a locally hosted schema file (note: only https protocol is supported in production)',
+        }), async (argv) => {
+            try {
+                await checkCommand.checkOpenApi({
+                    filename: argv.filename,
+                    localSchema: argv.localSchema,
+                });
+                process.exit(0);
+            }
+            catch (error) {
+                this.logger.error(error instanceof Error ? error.message : 'Unknown error');
+                process.exit(1);
+            }
+        })
+            .command(['a11y', 'accessibility-check', 'a11y-check', 'accessibility'], 'check for accessibility issues in documentation', () => undefined, async () => {
+            try {
+                const exitCode = await checkCommand.checkAccessibility();
+                process.exit(exitCode);
+            }
+            catch (error) {
+                this.logger.error(error instanceof Error ? error.message : 'Unknown error');
+                process.exit(1);
+            }
+        })
+            .command('broken-links', 'check for invalid internal links', () => undefined, async () => {
+            try {
+                const brokenLinks = await linkCommand.checkBrokenLinks();
+                const hasBrokenLinks = Object.keys(brokenLinks).length > 0;
+                process.exit(hasBrokenLinks ? 1 : 0);
+            }
+            catch (error) {
+                this.logger.error(error instanceof Error ? error.message : 'Unknown error');
+                process.exit(1);
+            }
+        })
+            .command('rename <from> <to>', 'rename a file and update all internal link references', (yargs) => yargs
+            .positional('from', {
+            describe: 'the file to rename',
+            type: 'string',
+        })
+            .positional('to', {
+            describe: 'the new name for the file',
+            type: 'string',
+        })
+            .demandOption(['from', 'to'])
+            .option('force', {
+            type: 'boolean',
+            default: false,
+            description: 'rename files and skip errors',
+        })
+            .epilog(`example: \`${this.packageName} rename introduction.mdx overview.mdx\``), async (argv) => {
+            try {
+                await linkCommand.renameFile({
+                    from: argv.from,
+                    to: argv.to,
+                    force: argv.force,
+                });
+                process.exit(0);
+            }
+            catch (error) {
+                this.logger.error(error instanceof Error ? error.message : 'Unknown error');
+                process.exit(1);
+            }
+        })
+            .command('update', 'update the CLI to the latest version', () => undefined, async () => {
+            try {
+                await updateCommand.run({});
+                process.exit(0);
+            }
+            catch (error) {
+                this.logger.error(error instanceof Error ? error.message : 'Unknown error');
+                process.exit(1);
+            }
+        })
+            .command(['version', 'v'], 'display the current version of the CLI and client', () => undefined, async () => {
+            const versions = versionService.getVersions();
+            this.logger.log(`cli version: ${versions.cli}`);
+            this.logger.log(`client version: ${versions.client}`);
+            process.exit(0);
+        })
+            .strictCommands()
+            .demandCommand(1, 'unknown command. see above for the list of supported commands.')
+            .alias('h', 'help')
+            .alias('v', 'version'));
+    }
+    async run() {
+        await this.build().parseAsync();
+    }
+}

package/bin/cli.d.ts

@@ -1,11 +1,5 @@
-export declare const cli: ({ packageName }: {
-    packageName?: string;
-}) => {
-    [x: string]: unknown;
-    _: (string | number)[];
-    $0: string;
-} | Promise<{
-    [x: string]: unknown;
-    _: (string | number)[];
-    $0: string;
-}>;
+#!/usr/bin/env node
+export interface CliOptions {
+    packageName: string;
+}
+export declare const cli: (options: CliOptions) => void;

package/bin/cli.js

@@ -1,201 +1,9 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { getBrokenInternalLinks, renameFilesAndUpdateLinksInContent } from '@poetora/link-rot';
-import { addLog, dev, ErrorLog, SpinnerLog, SuccessLog, Logs, clearLogs, BrokenLinksLog, WarningLog, } from '@poetora/previewing';
-import { validate, getOpenApiDocumentFromUrl, isAllowedLocalSchemaUrl } from '@poetora/shared';
-import { render, Text } from 'ink';
-import path from 'path';
-import yargs from 'yargs';
-import { hideBin } from 'yargs/helpers';
-import { accessibilityCheck } from './accessibilityCheck.js';
-import { checkPort, checkNodeVersion, getVersions, suppressConsoleWarnings, terminate, readLocalOpenApiFile, } from './helpers.js';
-import { init } from './init.js';
-import { mdxLinter } from './mdxLinter.js';
-import { update } from './update.js';
-export const cli = ({ packageName = 'poet' }) => {
-    render(_jsx(Logs, {}));
-    return (yargs(hideBin(process.argv))
-        .scriptName(packageName)
-        .middleware(checkNodeVersion)
-        .middleware(suppressConsoleWarnings)
-        .command('dev', 'initialize a local preview environment', (yargs) => yargs
-        .option('open', {
-        type: 'boolean',
-        default: true,
-        description: 'open a local preview in the browser',
-    })
-        .option('local-schema', {
-        type: 'boolean',
-        default: false,
-        hidden: true,
-        description: 'use a locally hosted schema file (note: only https protocol is supported in production)',
-    })
-        .option('client-version', {
-        type: 'string',
-        hidden: true,
-        description: 'the version of the client to use for cli testing',
-    })
-        .option('groups', {
-        type: 'array',
-        description: 'Mock user groups for local development and testing',
-        example: '--groups admin user',
-    })
-        .option('disable-openapi', {
-        type: 'boolean',
-        default: false,
-        description: 'Disable OpenAPI file generation',
-    })
-        .usage('usage: poetora dev [options]')
-        .example('poetora dev', 'run with default settings (opens in browser)')
-        .example('poetora dev --no-open', 'run without opening in browser'), async (argv) => {
-        let nodeVersionString = process.version;
-        if (nodeVersionString.charAt(0) === 'v') {
-            nodeVersionString = nodeVersionString.slice(1);
-        }
-        const versionArr = nodeVersionString.split('.');
-        const majorVersion = parseInt(versionArr[0], 10);
-        const minorVersion = parseInt(versionArr[1], 10);
-        if (majorVersion >= 25) {
-            addLog(_jsx(ErrorLog, { message: "poet dev is not supported on node versions 25+. Please downgrade to an LTS node version." }));
-            await terminate(1);
-        }
-        if (majorVersion < 20 || (majorVersion === 20 && minorVersion < 17)) {
-            addLog(_jsx(ErrorLog, { message: "poet dev is not supported on node versions below 20.17 Please upgrade to an LTS node version." }));
-            await terminate(1);
-        }
-        const port = await checkPort(argv);
-        const { cli: cliVersion } = getVersions();
-        if (port != undefined) {
-            await dev({
-                ...argv,
-                port,
-                packageName,
-                cliVersion,
-            });
-        }
-        else {
-            addLog(_jsx(ErrorLog, { message: "no available port found" }));
-            await terminate(1);
-        }
-    })
-        .command('openapi-check <filename>', 'check if an OpenAPI spec is valid', (yargs) => yargs
-        .positional('filename', {
-        describe: 'the filename of the OpenAPI spec (e.g. ./openapi.yaml) or the URL to the OpenAPI spec (e.g. https://petstore3.swagger.io/api/v3/openapi.json)',
-        type: 'string',
-        demandOption: true,
-    })
-        .option('local-schema', {
-        type: 'boolean',
-        default: false,
-        description: 'use a locally hosted schema file (note: only https protocol is supported in production)',
-    }), async ({ filename, 'local-schema': localSchema }) => {
-        try {
-            if (isAllowedLocalSchemaUrl(filename, localSchema)) {
-                await getOpenApiDocumentFromUrl(filename);
-                addLog(_jsx(SuccessLog, { message: "OpenAPI definition is valid." }));
-                await terminate(0);
-            }
-            if (filename.startsWith('http://') && !localSchema) {
-                addLog(_jsx(WarningLog, { message: "include the --local-schema flag to check locally hosted OpenAPI files" }));
-                addLog(_jsx(WarningLog, { message: "only https protocol is supported in production" }));
-                await terminate(0);
-            }
-            const document = await readLocalOpenApiFile(filename);
-            if (!document) {
-                throw new Error('failed to parse OpenAPI spec: could not parse file correctly, please check for any syntax errors.');
-            }
-            await validate(document);
-            addLog(_jsx(SuccessLog, { message: "OpenAPI definition is valid." }));
-        }
-        catch (err) {
-            if (err && typeof err === 'object' && 'code' in err && err.code === 'ENOENT') {
-                addLog(_jsx(ErrorLog, { message: `file not found, please check the path provided: ${filename}` }));
-            }
-            else {
-                addLog(_jsx(ErrorLog, { message: err instanceof Error ? err.message : 'unknown error' }));
-            }
-            await terminate(1);
-        }
-        await terminate(0);
-    })
-        .command('broken-links', 'check for invalid internal links', () => undefined, async () => {
-        addLog(_jsx(SpinnerLog, { message: "checking for broken links..." }));
-        try {
-            const brokenLinks = await getBrokenInternalLinks();
-            if (brokenLinks.length === 0) {
-                clearLogs();
-                addLog(_jsx(SuccessLog, { message: "no broken links found" }));
-                await terminate(0);
-            }
-            const brokenLinksByFile = {};
-            brokenLinks.forEach((mdxPath) => {
-                const filename = path.join(mdxPath.relativeDir, mdxPath.filename);
-                const brokenLinksForFile = brokenLinksByFile[filename];
-                if (brokenLinksForFile) {
-                    brokenLinksForFile.push(mdxPath.originalPath);
-                }
-                else {
-                    brokenLinksByFile[filename] = [mdxPath.originalPath];
-                }
-            });
-            clearLogs();
-            addLog(_jsx(BrokenLinksLog, { brokenLinksByFile: brokenLinksByFile }));
-        }
-        catch (err) {
-            addLog(_jsx(ErrorLog, { message: err instanceof Error ? err.message : 'unknown error' }));
-            await terminate(1);
-        }
-        await terminate(1);
-    })
-        .command('rename <from> <to>', 'rename a file and update all internal link references', (yargs) => yargs
-        .positional('from', {
-        describe: 'the file to rename',
-        type: 'string',
-    })
-        .positional('to', {
-        describe: 'the new name for the file',
-        type: 'string',
-    })
-        .demandOption(['from', 'to'])
-        .option('force', {
-        type: 'boolean',
-        default: false,
-        description: 'rename files and skip errors',
-    })
-        .epilog('example: `poetora rename introduction.mdx overview.mdx`'), async ({ from, to, force }) => {
-        await renameFilesAndUpdateLinksInContent(from, to, force);
-        await terminate(0);
-    })
-        .command('update', 'update the CLI to the latest version', () => undefined, async () => {
-        await update({ packageName });
-        await terminate(0);
-    })
-        .command(['a11y', 'accessibility-check', 'a11y-check', 'accessibility'], 'check for accessibility issues in documentation', () => undefined, async () => {
-        const accessibilityCheckTerminateCode = await accessibilityCheck();
-        const mdxLinterTerminateCode = await mdxLinter();
-        await terminate(accessibilityCheckTerminateCode || mdxLinterTerminateCode);
-    })
-        .command(['version', 'v'], 'display the current version of the CLI and client', () => undefined, async () => {
-        const { cli, client } = getVersions();
-        addLog(_jsxs(Text, { children: [_jsx(Text, { bold: true, color: "green", children: "cli version" }), ' ', cli] }));
-        addLog(_jsxs(Text, { children: [_jsx(Text, { bold: true, color: "green", children: "client version" }), ' ', client] }));
-    })
-        .command('new [directory]', 'Create a new Poetora documentation site', (yargs) => yargs.positional('directory', {
-        describe: 'The directory to initialize your documentation',
-        type: 'string',
-        default: '.',
-    }), async ({ directory }) => {
-        try {
-            await init(directory);
-            await terminate(0);
-        }
-        catch (error) {
-            addLog(_jsx(ErrorLog, { message: error instanceof Error ? error.message : 'error occurred' }));
-            await terminate(1);
-        }
-    })
-        .strictCommands()
-        .demandCommand(1, 'unknown command. see above for the list of supported commands.')
-        .alias('h', 'help')
-        .alias('v', 'version')
-        .parse());
+#!/usr/bin/env node
+import { CliBuilder } from './cli-builder.js';
+export const cli = (options) => {
+    const builder = new CliBuilder(options.packageName);
+    builder.run().catch((error) => {
+        console.error('Fatal error:', error);
+        process.exit(1);
+    });
 };

package/bin/commands/base.command.d.ts

@@ -0,0 +1,13 @@
+import type { ILogger } from '../utils/index.js';
+export declare abstract class BaseCommand<TOptions = unknown, TResult = void> {
+    protected readonly logger: ILogger;
+    protected readonly packageName: string;
+    abstract readonly name: string;
+    abstract readonly description: string;
+    constructor(logger: ILogger, packageName?: string);
+    run(options: TOptions): Promise<TResult>;
+    protected validate(_options: TOptions): Promise<void>;
+    protected abstract execute(options: TOptions): Promise<TResult>;
+    protected handleError(error: unknown): void;
+    protected exit(code: number): never;
+}

package/bin/commands/base.command.js

@@ -0,0 +1,40 @@
+import { CliError } from '../errors/index.js';
+export class BaseCommand {
+    logger;
+    packageName;
+    constructor(logger, packageName = 'poet') {
+        this.logger = logger;
+        this.packageName = packageName;
+    }
+    async run(options) {
+        try {
+            await this.validate(options);
+            const result = await this.execute(options);
+            return result;
+        }
+        catch (error) {
+            this.handleError(error);
+            throw error;
+        }
+    }
+    async validate(_options) {
+    }
+    handleError(error) {
+        if (error instanceof CliError) {
+            this.logger.error(error.message);
+        }
+        else if (error instanceof Error) {
+            this.logger.error(error.message);
+            if (process.env.DEBUG === 'true') {
+                console.error(error.stack);
+            }
+        }
+        else {
+            this.logger.error('An unexpected error occurred');
+            console.error(error);
+        }
+    }
+    exit(code) {
+        process.exit(code);
+    }
+}

package/bin/commands/check.command.d.ts

@@ -0,0 +1,14 @@
+import type { AccessibilityCheckService, OpenApiCheckService } from '../services/index.js';
+import type { OpenApiCheckOptions } from '../types/index.js';
+import type { ILogger } from '../utils/index.js';
+import { BaseCommand } from './base.command.js';
+export declare class CheckCommand extends BaseCommand {
+    private readonly openApiCheckService;
+    private readonly accessibilityCheckService;
+    readonly name = "check";
+    readonly description = "check OpenAPI specs or accessibility";
+    constructor(logger: ILogger, openApiCheckService: OpenApiCheckService, accessibilityCheckService: AccessibilityCheckService, packageName?: string);
+    checkOpenApi(options: OpenApiCheckOptions): Promise<void>;
+    checkAccessibility(): Promise<number>;
+    protected execute(options: OpenApiCheckOptions): Promise<void>;
+}

package/bin/commands/check.command.js

@@ -0,0 +1,21 @@
+import { BaseCommand } from './base.command.js';
+export class CheckCommand extends BaseCommand {
+    openApiCheckService;
+    accessibilityCheckService;
+    name = 'check';
+    description = 'check OpenAPI specs or accessibility';
+    constructor(logger, openApiCheckService, accessibilityCheckService, packageName = 'poet') {
+        super(logger, packageName);
+        this.openApiCheckService = openApiCheckService;
+        this.accessibilityCheckService = accessibilityCheckService;
+    }
+    async checkOpenApi(options) {
+        await this.openApiCheckService.validateSpec(options.filename, options.localSchema);
+    }
+    async checkAccessibility() {
+        return await this.accessibilityCheckService.checkAccessibility();
+    }
+    async execute(options) {
+        await this.openApiCheckService.validateSpec(options.filename, options.localSchema);
+    }
+}

package/bin/commands/dev.command.d.ts

@@ -0,0 +1,13 @@
+import type { PortService, VersionService } from '../services/index.js';
+import type { DevOptions } from '../types/index.js';
+import type { ILogger } from '../utils/index.js';
+import { BaseCommand } from './base.command.js';
+export declare class DevCommand extends BaseCommand {
+    private readonly versionService;
+    private readonly portService;
+    readonly name = "dev";
+    readonly description = "initialize a local preview environment";
+    constructor(logger: ILogger, versionService: VersionService, portService: PortService, packageName?: string);
+    protected validate(_options: DevOptions): Promise<void>;
+    protected execute(options: DevOptions): Promise<void>;
+}