@klyper/cli 0.3.0

package/README.md

@@ -0,0 +1,54 @@
+# @klyper/cli
+
+Command line tools for managing the Klyper monorepo.
+
+## Commands
+
+```sh
+npm run build --workspace @klyper/cli
+npm run check --workspace @klyper/cli
+npm run lint --workspace @klyper/cli
+npm test --workspace @klyper/cli
+```
+
+`build` uses Rollup for the package output. `check` runs TypeScript without emitting files.
+
+## Create a Package
+
+Create a new package template:
+
+```sh
+npm exec klyper create package utils
+```
+
+Alternative syntax:
+
+```sh
+npm exec klyper package create utils
+```
+
+The command creates `packages/utils` with:
+
+- `package.json`
+- `tsconfig.json`
+- `README.md`
+- `src/index.ts`
+- `src/index.test.ts`
+
+The generated `package.json` follows the public package convention used by the
+monorepo:
+
+- `main` points to the CommonJS bundle at `./dist/index.cjs`
+- `module` and `exports.import` point to the ESM bundle at `./dist/index.js`
+- `types` and `exports.types` point to `./dist/index.d.ts`
+- `exports.require` points to the CommonJS bundle
+- `sideEffects` is `false`
+- `prepublishOnly` runs `npm run build && npm test`
+
+The root build runs each package through npm workspaces, so new packages do not need root TypeScript project references.
+
+Use a custom scope:
+
+```sh
+npm exec klyper create package auth --scope @klyper
+```

package/dist/index.cjs

