milkee 3.0.0 → 3.0.1

package/.prettierrc.json

@@ -0,0 +1,3 @@
+{
+  "tabWidth": 2
+}

package/README-ja.md

@@ -0,0 +1,160 @@
+# Milkee
+
+[![Vitest](https://github.com/otoneko1102/coffeescript-milkee/actions/workflows/test.yml/badge.svg)](https://github.com/otoneko1102/coffeescript-milkee/actions)
+[![npm version](https://img.shields.io/npm/v/milkee.svg)](https://www.npmjs.com/package/milkee)
+[![Downloads](https://img.shields.io/npm/dw/milkee.svg)](https://www.npmjs.com/package/milkee)
+[![License](https://img.shields.io/npm/l/milkee.svg)](./LICENSE)
+
+[English](./README.md) | **日本語**  
+
+![Milkee logo](./img/Milkee-logo.png)  
+
+`coffee.config.cjs` を使ったシンプルな CoffeeScript ビルドツール
+
+## はじめに
+
+### インストール
+
+Milkee をインストールします:  
+
+```bash
+# グローバルインストール
+npm i -g milkee
+
+# ローカルインストール
+npm i -D milkee
+```
+
+CoffeeScript と `@babel/core` が必要です。  
+
+> [!TIP]
+> `options.transpile` が `true` の場合は `@babel/core` が必要です。
+
+```bash
+# グローバルインストール
+npm i -g coffeescript @babel/core
+
+# ローカルインストール
+npm i -D coffeescript @babel/core
+```
+
+### セットアップ
+
+`-s` (`--setup`) コマンドを実行すると、`coffee.config.cjs` が生成されます！  
+
+```bash
+# グローバル
+milkee -s
+
+# ローカル
+npx milkee -s
+```
+
+#### `coffee.config.cjs`
+
+```js
+/** @type {import('@milkee/d').Config} */
+
+module.exports = {
+  // コンパイルのエントリーポイント。
+  // 単一ファイルまたはディレクトリ（例: 'src/' や 'src/app.coffee'）を指定できます。
+  entry: 'src',
+  // コンパイルされた JavaScript ファイルの出力先。
+  // `options.join` が true の場合は単一ファイルパス（例: 'dist/app.js'）
+  // `options.join` が false の場合はディレクトリ（例: 'dist'）を指定します。
+  output: 'dist',
+  // (任意) CoffeeScript コンパイラの追加オプション。
+  // 利用可能な全オプションは `coffee --help` を参照してください。
+  // Web: https://coffeescript.org/annotated-source/command.html
+  options: {
+    // 以下のオプションがサポートされています:
+    // bare: false,
+    // join: false,
+    // map: false,
+    // inlineMap: false,
+    // noHeader: false,
+    // transpile: false,
+    // literate: false,
+    // watch: false,
+  },
+  // (任意) Milkee ビルダーの追加オプション / プラグイン。
+  milkee: {
+    options: {
+      // コンパイル前に出力ディレクトリをリセットします。
+      // refresh: false,
+      // コンパイル前に「実行しますか？」と確認します。
+      // confirm: false,
+      // コンパイル後に entry から output へ非 CoffeeScript ファイルをコピーします。（`options.join` が false の場合のみ有効）
+      // copy: false,
+    },
+    plugins: []
+  },
+};
+```
+
+##### `options` (CoffeeScript コンパイラオプション)
+
+これらのオプションは `coffee` コンパイラに直接渡されます。  
+
+| オプション | 型 | デフォルト | 説明 |
+| :--- | :--- | :--- | :--- |
+| `bare` | `boolean` | `false` | トップレベルの関数ラッパーなしでコンパイルする |
+| `join` | `boolean` | `false` | コンパイル前にソースを連結する |
+| `map` | `boolean` | `false` | ソースマップを生成して `.js.map` として保存する |
+| `inlineMap` | `boolean` | `false` | ソースマップを生成して出力内に直接含める |
+| `noHeader` | `boolean` | `false` | "Generated by" ヘッダを抑制する |
+| `transpile` | `boolean` | `false` | 生成された JavaScript を Babel に通す |
+| `literate` | `boolean` | `false` | 標準入力をリテラート形式の CoffeeScript として扱う |
+| `watch` | `boolean` | `false` | ファイル変更を監視してコマンドを再実行する |
+
+[CoffeeScript - command.coffee](https://coffeescript.org/annotated-source/command.html)  
+
+##### `milkee.options` (Milkee 固有オプション)
+
+これらのオプションは Milkee の動作を制御します。  
+
+| オプション | 型 | デフォルト | 説明 |
+| :--- | :--- | :--- | :--- |
+| `refresh` | `boolean` | `false` | コンパイル前に出力ディレクトリをリセットする |
+| `confirm` | `boolean` | `false` | コンパイル前に「実行しますか？」と確認する |
+| `copy` | `boolean` | `false` | コンパイル後に entry から output へ非 CoffeeScript ファイルをコピーする（`options.join` が false の場合のみ） |
+
+##### `milkee.plugins` (Milkee 固有プラグイン)
+
+Milkee の機能はプラグインで拡張できます。プラグインは、各コンパイル成功後に実行され、コンパイル済みファイルと設定にアクセスできる単純な関数です。
+
+例:
+
+```js
+const myPlugin = require('./plugins/my-plugin.js');
+
+module.exports = {
+  // ...
+  milkee: {
+    plugins: [
+      // この呼び出しは PluginExecutor を返します
+      myPlugin({ option: 'value' }),
+      // ...
+    ]
+  }
+}
+```
+
+### コンパイル
+
+Milkee は自動で `coffee.config.cjs` を読み、`options` からコマンドを組み立ててコンパイルを開始します！  
+
+```bash
+# グローバル
+milkee
+
+# ローカル
+npx milkee
+```
+
+## プラグインの作成
+
+独自の Milkee プラグインを作成したいですか？プラグインのドキュメントを確認してください:  
+
+- [English](./docs/PLUGIN.md)
+- [日本語](./docs/PLUGIN-ja.md)

package/README.md

@@ -1,5 +1,12 @@
 # Milkee
 
+[![Vitest](https://github.com/otoneko1102/coffeescript-milkee/actions/workflows/test.yml/badge.svg)](https://github.com/otoneko1102/coffeescript-milkee/actions)
+[![npm version](https://img.shields.io/npm/v/milkee.svg)](https://www.npmjs.com/package/milkee)
+[![Downloads](https://img.shields.io/npm/dw/milkee.svg)](https://www.npmjs.com/package/milkee)
+[![License](https://img.shields.io/npm/l/milkee.svg)](./LICENSE)
+
+**English** | [日本語](./README-ja.md)  
+
 ![Milkee logo](./img/Milkee-logo.png)  
 
 A simple CoffeeScript build tool with [coffee.config.cjs](./temp/coffee.config.cjs)  
@@ -89,16 +96,16 @@ module.exports = {
 
 These options are passed directly to the `coffee` compiler.  
 
-| Option      | Type      | Default | Description                                             |
-| :---------- | :-------- | :------ | :------------------------------------------------------ |
-| `bare`      | `boolean` | `false`   | compile without a top-level function wrapper            |
-| `join`      | `boolean` | `false`   | concatenate the source CoffeeScript before compiling    |
-| `map`       | `boolean` | `false`   | generate source map and save as `.js.map` files         |
-| `inlineMap` | `boolean` | `false`   | generate source map and include it directly in output   |
-| `noHeader`  | `boolean` | `false`   | suppress the "Generated by" header                      |
-| `transpile` | `boolean` | `false`   | pipe generated JavaScript through Babel                 |
-| `literate`  | `boolean` | `false`   | treat stdio as literate style coffeescript              |
-| `watch`     | `boolean` | `false`   | watch scripts for changes and rerun commands            |
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `bare` | `boolean` | `false` | compile without a top-level function wrapper |
+| `join` | `boolean` | `false` | concatenate the source CoffeeScript before compiling |
+| `map` | `boolean` | `false` | generate source map and save as `.js.map` files |
+| `inlineMap` | `boolean` | `false` | generate source map and include it directly in output |
+| `noHeader` | `boolean` | `false` | suppress the "Generated by" header |
+| `transpile` | `boolean` | `false` | pipe generated JavaScript through Babel |
+| `literate` | `boolean` | `false` | treat stdio as literate style coffeescript |
+| `watch` | `boolean` | `false` | watch scripts for changes and rerun commands |
 
 [CoffeeScript - command.coffee](https://coffeescript.org/annotated-source/command.html)  
 
@@ -106,11 +113,11 @@ These options are passed directly to the `coffee` compiler.
 
 These options control Milkee's behavior.  
 
-| Option    | Type      | Default | Description                                            |
-| :-------- | :-------- | :------ | :----------------------------------------------------- |
-| `refresh` | `boolean` | `false`   | Before compiling, reset the output directory.          |
-| `confirm` | `boolean` | `false`   | Before compiling, prompt "Do you want to Continue?". |
-| `copy`    | `boolean` | `false`   | After compiling, copy non-coffee files from entry to output directory. (Only works when `options.join` is `false`) |
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `refresh` | `boolean` | `false` | Before compiling, reset the output directory. |
+| `confirm` | `boolean` | `false` | Before compiling, prompt "Do you want to Continue?". |
+| `copy` | `boolean` | `false` | After compiling, copy non-coffee files from entry to output directory. (Only works when `options.join` is `false`) |
 
 ##### `milkee.plugins` (Milkee Specific Plugins)
 

package/dist/commands/compile.js

@@ -11,11 +11,11 @@ crypto = require('crypto');
 
 consola = require('consola');
 
-({CWD, CONFIG_PATH, CONFIG_FILE} = require('../constants'));
+({CWD, CONFIG_PATH, CONFIG_FILE} = require('../lib/constants'));
 
-({checkLatest, checkCoffee} = require('../checks'));
+({checkLatest, checkCoffee} = require('../lib/checks'));
 
-({runPlugins} = require('../plugins'));
+({runPlugins} = require('../lib/plugins'));
 
 confirmContinue = require('../options/confirm');
 

package/dist/commands/plugin.js

@@ -10,7 +10,7 @@ path = require('path');
 
 consola = require('consola');
 
-({CWD, CONFIG_FILE} = require('../constants'));
+({CWD, CONFIG_FILE} = require('../lib/constants'));
 
 confirmContinue = require('../options/confirm');
 

package/dist/commands/setup.js

@@ -7,9 +7,9 @@ path = require('path');
 
 consola = require('consola');
 
-({CONFIG_FILE, CONFIG_PATH} = require('../constants'));
+({CONFIG_FILE, CONFIG_PATH} = require('../lib/constants'));
 
-({checkCoffee} = require('../checks'));
+({checkCoffee} = require('../lib/checks'));
 
 // async
 setup = async function() {

package/dist/lib/checks.js

@@ -0,0 +1,58 @@
+// Generated by CoffeeScript 2.7.0
+var CWD, checkCoffee, checkLatest, consola, exec, fs, isPackageLatest, path, pkg;
+
+fs = require('fs');
+
+path = require('path');
+
+({exec} = require('child_process'));
+
+consola = require('consola');
+
+({isPackageLatest} = require('is-package-latest'));
+
+({pkg, CWD} = require('./constants'));
+
+// async
+checkLatest = async function() {
+  var res;
+  try {
+    res = (await isPackageLatest(pkg));
+    if (res.success && !res.isLatest) {
+      consola.box({
+        title: "A new version is now available!",
+        message: `${res.currentVersion} --> \`${res.latestVersion}\`\n\n# global installation\n\`npm i -g milkee@latest\`\n# or local installation\n\`npm i -D milkee@latest\``
+      });
+      return true;
+    } else {
+      return false;
+    }
+  } catch (error1) {
+    return false;
+  }
+};
+
+checkCoffee = function() {
+  var PKG_PATH, error, pkgData, pkgFile, ref, ref1;
+  PKG_PATH = path.join(CWD, 'package.json');
+  if (fs.existsSync(PKG_PATH)) {
+    try {
+      pkgFile = fs.readFileSync(PKG_PATH, 'utf-8');
+      pkgData = JSON.parse(pkgFile);
+      if (((ref = pkgData.dependencies) != null ? ref.coffeescript : void 0) || ((ref1 = pkgData.devDependencies) != null ? ref1.coffeescript : void 0)) {
+        return;
+      }
+    } catch (error1) {
+      error = error1;
+      consola.warn(`Could not parse \`package.json\`: ${error.message}`);
+    }
+  }
+  return exec('coffee --version', function(error) {
+    if (error) {
+      consola.warn('CoffeeScript is not found in local dependencies (`dependencies`, `devDependencies`) or globally.');
+      return consola.info('Please install it via `npm install --save-dev coffeescript` to continue.');
+    }
+  });
+};
+
+module.exports = {checkLatest, checkCoffee};

package/dist/lib/constants.js

@@ -0,0 +1,14 @@
+// Generated by CoffeeScript 2.7.0
+var CONFIG_FILE, CONFIG_PATH, CWD, path, pkg;
+
+path = require('path');
+
+pkg = require('../../package.json');
+
+CWD = process.cwd();
+
+CONFIG_FILE = 'coffee.config.cjs';
+
+CONFIG_PATH = path.join(CWD, CONFIG_FILE);
+
+module.exports = {pkg, CWD, CONFIG_FILE, CONFIG_PATH};

package/dist/lib/plugins.js

@@ -0,0 +1,59 @@
+// Generated by CoffeeScript 2.7.0
+var CWD, consola, executePlugins, fs, getCompiledFiles, path, runPlugins;
+
+path = require('path');
+
+fs = require('fs');
+
+consola = require('consola');
+
+({CWD} = require('./constants'));
+
+({getCompiledFiles} = require('./utils'));
+
+executePlugins = function(config, compilationResult) {
+  var plugins, ref;
+  plugins = ((ref = config.milkee) != null ? ref.plugins : void 0) || [];
+  if (!(plugins.length > 0)) {
+    return;
+  }
+  consola.start(`Running ${plugins.length} plugin(s)...`);
+  return (async function() {    // async
+    var error, i, len, pluginFn;
+    try {
+      for (i = 0, len = plugins.length; i < len; i++) {
+        pluginFn = plugins[i];
+        if (typeof pluginFn === 'function') {
+          await Promise.resolve(pluginFn(compilationResult));
+        } else {
+          consola.warn(`Invalid plugin definition skipped (expected a function, got ${typeof pluginFn}).`);
+        }
+      }
+      return consola.success("Plugins executed successfully.");
+    } catch (error1) {
+      error = error1;
+      return consola.error("An error occurred during plugin execution:", error);
+    }
+  })();
+};
+
+runPlugins = function(config, options, stdout = '', stderr = '') {
+  var compilationResult, compiledFiles, mapPath, outputPath;
+  outputPath = path.join(CWD, config.output);
+  compiledFiles = getCompiledFiles(outputPath);
+  if (options.join && options.map && !options.inlineMap) {
+    mapPath = `${outputPath}.map`;
+    if (fs.existsSync(mapPath && !compiledFiles.includes(mapPath))) {
+      compiledFiles = compiledFiles.concat(getCompiledFiles(mapPath));
+    }
+  }
+  compilationResult = {
+    config: config,
+    compiledFiles: compiledFiles,
+    stdout: stdout,
+    stderr: stderr
+  };
+  return executePlugins(config, compilationResult);
+};
+
+module.exports = {runPlugins};

package/dist/lib/utils.js

@@ -0,0 +1,48 @@
+// Generated by CoffeeScript 2.7.0
+var consola, fs, getCompiledFiles, path, sleep;
+
+fs = require('fs');
+
+path = require('path');
+
+consola = require('consola');
+
+sleep = function(time) {
+  return new Promise(function(resolve) {
+    return setTimeout(resolve, time);
+  });
+};
+
+getCompiledFiles = function(targetPath) {
+  var error, filesList, i, item, itemPath, items, len, stat;
+  filesList = [];
+  if (!fs.existsSync(targetPath)) {
+    consola.warn(`Path does not exist, skipping scan ${targetPath}`);
+    return [];
+  }
+  try {
+    stat = fs.statSync(targetPath);
+    if (stat.isDirectory()) {
+      consola.start(`Scanning directory: ${targetPath}`);
+      items = fs.readdirSync(targetPath);
+      for (i = 0, len = items.length; i < len; i++) {
+        item = items[i];
+        itemPath = path.join(targetPath, item);
+        filesList = filesList.concat(getCompiledFiles(itemPath));
+      }
+    } else if (stat.isFile()) {
+      if (targetPath.match(/\.js(?:\.map)?$/i)) {
+        if (fs.existsSync(targetPath)) {
+          consola.info(`Found file: \`${targetPath}\``);
+          filesList.push(targetPath);
+        }
+      }
+    }
+  } catch (error1) {
+    error = error1;
+    consola.warn(`Could not scan output path ${targetPath}: ${error.message}`);
+  }
+  return filesList;
+};
+
+module.exports = {sleep, getCompiledFiles};

package/dist/main.js

@@ -5,7 +5,7 @@ yargs = require('yargs');
 
 ({hideBin} = require('yargs/helpers'));
 
-({pkg} = require('./constants'));
+({pkg} = require('./lib/constants'));
 
 setup = require('./commands/setup');
 

package/dist/options/copy.js

@@ -7,12 +7,12 @@ path = require('path');
 
 consola = require('consola');
 
-({CWD} = require('../constants'));
+({CWD} = require('../lib/constants'));
 
 executeCopy = function(config) {
   var copyNonCoffeeFiles, entryPath, error, outputPath, ref, stat;
-  entryPath = path.join(CWD, config.entry);
-  outputPath = path.join(CWD, config.output);
+  entryPath = path.isAbsolute(config.entry) ? config.entry : path.join(CWD, config.entry);
+  outputPath = path.isAbsolute(config.output) ? config.output : path.join(CWD, config.output);
   if (!fs.existsSync(entryPath)) {
     consola.warn(`Entry path does not exist: ${config.entry}`);
     return;

package/dist/options/refresh.js

@@ -9,12 +9,12 @@ crypto = require('crypto');
 
 consola = require('consola');
 
-({CWD} = require('../constants'));
+({CWD} = require('../lib/constants'));
 
 // Execute refresh processing
 executeRefresh = function(config, backupFiles) {
   var backupName, backupPath, dirName, error, fileName, hash, i, item, items, len, originalPath, stat, targetDir;
-  targetDir = path.join(CWD, config.output);
+  targetDir = path.isAbsolute(config.output) ? config.output : path.join(CWD, config.output);
   if (fs.existsSync(targetDir)) {
     stat = fs.statSync(targetDir);
     hash = crypto.randomBytes(4).toString('hex');

package/docs/PLUGIN-ja.md

@@ -71,12 +71,12 @@ module.exports = main
 
 Milkee はコンパイル後にこのオブジェクトをプラグインに渡します：  
 
-| プロパティ      | 型         | 説明                                           |
-| :-------------- | :--------- | :--------------------------------------------- |
-| `config`        | `object`   | `coffee.config.cjs` の設定オブジェクト         |
-| `compiledFiles` | `string[]` | コンパイルされた `.js` と `.js.map` のパス     |
-| `stdout`        | `string`   | コンパイラの標準出力                           |
-| `stderr`        | `string`   | コンパイラの標準エラー                         |
+| プロパティ | 型 | 説明 |
+| :--- | :--- | :--- |
+| `config` | `object` | `coffee.config.cjs` の設定オブジェクト |
+| `compiledFiles` | `string[]` | コンパイルされた `.js` と `.js.map` のパス |
+| `stdout` | `string` | コンパイラの標準出力 |
+| `stderr` | `string` | コンパイラの標準エラー |
 
 ### coffee.config.cjs での使用
 

package/docs/PLUGIN.md

@@ -71,12 +71,12 @@ module.exports = main
 
 Milkee passes this object to your plugin after compilation:  
 
-| Property        | Type       | Description                                    |
-| :-------------- | :--------- | :--------------------------------------------- |
-| `config`        | `object`   | Full config from `coffee.config.cjs`           |
-| `compiledFiles` | `string[]` | Paths to compiled `.js` and `.js.map` files    |
-| `stdout`        | `string`   | Compiler standard output                       |
-| `stderr`        | `string`   | Compiler standard error                        |
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `config` | `object` | Full config from `coffee.config.cjs` |
+| `compiledFiles` | `string[]` | Paths to compiled `.js` and `.js.map` files |
+| `stdout` | `string` | Compiler standard output |
+| `stderr` | `string` | Compiler standard error |
 
 ### Using in coffee.config.cjs
 

package/package.json

@@ -1,14 +1,18 @@
 {
   "name": "milkee",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "A simple CoffeeScript build tool with coffee.config.cjs",
   "main": "dist/main.js",
   "bin": {
     "milkee": "bin/milkee.js"
   },
   "scripts": {
-    "test": "echo \"No test specified\" && exit 0",
-    "build": "coffee --output dist/ --compile --bare src/"
+    "test": "prettier --write ./test && vitest",
+    "test:ci": "vitest --run",
+    "coverage": "vitest --run --coverage",
+    "build": "coffee --output dist/ --compile --bare src/",
+    "format": "node ./scripts/format.js",
+    "deprecate:dev": "node ./scripts/deprecate-dev-versions.js"
   },
   "repository": {
     "type": "git",
@@ -40,6 +44,12 @@
   "devDependencies": {
     "@babel/core": "^7.28.5",
     "@types/coffeescript": "^2.5.7",
-    "coffeescript": "^2.7.0"
+    "@vitest/coverage-v8": "^4.0.17",
+    "coffee-fmt": "^0.12.0",
+    "coffeescript": "^2.7.0",
+    "dotenv": "^17.2.3",
+    "execa": "^9.6.1",
+    "prettier": "^3.8.0",
+    "vitest": "^4.0.17"
   }
 }

package/test/integration/setup.cli.test.js

@@ -0,0 +1,36 @@
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { execFile } = require("child_process");
+
+describe("cli setup integration", () => {
+  it("runs `--setup` and creates coffee.config.cjs", async () => {
+    const dir = createTestDir("cli");
+
+    // run the setup command directly via CoffeeScript so we don't require the ESM-only `yargs` in `main`
+    const scriptPath = require("path").join(
+      process.cwd(),
+      "src",
+      "commands",
+      "setup.coffee",
+    );
+    const csRegister = require.resolve("coffeescript/register");
+    await new Promise((resolve, reject) => {
+      // -r <abs> -> preload CoffeeScript via absolute path so child process can find it
+      execFile(
+        "node",
+        ["-r", csRegister, "-e", `require(${JSON.stringify(scriptPath)})()`],
+        { cwd: dir },
+        (err) => {
+          if (err) return reject(err);
+          resolve();
+        },
+      );
+    });
+
+    const cfgPath = path.join(dir, "coffee.config.cjs");
+    expect(fs.existsSync(cfgPath)).toBe(true);
+
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+});

package/test/setup.js

@@ -0,0 +1,113 @@
+// Register CoffeeScript so tests can require .coffee files
+require("coffeescript/register");
+
+// Test sandbox guard: prevent accidental writes outside a temporary sandbox
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const SANDBOX = fs.mkdtempSync(path.join(os.tmpdir(), "milkee-test-sandbox-"));
+process.env.TEST_SANDBOX = SANDBOX;
+globalThis.TEST_SANDBOX = SANDBOX;
+
+function stripExtendedPrefix(s) {
+  if (typeof s !== "string") return s;
+  // Remove Windows extended path prefix like '\\?\\' or '\?\\'
+  let out = s.replace(/^\\+\?\\/, "");
+  // If we still have a leading backslash before a drive letter (e.g. '\C:\...'), remove it
+  out = out.replace(/^\\+([A-Za-z]:)/, "$1");
+  return out;
+}
+
+// Allowlist: sandbox + system temp + node_modules + any additional paths via TEST_WRITE_ALLOW
+const allowed = [
+  path.resolve(stripExtendedPrefix(SANDBOX)),
+  path.resolve(stripExtendedPrefix(os.tmpdir())),
+  path.resolve(stripExtendedPrefix(process.cwd()), "node_modules"),
+];
+if (process.env.TEST_WRITE_ALLOW) {
+  process.env.TEST_WRITE_ALLOW.split(",").forEach((p) => {
+    if (p) allowed.push(path.resolve(stripExtendedPrefix(p)));
+  });
+}
+
+function resolveSafe(p) {
+  if (!p) return p;
+  // accept Buffers as well
+  if (Buffer.isBuffer(p)) p = p.toString();
+  // strip Windows extended path prefix if present
+  if (typeof p === "string") {
+    p = stripExtendedPrefix(p);
+  }
+  if (!path.isAbsolute(p)) p = path.join(process.cwd(), String(p));
+  return path.resolve(p);
+}
+
+function isAllowed(p) {
+  const rp = resolveSafe(p);
+  return allowed.some(
+    (prefix) => rp === prefix || rp.startsWith(prefix + path.sep),
+  );
+}
+
+function makeGuard(orig, checkIndex = 0) {
+  return function (...args) {
+    const target = args[checkIndex];
+    if (!isAllowed(target)) {
+      throw new Error(
+        `Test attempted to modify outside sandbox: ${target} (sandbox=${SANDBOX})`,
+      );
+    }
+    return orig.apply(this, args);
+  };
+}
+
+// Patch common fs methods that write or modify the FS
+const writeSyncMethods = [
+  "writeFileSync",
+  "appendFileSync",
+  "copyFileSync",
+  "mkdirSync",
+  "rmSync",
+  "rmdirSync",
+  "renameSync",
+  "unlinkSync",
+];
+for (const m of writeSyncMethods) {
+  if (typeof fs[m] === "function") fs[m] = makeGuard(fs[m], 0);
+}
+
+// Async versions
+if (typeof fs.writeFile === "function") {
+  const orig = fs.writeFile;
+  fs.writeFile = function (file, ...rest) {
+    if (!isAllowed(file)) {
+      const cb = rest.find((r) => typeof r === "function");
+      const err = new Error(
+        `Test attempted to modify outside sandbox: ${file} (sandbox=${SANDBOX})`,
+      );
+      if (cb) return process.nextTick(() => cb(err));
+      throw err;
+    }
+    return orig.apply(this, [file, ...rest]);
+  };
+}
+if (fs.promises && typeof fs.promises.writeFile === "function") {
+  const orig = fs.promises.writeFile;
+  fs.promises.writeFile = function (file, ...rest) {
+    if (!isAllowed(file))
+      throw new Error(
+        `Test attempted to modify outside sandbox: ${file} (sandbox=${SANDBOX})`,
+      );
+    return orig.apply(this, [file, ...rest]);
+  };
+}
+
+// Helper for tests to create safe temp dirs
+globalThis.createTestDir = function (name = "") {
+  const dir = path.join(SANDBOX, name || String(Date.now()));
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+};
+
+console.info(`[test setup] test sandbox: ${SANDBOX}`);

package/test/unit/checks.test.js

@@ -0,0 +1,38 @@
+const fs = require("fs");
+const path = require("path");
+const consola = require("consola");
+
+// We re-require the checks module inside tests to allow us to mock dependencies
+// that it captures at require-time.
+
+describe("checks", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+    vi.resetModules();
+  });
+
+  it("checkLatest returns true and shows box when not latest", async () => {
+    vi.mock("is-package-latest", () => ({
+      isPackageLatest: async () => ({
+        success: true,
+        isLatest: false,
+        currentVersion: "1.0.0",
+        latestVersion: "1.2.0",
+      }),
+    }));
+    const { checkLatest } = require("../../src/lib/checks.coffee");
+
+    vi.spyOn(consola, "box").mockImplementation(() => {});
+
+    const res = await checkLatest();
+    expect(res).toBe(true);
+    expect(consola.box).toHaveBeenCalled();
+  });
+
+  it("checkCoffee reads package.json and does not warn when coffeescript present", async () => {
+    const { checkCoffee } = require("../../src/lib/checks.coffee");
+    vi.spyOn(consola, "warn").mockImplementation(() => {});
+    await checkCoffee();
+    expect(consola.warn).not.toHaveBeenCalled();
+  });
+});

package/test/unit/copy.test.js

@@ -0,0 +1,50 @@
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const executeCopy = require("../../src/options/copy.coffee");
+
+function createTree(base) {
+  fs.mkdirSync(base, { recursive: true });
+  fs.writeFileSync(path.join(base, "a.coffee"), "c");
+  fs.writeFileSync(path.join(base, "b.txt"), "b");
+  fs.mkdirSync(path.join(base, "sub"), { recursive: true });
+  fs.writeFileSync(path.join(base, "sub", "c.md"), "c");
+}
+
+describe("copy", () => {
+  it("copies non-coffee files recursively", () => {
+    const base = createTestDir("copy");
+    const entry = path.join(base, "entry");
+    const out = path.join(base, "out");
+    createTree(entry);
+    fs.mkdirSync(out, { recursive: true });
+
+    // preconditions
+    expect(fs.existsSync(entry)).toBe(true);
+    expect(fs.existsSync(path.join(entry, "b.txt"))).toBe(true);
+
+    // use absolute paths (sandboxed)
+    executeCopy({ entry, output: out });
+
+    expect(fs.existsSync(path.join(out, "b.txt"))).toBe(true);
+    expect(fs.existsSync(path.join(out, "sub", "c.md"))).toBe(true);
+    expect(fs.existsSync(path.join(out, "a.coffee"))).toBe(false);
+
+    fs.rmSync(base, { recursive: true, force: true });
+  });
+
+  it("skips when join option is enabled", () => {
+    const base = createTestDir("copy");
+    const entry = path.join(base, "entry");
+    const out = path.join(base, "out");
+    createTree(entry);
+    fs.mkdirSync(out, { recursive: true });
+
+    executeCopy({ entry, output: out, options: { join: true } });
+
+    expect(fs.existsSync(path.join(out, "b.txt"))).toBe(false);
+
+    fs.rmSync(base, { recursive: true, force: true });
+  });
+});

package/test/unit/plugins.test.js

@@ -0,0 +1,50 @@
+const fs = require("fs");
+
+const path = require("path");
+
+const plugins = require("../../src/lib/plugins.coffee");
+
+describe("plugins", () => {
+  it("runPlugins executes provided plugin functions", async () => {
+    let called = false;
+    const tempDir = createTestDir("plugins");
+    // create a dummy compiled file
+    const compiled = path.join(tempDir, "out.js");
+    fs.writeFileSync(compiled, "x");
+
+    const config = {
+      output: tempDir,
+      milkee: {
+        plugins: [
+          (res) => {
+            called = true;
+            return Promise.resolve();
+          },
+        ],
+      },
+    };
+    plugins.runPlugins(config, {});
+
+    // wait a tick for async IIFE to run
+    await new Promise((r) => setTimeout(r, 10));
+    expect(called).toBe(true);
+
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it("warns on invalid plugin entries", async () => {
+    const tempDir = fs.mkdtempSync(
+      path.join(require("os").tmpdir(), "milkee-plugins-"),
+    );
+    const consola = require("consola");
+    vi.spyOn(consola, "warn").mockImplementation(() => {});
+
+    const config = { output: tempDir, milkee: { plugins: ["not-fn"] } };
+    plugins.runPlugins(config, {});
+    await new Promise((r) => setTimeout(r, 10));
+
+    expect(consola.warn).toHaveBeenCalled();
+
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+});

package/test/unit/refresh.test.js

@@ -0,0 +1,63 @@
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const {
+  executeRefresh,
+  restoreBackups,
+  clearBackups,
+} = require("../../src/options/refresh.coffee");
+
+describe("refresh", () => {
+  it("backs up directory files and restores them", () => {
+    const base = createTestDir("refresh");
+    const dir = path.join(base, "out");
+    fs.mkdirSync(dir, { recursive: true });
+    const a = path.join(dir, "a.txt");
+    const b = path.join(dir, "b.txt");
+    fs.writeFileSync(a, "1");
+    fs.writeFileSync(b, "2");
+
+    const backupFiles = [];
+    // preconditions
+    expect(fs.existsSync(dir)).toBe(true);
+    expect(fs.existsSync(a)).toBe(true);
+
+    executeRefresh({ output: dir }, backupFiles);
+
+    expect(backupFiles.length).toBe(2);
+    for (const binfo of backupFiles) {
+      expect(fs.existsSync(binfo.backup)).toBe(true);
+      expect(fs.existsSync(binfo.original)).toBe(false);
+    }
+
+    // restore
+    restoreBackups(backupFiles);
+    for (const binfo of backupFiles) {
+      expect(fs.existsSync(binfo.original)).toBe(true);
+      expect(fs.existsSync(binfo.backup)).toBe(false);
+    }
+
+    // cleanup
+    fs.rmSync(base, { recursive: true, force: true });
+  });
+
+  it("clearBackups removes backup files", () => {
+    const base = createTestDir("refresh");
+    const dir = path.join(base, "out");
+    fs.mkdirSync(dir, { recursive: true });
+    const a = path.join(dir, "a.txt");
+    fs.writeFileSync(a, "1");
+
+    const backupFiles = [];
+    executeRefresh({ output: dir }, backupFiles);
+    expect(backupFiles.length).toBeGreaterThan(0);
+
+    clearBackups(backupFiles);
+    for (const binfo of backupFiles) {
+      expect(fs.existsSync(binfo.backup)).toBe(false);
+    }
+
+    fs.rmSync(base, { recursive: true, force: true });
+  });
+});

package/test/unit/sandbox-windows.test.js

@@ -0,0 +1,14 @@
+const fs = require("fs");
+const path = require("path");
+
+describe("sandbox Windows extended path handling", () => {
+  it("allows writes when path uses \\?\\ prefix (Windows only)", () => {
+    if (process.platform !== "win32") return;
+    const dir = createTestDir("win-prefix");
+    // simulate Windows extended path prefix
+    // use Windows extended path prefix with doubled backslashes
+    const prefixed = "\\\\?\\\\" + path.join(dir, "file.txt");
+    expect(() => fs.writeFileSync(prefixed, "ok")).not.toThrow();
+    expect(fs.existsSync(path.join(dir, "file.txt"))).toBe(true);
+  });
+});

package/test/unit/setup.test.js

@@ -0,0 +1,70 @@
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const setup = require("../../src/commands/setup.coffee");
+const checks = require("../../src/lib/checks.coffee");
+const { CONFIG_FILE } = require("../../src/lib/constants.coffee");
+
+describe("setup", () => {
+  let cwd;
+  beforeEach(() => {
+    cwd = process.cwd();
+    vi.spyOn(checks, "checkCoffee").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    process.chdir(cwd);
+    vi.restoreAllMocks();
+  });
+
+  it("creates config file when not present", async () => {
+    const dir = fs.mkdtempSync(
+      path.join(require("os").tmpdir(), "milkee-setup-"),
+    );
+    process.chdir(dir);
+
+    // re-require to ensure constants.CWD is captured from the new cwd
+    delete require.cache[require.resolve("../../src/lib/constants.coffee")];
+    delete require.cache[require.resolve("../../src/commands/setup.coffee")];
+    const setupLocal = require("../../src/commands/setup.coffee");
+
+    // run setup
+    await setupLocal();
+
+    const cfgPath = path.join(dir, CONFIG_FILE);
+    expect(fs.existsSync(cfgPath)).toBe(true);
+
+    try {
+      fs.rmSync(dir, { recursive: true, force: true });
+    } catch (e) {
+      /* ignore */
+    }
+  });
+
+  it("does not overwrite when prompt says no", async () => {
+    const dir = fs.mkdtempSync(
+      path.join(require("os").tmpdir(), "milkee-setup-"),
+    );
+    process.chdir(dir);
+
+    const cfgPath = path.join(dir, CONFIG_FILE);
+    fs.writeFileSync(cfgPath, "original");
+
+    const consola = require("consola");
+    vi.spyOn(consola, "prompt").mockResolvedValue(false);
+
+    delete require.cache[require.resolve("../../src/lib/constants.coffee")];
+    delete require.cache[require.resolve("../../src/commands/setup.coffee")];
+    const setupLocal = require("../../src/commands/setup.coffee");
+
+    await setupLocal();
+
+    expect(fs.readFileSync(cfgPath, "utf-8")).toBe("original");
+
+    // try cleanup; ignore errors
+    try {
+      fs.rmSync(dir, { recursive: true, force: true });
+    } catch (e) {}
+  });
+});

package/test/unit/src.smoke.test.js

@@ -0,0 +1,56 @@
+const fs = require("fs");
+const path = require("path");
+
+function collectCoffeeFiles(dir) {
+  let out = [];
+  const items = fs.readdirSync(dir);
+  for (const item of items) {
+    const itemPath = path.join(dir, item);
+    const stat = fs.statSync(itemPath);
+    if (stat.isDirectory()) {
+      out = out.concat(collectCoffeeFiles(itemPath));
+    } else if (stat.isFile() && itemPath.endsWith(".coffee")) {
+      out.push(itemPath);
+    }
+  }
+  return out;
+}
+
+const SRC_DIR = path.join(__dirname, "../../src");
+let files = [];
+try {
+  files = collectCoffeeFiles(SRC_DIR);
+} catch (e) {
+  // If src missing for some reason, test will fail explicitly below
+}
+
+// Exclude main.coffee and compile.coffee to avoid executing CLI/long-running flows on require
+files = files.filter((f) => {
+  const excluded = [
+    path.join("src", "main.coffee"),
+    path.join("src", "commands", "compile.coffee"),
+  ];
+  return !excluded.some((e) => f.endsWith(e));
+});
+
+if (files.length === 0) {
+  it("has .coffee files under src", () => {
+    throw new Error("No .coffee files found under src");
+  });
+} else {
+  describe("smoke: require all src .coffee files", () => {
+    for (const file of files) {
+      const rel = path.relative(process.cwd(), file);
+      it(`require ${rel}`, () => {
+        // clear cache to make require deterministic
+        try {
+          delete require.cache[require.resolve(file)];
+        } catch (e) {}
+        expect(() => {
+          const mod = require(file);
+          expect(mod).not.toBeUndefined();
+        }).not.toThrow();
+      });
+    }
+  });
+}

package/test/unit/utils.test.js

@@ -0,0 +1,41 @@
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const utils = require("../../src/lib/utils.coffee");
+
+describe("utils", () => {
+  it("sleep resolves after given time", async () => {
+    vi.useFakeTimers();
+    const p = utils.sleep(100);
+    vi.advanceTimersByTime(100);
+    await vi.runAllTimersAsync();
+    await expect(p).resolves.toBeUndefined();
+    vi.useRealTimers();
+  });
+
+  it("getCompiledFiles finds .js and .js.map files recursively", () => {
+    // create directory inside test sandbox
+    const dir = createTestDir("utils");
+    const fileA = path.join(dir, "a.js");
+    const fileB = path.join(dir, "b.js.map");
+    const fileC = path.join(dir, "c.txt");
+    const subdir = path.join(dir, "sub");
+    fs.mkdirSync(subdir);
+    const fileD = path.join(subdir, "d.js");
+    fs.writeFileSync(fileA, "console.log(1)");
+    fs.writeFileSync(fileB, "map");
+    fs.writeFileSync(fileC, "no");
+    fs.writeFileSync(fileD, "console.log(2)");
+    const res = utils.getCompiledFiles(dir);
+    expect(res).toEqual(expect.arrayContaining([fileA, fileB, fileD]));
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("returns empty if path does not exist", () => {
+    const res = utils.getCompiledFiles(
+      path.join(os.tmpdir(), "nonexistent-" + Date.now()),
+    );
+    expect(res).toEqual([]);
+  });
+});

package/vitest.config.mjs

@@ -0,0 +1,14 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    globals: true,
+    setupFiles: './test/setup.js',
+  },
+  coverage: {
+    provider: 'v8',
+    reporter: ['text', 'lcov'],
+    exclude: ['**/*.coffee']
+  }
+})