milkee 2.4.0 → 2.4.2

package/dist/commands/plugin.js

@@ -1,5 +1,5 @@
 // Generated by CoffeeScript 2.7.0
-var CONFIG_FILE, CWD, PLUGIN_KEYWORDS, TEMPLATES, TEMPLATE_DIR, confirmContinue, consola, copyTemplate, ensureDir, execSync, fs, generateReadme, initPackageJson, path, plugin, updatePackageJson,
+var CONFIG_FILE, CWD, DOCS, DOCS_DIR, PLUGIN_KEYWORDS, TEMPLATES, TEMPLATE_DIR, confirmContinue, consola, copyDocs, copyTemplate, ensureDir, execSync, fs, generateReadme, initPackageJson, path, plugin, updatePackageJson,
   indexOf = [].indexOf;
 
 fs = require('fs');
@@ -16,6 +16,8 @@ confirmContinue = require('../options/confirm');
 
 TEMPLATE_DIR = path.join(__dirname, '..', '..', 'temp', 'plugin');
 
+DOCS_DIR = path.join(__dirname, '..', '..', 'docs');
+
 TEMPLATES = [
   {
     src: 'main.coffee',
@@ -43,6 +45,17 @@ TEMPLATES = [
   }
 ];
 
+DOCS = [
+  {
+    src: 'PLUGIN.md',
+    dest: 'docs/PLUGIN.md'
+  },
+  {
+    src: 'PLUGIN-ja.md',
+    dest: 'docs/PLUGIN-ja.md'
+  }
+];
+
 // Create directory if not exists
 ensureDir = function(filePath) {
   var dir;
@@ -70,6 +83,22 @@ copyTemplate = function(src, dest) {
   return true;
 };
 
+// Copy docs file
+copyDocs = function(src, dest) {
+  var content, destPath, srcPath;
+  srcPath = path.join(DOCS_DIR, src);
+  destPath = path.join(CWD, dest);
+  if (!fs.existsSync(srcPath)) {
+    consola.error(`Docs file not found: ${srcPath}`);
+    return false;
+  }
+  ensureDir(destPath);
+  content = fs.readFileSync(srcPath, 'utf-8');
+  fs.writeFileSync(destPath, content);
+  consola.success(`Created \`${dest}\``);
+  return true;
+};
+
 PLUGIN_KEYWORDS = ['milkee', 'coffeescript', 'coffee', 'ext', 'plugin', 'milkee-plugin'];
 
 // Update package.json
@@ -158,7 +187,7 @@ generateReadme = function() {
 
 // Main plugin setup function
 plugin = async function() {
-  var confirmed, destPath, error, i, j, len, len1, overwrite, pkgPath, readmePath, template;
+  var confirmed, destPath, doc, error, i, j, k, l, len, len1, len2, len3, overwrite, pkgPath, readmePath, template;
   consola.box("Milkee Plugin Setup");
   consola.info("This will set up your project as a Milkee plugin.");
   consola.info("");
@@ -173,8 +202,13 @@ plugin = async function() {
     template = TEMPLATES[i];
     consola.info(`     - ${template.dest}`);
   }
-  consola.info("  3. Update package.json (main, scripts, keywords)");
-  consola.info("  4. Generate README.md");
+  consola.info("  3. Copy docs:");
+  for (j = 0, len1 = DOCS.length; j < len1; j++) {
+    doc = DOCS[j];
+    consola.info(`     - ${doc.dest}`);
+  }
+  consola.info("  4. Update package.json (main, scripts, keywords)");
+  consola.info("  5. Generate README.md");
   consola.info("");
   // Confirm before proceeding
   confirmed = (await confirmContinue());
@@ -206,8 +240,8 @@ plugin = async function() {
   consola.info("");
   // Create template files
   consola.start("Creating template files...");
-  for (j = 0, len1 = TEMPLATES.length; j < len1; j++) {
-    template = TEMPLATES[j];
+  for (k = 0, len2 = TEMPLATES.length; k < len2; k++) {
+    template = TEMPLATES[k];
     destPath = path.join(CWD, template.dest);
     if (fs.existsSync(destPath)) {
       overwrite = (await consola.prompt(`${template.dest} already exists. Overwrite?`, {
@@ -221,6 +255,23 @@ plugin = async function() {
     copyTemplate(template.src, template.dest);
   }
   consola.info("");
+  // Copy docs
+  consola.start("Copying docs...");
+  for (l = 0, len3 = DOCS.length; l < len3; l++) {
+    doc = DOCS[l];
+    destPath = path.join(CWD, doc.dest);
+    if (fs.existsSync(destPath)) {
+      overwrite = (await consola.prompt(`${doc.dest} already exists. Overwrite?`, {
+        type: "confirm"
+      }));
+      if (!overwrite) {
+        consola.info(`Skipped \`${doc.dest}\``);
+        continue;
+      }
+    }
+    copyDocs(doc.src, doc.dest);
+  }
+  consola.info("");
   // Update package.json
   consola.start("Updating package.json...");
   updatePackageJson();

package/docs/PLUGIN-ja.md

@@ -0,0 +1,143 @@
+# Milkee プラグインの作成
+
+カスタムプラグインで Milkee の機能を拡張できます。  
+
+## クイックスタート
+
+`-p` (`--plugin`) コマンドでプラグインプロジェクトをセットアップ：  
+
+```bash
+# グローバル
+milkee -p
+
+# ローカル
+npx milkee -p
+```
+
+以下が実行されます：
+1. `package.json` の初期化（必要な場合）
+2. 依存関係のインストール (`consola`, `coffeescript`, `milkee`)
+3. テンプレートファイルの作成
+4. `package.json` の更新 (`main`, `scripts`, `keywords`)
+
+## プロジェクト構造
+
+```
+your-plugin/
+  src/
+    main.coffee    # プラグインのソース
+  dist/
+    main.js        # コンパイル後の出力
+  .github/
+    workflows/
+      publish.yml  # npm公開ワークフロー
+  coffee.config.cjs
+  package.json
+```
+
+## プラグインの書き方
+
+### 基本テンプレート
+
+```coffee
+fs = require 'fs'
+path = require 'path'
+consola = require 'consola'
+
+pkg = require '../package.json'
+PREFIX = "[#{pkg.name}]"
+
+# プレフィックス付きカスタムロガー
+c = {}
+for method in ['log', 'info', 'success', 'warn', 'error', 'debug', 'start', 'box']
+  do (method) ->
+    c[method] = (args...) ->
+      if typeof args[0] is 'string'
+        args[0] = "#{PREFIX} #{args[0]}"
+      consola[method] args...
+
+# メインプラグイン関数
+main = (compilationResult) ->
+  { config, compiledFiles, stdout, stderr } = compilationResult
+
+  c.info "#{compiledFiles.length} ファイルをコンパイルしました"
+  for file in compiledFiles
+    c.log "  - #{file}"
+
+module.exports = main
+```
+
+### コンパイル結果
+
+Milkee はコンパイル後にこのオブジェクトをプラグインに渡します：  
+
+| プロパティ      | 型         | 説明                                           |
+| :-------------- | :--------- | :--------------------------------------------- |
+| `config`        | `object`   | `coffee.config.cjs` の設定オブジェクト         |
+| `compiledFiles` | `string[]` | コンパイルされた `.js` と `.js.map` のパス     |
+| `stdout`        | `string`   | コンパイラの標準出力                           |
+| `stderr`        | `string`   | コンパイラの標準エラー                         |
+
+### coffee.config.cjs での使用
+
+```js
+const myPlugin = require('your-plugin-name');
+
+module.exports = {
+  entry: 'src',
+  output: 'dist',
+  milkee: {
+    plugins: [
+      myPlugin({ customOption: 'value' }),
+    ]
+  }
+};
+```
+
+## ビルド & テスト
+
+```bash
+# プラグインをビルド
+npm run build
+
+# ローカルテスト用にリンク
+npm link
+
+# 別のプロジェクトで
+npm link your-plugin-name
+```
+
+## 公開
+
+### GitHub Actions を使用
+
+同梱のワークフローで npm に手動公開：  
+
+1. リポジトリに `NPM_TOKEN` シークレットを追加
+2. **Actions** → **Manual Publish to npm** に移動
+3. **Run workflow** をクリック
+
+### 手動
+
+```bash
+npm run build
+npm publish --access public
+```
+
+## ベストプラクティス
+
+### 命名規則 & キーワード
+
+- 名前: `milkee-plugin-xxx` または `@yourname/milkee-plugin-xxx`
+- キーワード（自動追加）: `milkee`, `coffeescript`, `coffee`, `ext`, `plugin`, `milkee-plugin`
+
+### エラーハンドリング
+
+```coffee
+main = (compilationResult) ->
+  try
+    # ロジック
+  catch error
+    c.error "失敗:", error.message
+    throw error
+```

package/docs/PLUGIN.md

@@ -0,0 +1,143 @@
+# Creating a Milkee Plugin
+
+Extend Milkee's functionality with custom plugins.  
+
+## Quick Start
+
+Run `-p` (`--plugin`) command to set up your plugin project:  
+
+```bash
+# global
+milkee -p
+
+# or local
+npx milkee -p
+```
+
+This will:
+1. Initialize `package.json` (if needed)
+2. Install dependencies (`consola`, `coffeescript`, `milkee`)
+3. Create template files
+4. Update `package.json` (`main`, `scripts`, `keywords`)
+
+## Project Structure
+
+```
+your-plugin/
+  src/
+    main.coffee    # Your plugin source
+  dist/
+    main.js        # Compiled output
+  .github/
+    workflows/
+      publish.yml  # npm publish workflow
+  coffee.config.cjs
+  package.json
+```
+
+## Writing Your Plugin
+
+### Basic Template
+
+```coffee
+fs = require 'fs'
+path = require 'path'
+consola = require 'consola'
+
+pkg = require '../package.json'
+PREFIX = "[#{pkg.name}]"
+
+# Custom logger with prefix
+c = {}
+for method in ['log', 'info', 'success', 'warn', 'error', 'debug', 'start', 'box']
+  do (method) ->
+    c[method] = (args...) ->
+      if typeof args[0] is 'string'
+        args[0] = "#{PREFIX} #{args[0]}"
+      consola[method] args...
+
+# Main plugin function
+main = (compilationResult) ->
+  { config, compiledFiles, stdout, stderr } = compilationResult
+
+  c.info "Compiled #{compiledFiles.length} file(s)"
+  for file in compiledFiles
+    c.log "  - #{file}"
+
+module.exports = main
+```
+
+### Compilation Result
+
+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                        |
+
+### Using in coffee.config.cjs
+
+```js
+const myPlugin = require('your-plugin-name');
+
+module.exports = {
+  entry: 'src',
+  output: 'dist',
+  milkee: {
+    plugins: [
+      myPlugin({ customOption: 'value' }),
+    ]
+  }
+};
+```
+
+## Build & Test
+
+```bash
+# Build your plugin
+npm run build
+
+# Link for local testing
+npm link
+
+# In another project
+npm link your-plugin-name
+```
+
+## Publishing
+
+### Using GitHub Actions
+
+The included workflow publishes to npm manually:  
+
+1. Add `NPM_TOKEN` secret to your repository
+2. Go to **Actions** → **Manual Publish to npm**
+3. Click **Run workflow**
+
+### Manual
+
+```bash
+npm run build
+npm publish --access public
+```
+
+## Best Practices
+
+### Naming & Keywords
+
+- Name: `milkee-plugin-xxx` or `@yourname/milkee-plugin-xxx`
+- Keywords (auto-added): `milkee`, `coffeescript`, `coffee`, `ext`, `plugin`, `milkee-plugin`
+
+### Error Handling
+
+```coffee
+main = (compilationResult) ->
+  try
+    # Your logic
+  catch error
+    c.error "Failed:", error.message
+    throw error
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "milkee",
-  "version": "2.4.0",
+  "version": "2.4.2",
   "description": "A simple CoffeeScript build tool with coffee.config.cjs",
   "main": "dist/main.js",
   "bin": {

package/temp/plugin/_gitignore

@@ -1,2 +1,3 @@
 node_modules/
+docs/
 .env