@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+/*!
+ * @klyper/cli v0.3.0
+ * Command line tools for the Klyper monorepo.
+ * (c) 2026 Andrew Caires
+ * @license: MIT
+ */
+
+'use strict';
+
+var node_fs = require('node:fs');
+var node_url = require('node:url');
+var promises = require('node:fs/promises');
+var node_path = require('node:path');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+const defaultScope = "@klyper";
+const packageNamePattern = /^[a-z][a-z0-9-]*$/;
+const scopePattern = /^@[a-z][a-z0-9-]*$/;
+const helpText = `Klyper CLI
+
+Usage:
+  klyper create package <name> [--scope @scope]
+  klyper package create <name> [--scope @scope]
+
+Examples:
+  klyper create package utils
+  klyper create package auth --scope @klyper
+`;
+const runCli = async (args, io) => {
+    try {
+        if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+            io.stdout.write(helpText);
+            return 0;
+        }
+        const command = parseCreatePackageCommand(args);
+        const result = await createPackageTemplate({
+            cwd: io.cwd,
+            name: command.name,
+            scope: command.scope
+        });
+        io.stdout.write(`Created ${result.packageName} in packages/${result.directoryName}\n`);
+        return 0;
+    }
+    catch (error) {
+        io.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+};
+const createPackageTemplate = async (options) => {
+    const identifier = parsePackageIdentifier(options.name, options.scope ?? defaultScope);
+    const packageRoot = node_path.join(options.cwd, "packages", identifier.directoryName);
+    if (await pathExists(packageRoot)) {
+        throw new Error(`Package directory already exists: packages/${identifier.directoryName}`);
+    }
+    const files = buildPackageFiles(identifier);
+    await promises.mkdir(node_path.join(packageRoot, "src"), { recursive: true });
+    await Promise.all(files.map((file) => promises.writeFile(node_path.join(packageRoot, file.path), file.content)));
+    return {
+        directoryName: identifier.directoryName,
+        packageName: identifier.packageName,
+        packageRoot,
+        files: files.map((file) => node_path.join(packageRoot, file.path))
+    };
+};
+const parseCreatePackageCommand = (args) => {
+    const [first, second, third, ...rest] = args;
+    const isCreatePackage = first === "create" && second === "package";
+    const isPackageCreate = first === "package" && second === "create";
+    if (!isCreatePackage && !isPackageCreate) {
+        throw new Error("Unknown command. Run `klyper --help` for usage.");
+    }
+    if (!third) {
+        throw new Error("Missing package name.");
+    }
+    const scope = readScopeOption(rest);
+    return { name: third, scope };
+};
+const readScopeOption = (args) => {
+    if (args.length === 0) {
+        return defaultScope;
+    }
+    if (args.length === 2 && args[0] === "--scope") {
+        return args[1] ?? defaultScope;
+    }
+    throw new Error(`Unknown option: ${args.join(" ")}`);
+};
+const parsePackageIdentifier = (name, scope) => {
+    const trimmedName = name.trim();
+    const trimmedScope = scope.trim();
+    if (trimmedName.startsWith("@")) {
+        const [providedScope, packageName, extra] = trimmedName.split("/");
+        if (extra || !providedScope || !packageName) {
+            throw new Error("Scoped package names must use the @scope/name format.");
+        }
+        validateScope(providedScope);
+        validatePackageName(packageName);
+        return {
+            directoryName: packageName,
+            packageName: `${providedScope}/${packageName}`
+        };
+    }
+    validateScope(trimmedScope);
+    validatePackageName(trimmedName);
+    return {
+        directoryName: trimmedName,
+        packageName: `${trimmedScope}/${trimmedName}`
+    };
+};
+const validatePackageName = (name) => {
+    if (!packageNamePattern.test(name)) {
+        throw new Error("Package names must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens.");
+    }
+};
+const validateScope = (scope) => {
+    if (!scopePattern.test(scope)) {
+        throw new Error("Package scopes must use @scope and contain only lowercase letters, numbers, and hyphens.");
+    }
+};
+const buildPackageFiles = (identifier) => {
+    return [
+        {
+            path: "package.json",
+            content: `${JSON.stringify({
+                name: identifier.packageName,
+                version: "0.0.0",
+                description: `Klyper ${identifier.directoryName} package.`,
+                author: "Andrew Caires",
+                license: "MIT",
+                repository: {
+                    type: "git",
+                    url: "git+https://github.com/andrewcaires/klyper.git"
+                },
+                type: "module",
+                main: "./dist/index.cjs",
+                module: "./dist/index.js",
+                types: "./dist/index.d.ts",
+                exports: {
+                    ".": {
+                        types: "./dist/index.d.ts",
+                        import: "./dist/index.js",
+                        require: "./dist/index.cjs",
+                        default: "./dist/index.js"
+                    }
+                },
+                sideEffects: false,
+                files: ["dist"],
+                scripts: {
+                    build: "npm run clean && npm run check && npm run bundle",
+                    bundle: "rollup --bundleConfigAsCjs -c ../../rollup.config.js",
+                    check: "npm run lint && npm run typecheck",
+                    clean: "rm -rf dist",
+                    lint: "eslint .",
+                    "lint:fix": "eslint . --fix",
+                    prepublishOnly: "npm run build && npm test",
+                    test: "node --import tsx --test \"src/**/*.test.ts\"",
+                    "test:watch": "node --import tsx --test --watch \"src/**/*.test.ts\"",
+                    typecheck: "tsc -p tsconfig.json --noEmit"
+                },
+                publishConfig: {
+                    access: "public"
+                }
+            }, null, 2)}\n`
+        },
+        {
+            path: "README.md",
+            content: `# ${identifier.packageName}
+
+Klyper ${identifier.directoryName} package.
+
+## Installation
+
+\`\`\`sh
+npm install ${identifier.packageName}
+\`\`\`
+
+This package is published as an ES module package and also exposes a CommonJS
+entry through \`main\` and \`exports.require\`.
+
+## Commands
+
+\`\`\`sh
+npm run build --workspace ${identifier.packageName}
+npm run check --workspace ${identifier.packageName}
+npm run lint --workspace ${identifier.packageName}
+npm test --workspace ${identifier.packageName}
+\`\`\`
+
+\`build\` uses Rollup for the package output. \`check\` runs TypeScript without emitting files.
+\`prepublishOnly\` runs the package build and test suite before npm publish.
+
+## API
+
+\`\`\`ts
+import { getPackageName } from "${identifier.packageName}";
+
+getPackageName();
+\`\`\`
+`
+        },
+        {
+            path: "tsconfig.json",
+            content: `${JSON.stringify({
+                extends: "../../tsconfig.base.json",
+                compilerOptions: {
+                    outDir: "dist",
+                    rootDir: "src"
+                },
+                include: ["src/**/*.ts"],
+            }, null, 2)}\n`
+        },
+        {
+            path: "src/index.ts",
+            content: `export const getPackageName = (): string => {
+  return "${identifier.packageName}";
+};
+`
+        },
+        {
+            path: "src/index.test.ts",
+            content: `import { equal } from "node:assert/strict";
+import test from "node:test";
+
+import { getPackageName } from "./index.js";
+
+test("getPackageName returns the package name", () => {
+  equal(getPackageName(), "${identifier.packageName}");
+});
+`
+        }
+    ];
+};
+const pathExists = async (path) => {
+    try {
+        await promises.stat(path);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+};
+
+const isCliEntryPoint = () => {
+    return !!process.argv[1] && node_fs.realpathSync(process.argv[1]) === node_url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)));
+};
+if (isCliEntryPoint()) {
+    void runCli(process.argv.slice(2), {
+        cwd: process.cwd(),
+        stdout: process.stdout,
+        stderr: process.stderr
+    }).then((exitCode) => {
+        process.exitCode = exitCode;
+    });
+}
+
+exports.createPackageTemplate = createPackageTemplate;
+exports.runCli = runCli;

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+/*!
+ * @klyper/cli v0.3.0
+ * Command line tools for the Klyper monorepo.
+ * (c) 2026 Andrew Caires
+ * @license: MIT
+ */
+
+type Writable = {
+    write: (_chunk: string) => void;
+};
+type CliIo = {
+    cwd: string;
+    stdout: Writable;
+    stderr: Writable;
+};
+type PackageTemplateResult = {
+    directoryName: string;
+    packageName: string;
+    packageRoot: string;
+    files: string[];
+};
+declare const runCli: (args: string[], io: CliIo) => Promise<number>;
+declare const createPackageTemplate: (options: {
+    cwd: string;
+    name: string;
+    scope?: string;
+}) => Promise<PackageTemplateResult>;
+
+export { createPackageTemplate, runCli };
+export type { CliIo, PackageTemplateResult };

