@mikode13/cross-platform 0.1.0

package/LICENSE

@@ -0,0 +1,44 @@
+"Commons Clause" License Condition v1.0
+
+The Software is provided to you by the Licensor under the License, as defined below,
+subject to the following condition.
+
+Without limiting other conditions in the License, the grant of rights under the License
+will not include, and the License does not grant to you, the right to Sell the Software.
+
+For purposes of the foregoing, "Sell" means practicing any or all of the rights granted
+to you under the License to provide to third parties, for a fee or other consideration
+(including without limitation fees for hosting or consulting/support services related
+to the Software), a product or service whose value derives, entirely or substantially,
+from the functionality of the Software.
+
+Any license notice or attribution required by the License must also include this
+Commons Clause License Condition notice.
+
+Software: @mikode13/cross-platform
+License: MIT License
+Licensor: MiKode13
+
+MIT License
+
+Copyright (c) 2026 MiKode13
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the Commons Clause License Condition above
+and the following conditions:
+
+The above copyright notice, this permission notice, and the Commons Clause
+License Condition notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# @mikode13/cross-platform
+
+Cross-platform utilities for MiKode `package.json` build and maintenance scripts.
+
+## Why
+
+Some operations a build script needs — for example deleting a stale output directory
+before recompiling — have no single command that works unmodified on every platform.
+`rm -rf dist` fails under native Windows `cmd.exe`, which is what `npm`/`pnpm` invoke by
+default there, even though it works on macOS, Linux, and Windows under Git Bash, WSL, or
+PowerShell with an alias.
+
+This package centralizes that kind of operation in one MiKode-owned place, so a
+repository depends on a single first-party package instead of independently picking a
+third-party tool or hand-rolling a platform-specific command each time the same problem
+appears.
+
+See [ADR 0016](https://github.com/Mikode13/engineering/blob/main/adr/0016-centralize-cross-platform-script-utilities.md)
+and the [cross-platform script utilities standard](https://github.com/Mikode13/engineering/blob/main/standards/cross-platform-script-utilities.md)
+in `mikode-engineering` for the decision and usage policy this package implements. The
+ADR is `Accepted`.
+
+## Status
+
+The first (and currently only) capability, `clean`, is implemented: cross-platform-safe
+removal of a directory using Node's built-in `node:fs/promises`, exposed both as a
+function and as a CLI for `package.json` scripts.
+
+## Install
+
+```sh
+pnpm add @mikode13/cross-platform
+```
+
+## Usage
+
+As a function:
+
+```ts
+import { clean } from '@mikode13/cross-platform';
+
+await clean('dist');
+```
+
+From a `package.json` script, in place of `rm -rf`:
+
+```json
+{
+	"scripts": {
+		"build": "mikode-scripts clean dist && tsc -p tsconfig.build.json"
+	}
+}
+```
+
+The CLI rejects an empty path, the root of the filesystem, and the current working
+directory. It does not restrict the target to be inside the current working directory
+(for example `../other-dir` is allowed).
+
+## Tests
+
+`pnpm test` runs the unit suite.
+
+## License
+
+This project is source-available under the MIT License with the
+[Commons Clause License Condition v1.0](https://commonsclause.com/). See
+[LICENSE](./LICENSE) for the complete text. It is not OSI open source: the Commons
+Clause restricts selling the software or a service whose value derives substantially
+from it.

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":""}

package/dist/bin.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCli } from "./cli.js";
+await runCli(process.argv.slice(2), process.cwd());
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAElC,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC"}

package/dist/clean.d.ts

@@ -0,0 +1,2 @@
+export declare function clean(path: string): Promise<void>;
+//# sourceMappingURL=clean.d.ts.map

package/dist/clean.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clean.d.ts","sourceRoot":"","sources":["../src/clean.ts"],"names":[],"mappings":"AAEA,wBAAsB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKvD"}

package/dist/clean.js

@@ -0,0 +1,8 @@
+import { rm } from 'node:fs/promises';
+export async function clean(path) {
+    await rm(path, {
+        recursive: true,
+        force: true,
+    });
+}
+//# sourceMappingURL=clean.js.map

package/dist/clean.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clean.js","sourceRoot":"","sources":["../src/clean.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAEtC,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,IAAY;IACvC,MAAM,EAAE,CAAC,IAAI,EAAE;QACd,SAAS,EAAE,IAAI;QACf,KAAK,EAAE,IAAI;KACX,CAAC,CAAC;AACJ,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+export declare function resolveCleanTarget(target: string, cwd: string): string;
+export declare function runCli(argv: string[], cwd: string): Promise<void>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAGA,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAgBtE;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAWvE"}

package/dist/cli.js

@@ -0,0 +1,24 @@
+import path from 'node:path';
+import { clean } from "./clean.js";
+export function resolveCleanTarget(target, cwd) {
+    if (!target.trim()) {
+        throw new Error('A path is required');
+    }
+    const resolved = path.resolve(cwd, target);
+    if (resolved === path.parse(resolved).root) {
+        throw new Error('Cannot clean a filesystem root');
+    }
+    if (resolved === path.resolve(cwd)) {
+        throw new Error('Cannot clean the current working directory');
+    }
+    return resolved;
+}
+export async function runCli(argv, cwd) {
+    const [command, target] = argv;
+    if (command !== 'clean') {
+        throw new Error(`Unrecognized command: "${command ?? ''}". The only supported command is "clean".`);
+    }
+    const resolved = resolveCleanTarget(target ?? '', cwd);
+    await clean(resolved);
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,MAAM,UAAU,kBAAkB,CAAC,MAAc,EAAE,GAAW;IAC7D,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC;IACvC,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAE3C,IAAI,QAAQ,KAAK,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACnD,CAAC;IAED,IAAI,QAAQ,KAAK,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAC/D,CAAC;IAED,OAAO,QAAQ,CAAC;AACjB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,IAAc,EAAE,GAAW;IACvD,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAE/B,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CACd,0BAA0B,OAAO,IAAI,EAAE,2CAA2C,CAClF,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,kBAAkB,CAAC,MAAM,IAAI,EAAE,EAAE,GAAG,CAAC,CAAC;IACvD,MAAM,KAAK,CAAC,QAAQ,CAAC,CAAC;AACvB,CAAC"}

package/dist/cliClean.d.ts

@@ -0,0 +1,3 @@
+export declare function resolveCleanTarget(target: string, cwd: string): string;
+export declare function runCli(argv: string[], cwd: string): Promise<void>;
+//# sourceMappingURL=cliClean.d.ts.map

package/dist/cliClean.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cliClean.d.ts","sourceRoot":"","sources":["../src/cliClean.ts"],"names":[],"mappings":"AAGA,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAgBtE;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAWvE"}

package/dist/cliClean.js

@@ -0,0 +1,24 @@
+import path from 'node:path';
+import { clean } from "./clean.js";
+export function resolveCleanTarget(target, cwd) {
+    if (!target.trim()) {
+        throw new Error('A path is required');
+    }
+    const resolved = path.resolve(cwd, target);
+    if (resolved === path.parse(resolved).root) {
+        throw new Error('Cannot clean a filesystem root');
+    }
+    if (resolved === path.resolve(cwd)) {
+        throw new Error('Cannot clean the current working directory');
+    }
+    return resolved;
+}
+export async function runCli(argv, cwd) {
+    const [command, target] = argv;
+    if (command !== 'clean') {
+        throw new Error(`Unrecognized command: "${command ?? ''}". The only supported command is "clean".`);
+    }
+    const resolved = resolveCleanTarget(target ?? '', cwd);
+    await clean(resolved);
+}
+//# sourceMappingURL=cliClean.js.map

package/dist/cliClean.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cliClean.js","sourceRoot":"","sources":["../src/cliClean.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,MAAM,UAAU,kBAAkB,CAAC,MAAc,EAAE,GAAW;IAC7D,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC;IACvC,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAE3C,IAAI,QAAQ,KAAK,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACnD,CAAC;IAED,IAAI,QAAQ,KAAK,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAC/D,CAAC;IAED,OAAO,QAAQ,CAAC;AACjB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,IAAc,EAAE,GAAW;IACvD,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;IAE/B,IAAI,OAAO,KAAK,OAAO,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CACd,0BAA0B,OAAO,IAAI,EAAE,2CAA2C,CAClF,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAG,kBAAkB,CAAC,MAAM,IAAI,EAAE,EAAE,GAAG,CAAC,CAAC;IACvD,MAAM,KAAK,CAAC,QAAQ,CAAC,CAAC;AACvB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { clean } from './clean.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { clean } from "./clean.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@mikode13/cross-platform",
+  "version": "0.1.0",
+  "description": "Cross-platform utilities for MiKode build and maintenance scripts",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mikode13/cross-platform.git"
+  },
+  "engines": {
+    "node": "^22.13.0 || ^24.0.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "bin": {
+    "mikode-scripts": "./dist/bin.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@mikode13/code-quality": "0.1.0",
+    "@mikode13/code-style": "0.1.0",
+    "@mikode13/git-hooks": "0.1.0",
+    "@mikode13/tsconfig": "0.1.0",
+    "@types/node": "^26.1.2",
+    "@vitest/coverage-v8": "^4.1.11",
+    "eslint": "^10.8.0",
+    "prettier": "^3.9.6",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.11"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tests",
+    "format": "prettier . --write",
+    "format:check": "prettier . --check",
+    "lint": "eslint . --max-warnings 0",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run --project unit",
+    "test:unit": "vitest run --project unit",
+    "test:unit:watch": "vitest --project unit",
+    "test:coverage": "vitest run --project unit --coverage",
+    "pack:check": "pnpm pack --dry-run",
+    "check": "pnpm run format:check && pnpm run lint && pnpm run typecheck"
+  }
+}