package/dist/index.js

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+/*!
+ * @klyper/cli v0.3.0
+ * Command line tools for the Klyper monorepo.
+ * (c) 2026 Andrew Caires
+ * @license: MIT
+ */
+
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { mkdir, writeFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const defaultScope = "@klyper";
+const packageNamePattern = /^[a-z][a-z0-9-]*$/;
+const scopePattern = /^@[a-z][a-z0-9-]*$/;
+const helpText = `Klyper CLI
+
+Usage:
+  klyper create package <name> [--scope @scope]
+  klyper package create <name> [--scope @scope]
+
+Examples:
+  klyper create package utils
+  klyper create package auth --scope @klyper
+`;
+const runCli = async (args, io) => {
+    try {
+        if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+            io.stdout.write(helpText);
+            return 0;
+        }
+        const command = parseCreatePackageCommand(args);
+        const result = await createPackageTemplate({
+            cwd: io.cwd,
+            name: command.name,
+            scope: command.scope
+        });
+        io.stdout.write(`Created ${result.packageName} in packages/${result.directoryName}\n`);
+        return 0;
+    }
+    catch (error) {
+        io.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+};
+const createPackageTemplate = async (options) => {
+    const identifier = parsePackageIdentifier(options.name, options.scope ?? defaultScope);
+    const packageRoot = join(options.cwd, "packages", identifier.directoryName);
+    if (await pathExists(packageRoot)) {
+        throw new Error(`Package directory already exists: packages/${identifier.directoryName}`);
+    }
+    const files = buildPackageFiles(identifier);
+    await mkdir(join(packageRoot, "src"), { recursive: true });
+    await Promise.all(files.map((file) => writeFile(join(packageRoot, file.path), file.content)));
+    return {
+        directoryName: identifier.directoryName,
+        packageName: identifier.packageName,
+        packageRoot,
+        files: files.map((file) => join(packageRoot, file.path))
+    };
+};
+const parseCreatePackageCommand = (args) => {
+    const [first, second, third, ...rest] = args;
+    const isCreatePackage = first === "create" && second === "package";
+    const isPackageCreate = first === "package" && second === "create";
+    if (!isCreatePackage && !isPackageCreate) {
+        throw new Error("Unknown command. Run `klyper --help` for usage.");
+    }
+    if (!third) {
+        throw new Error("Missing package name.");
+    }
+    const scope = readScopeOption(rest);
+    return { name: third, scope };
+};
+const readScopeOption = (args) => {
+    if (args.length === 0) {
+        return defaultScope;
+    }
+    if (args.length === 2 && args[0] === "--scope") {
+        return args[1] ?? defaultScope;
+    }
+    throw new Error(`Unknown option: ${args.join(" ")}`);
+};
+const parsePackageIdentifier = (name, scope) => {
+    const trimmedName = name.trim();
+    const trimmedScope = scope.trim();
+    if (trimmedName.startsWith("@")) {
+        const [providedScope, packageName, extra] = trimmedName.split("/");
+        if (extra || !providedScope || !packageName) {
+            throw new Error("Scoped package names must use the @scope/name format.");
+        }
+        validateScope(providedScope);
+        validatePackageName(packageName);
+        return {
+            directoryName: packageName,
+            packageName: `${providedScope}/${packageName}`
+        };
+    }
+    validateScope(trimmedScope);
+    validatePackageName(trimmedName);
+    return {
+        directoryName: trimmedName,
+        packageName: `${trimmedScope}/${trimmedName}`
+    };
+};
+const validatePackageName = (name) => {
+    if (!packageNamePattern.test(name)) {
+        throw new Error("Package names must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens.");
+    }
+};
+const validateScope = (scope) => {
+    if (!scopePattern.test(scope)) {
+        throw new Error("Package scopes must use @scope and contain only lowercase letters, numbers, and hyphens.");
+    }
+};
+const buildPackageFiles = (identifier) => {
+    return [
+        {
+            path: "package.json",
+            content: `${JSON.stringify({
+                name: identifier.packageName,
+                version: "0.0.0",
+                description: `Klyper ${identifier.directoryName} package.`,
+                author: "Andrew Caires",
+                license: "MIT",
+                repository: {
+                    type: "git",
+                    url: "git+https://github.com/andrewcaires/klyper.git"
+                },
+                type: "module",
+                main: "./dist/index.cjs",
+                module: "./dist/index.js",
+                types: "./dist/index.d.ts",
+                exports: {
+                    ".": {
+                        types: "./dist/index.d.ts",
+                        import: "./dist/index.js",
+                        require: "./dist/index.cjs",
+                        default: "./dist/index.js"
+                    }
+                },
+                sideEffects: false,
+                files: ["dist"],
+                scripts: {
+                    build: "npm run clean && npm run check && npm run bundle",
+                    bundle: "rollup --bundleConfigAsCjs -c ../../rollup.config.js",
+                    check: "npm run lint && npm run typecheck",
+                    clean: "rm -rf dist",
+                    lint: "eslint .",
+                    "lint:fix": "eslint . --fix",
+                    prepublishOnly: "npm run build && npm test",
+                    test: "node --import tsx --test \"src/**/*.test.ts\"",
+                    "test:watch": "node --import tsx --test --watch \"src/**/*.test.ts\"",
+                    typecheck: "tsc -p tsconfig.json --noEmit"
+                },
+                publishConfig: {
+                    access: "public"
+                }
+            }, null, 2)}\n`
+        },
+        {
+            path: "README.md",
+            content: `# ${identifier.packageName}
+
+Klyper ${identifier.directoryName} package.
+
+## Installation
+
+\`\`\`sh
+npm install ${identifier.packageName}
+\`\`\`
+
+This package is published as an ES module package and also exposes a CommonJS
+entry through \`main\` and \`exports.require\`.
+
+## Commands
+
+\`\`\`sh
+npm run build --workspace ${identifier.packageName}
+npm run check --workspace ${identifier.packageName}
+npm run lint --workspace ${identifier.packageName}
+npm test --workspace ${identifier.packageName}
+\`\`\`
+
+\`build\` uses Rollup for the package output. \`check\` runs TypeScript without emitting files.
+\`prepublishOnly\` runs the package build and test suite before npm publish.
+
+## API
+
+\`\`\`ts
+import { getPackageName } from "${identifier.packageName}";
+
+getPackageName();
+\`\`\`
+`
+        },
+        {
+            path: "tsconfig.json",
+            content: `${JSON.stringify({
+                extends: "../../tsconfig.base.json",
+                compilerOptions: {
+                    outDir: "dist",
+                    rootDir: "src"
+                },
+                include: ["src/**/*.ts"],
+            }, null, 2)}\n`
+        },
+        {
+            path: "src/index.ts",
+            content: `export const getPackageName = (): string => {
+  return "${identifier.packageName}";
+};
+`
+        },
+        {
+            path: "src/index.test.ts",
+            content: `import { equal } from "node:assert/strict";
+import test from "node:test";
+
+import { getPackageName } from "./index.js";
+
+test("getPackageName returns the package name", () => {
+  equal(getPackageName(), "${identifier.packageName}");
+});
+`
+        }
+    ];
+};
+const pathExists = async (path) => {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+};
+
+const isCliEntryPoint = () => {
+    return !!process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
+};
+if (isCliEntryPoint()) {
+    void runCli(process.argv.slice(2), {
+        cwd: process.cwd(),
+        stdout: process.stdout,
+        stderr: process.stderr
+    }).then((exitCode) => {
+        process.exitCode = exitCode;
+    });
+}
+
+export { createPackageTemplate, runCli };

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@klyper/cli",
+  "version": "0.3.0",
+  "description": "Command line tools for the Klyper monorepo.",
+  "author": "Andrew Caires",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/andrewcaires/klyper.git"
+  },
+  "type": "module",
+  "bin": {
+    "klyper": "dist/index.js"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "npm run clean && npm run check && npm run bundle",
+    "bundle": "rollup --bundleConfigAsCjs -c ../../rollup.config.js && chmod +x dist/index.js",
+    "check": "npm run lint && npm run typecheck",
+    "clean": "rm -rf dist",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "prepublishOnly": "npm run build && npm test",
+    "test": "node --import tsx --test \"src/**/*.test.ts\"",
+    "test:watch": "node --import tsx --test --watch \"src/**/*.test.ts\"",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}