create-tooldock-extension 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -17,7 +17,7 @@ npm create tooldock-extension@latest my-tool -- --id my-tool --name "我的工
17
17
  | `view` | 分頁畫面加後端:示範 `invoke`、`emit` 推送、`storage`、對話框、指令、設定與生命週期 |
18
18
  | `service` | 背景服務:隨平台啟動、定時工作、狀態列、暫停與恢復、休眠與喚醒 |
19
19
 
20
- 產生的專案包含 `tooldock-cli`、`tooldock-types`、JSDoc 型別檢查、VS Code 偵錯設定(F5)、`.tbxignore` 和 README。
20
+ 產生的專案包含 `tooldock-cli`、`tooldock-types`、JSDoc 型別檢查、VS Code 偵錯設定(F5)、`.tbxignore`、README,以及 GitHub Actions 自動發佈流程(`.github/workflows/release.yml`:推送 `v*` tag 後自動驗證、打包、簽章並建立 GitHub Release)。
21
21
 
22
22
  參數:
23
23
  - `--no-install`:不自動執行 `npm install`
package/index.js CHANGED
@@ -63,8 +63,8 @@ function render(text, vars) {
63
63
 
64
64
  function copyTemplate(src, dest, vars) {
65
65
  for (const ent of fs.readdirSync(src, { withFileTypes: true })) {
66
- // npm 發佈時會移除 .gitignore 等點檔,範本內以 _ 開頭命名
67
- const name = ent.name.replace(/^_(gitignore|vscode|tbxignore)$/, '.$1');
66
+ // npm 發佈時會移除 .gitignore、.github 等點檔,範本內以 _ 開頭命名
67
+ const name = ent.name.replace(/^_(gitignore|vscode|tbxignore|github)$/, '.$1');
68
68
  const from = path.join(src, ent.name);
69
69
  const to = path.join(dest, name);
70
70
  if (ent.isDirectory()) {
@@ -164,7 +164,7 @@ async function main() {
164
164
  tooldock: manifest(vars, template),
165
165
  dependencies: {},
166
166
  devDependencies: {
167
- 'tooldock-cli': local ? `file:${local.cli}` : '^1.0.0',
167
+ 'tooldock-cli': local ? `file:${local.cli}` : '^1.1.0',
168
168
  'tooldock-types': local ? `file:${local.types}` : '^1.0.0',
169
169
  '@types/node': '^22.0.0',
170
170
  },
@@ -188,6 +188,10 @@ ${bold('下一步')}
188
188
  npm run debug ${dim('同上,並開啟後端偵錯埠 9229(VS Code 按 F5 附加)')}
189
189
  npm run validate ${dim('檢查 manifest')}
190
190
  npm run pack ${dim('打包成 dist/*.tbx')}
191
+
192
+ ${bold('發佈')} ${dim('(GitHub Actions:.github/workflows/release.yml)')}
193
+ npx tooldock-ext keygen ${dim('產生簽章金鑰,私鑰加入 GitHub secret TOOLDOCK_SIGNING_KEY')}
194
+ npm version patch && git push --follow-tags ${dim('推送 v* tag 後自動打包、簽章並建立 Release')}
191
195
  `);
192
196
  }
193
197
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-tooldock-extension",
3
- "version": "1.0.0",
3
+ "version": "1.1.0",
4
4
  "description": "建立 ToolDock 擴充專案:npm create tooldock-extension@latest",
5
5
  "bin": {
6
6
  "create-tooldock-extension": "index.js"
@@ -36,6 +36,61 @@ TOOLDOCK_PATH=/Applications/ToolDock.app npm run dev
36
36
 
37
37
  **日誌**:`ctx.log.*` 和 `console.log` 會顯示在 ToolDock 的輸出面板(`⇧⌘U`),也會顯示在執行 `npm run dev` 的終端機。
38
38
 
39
+ ## 發佈
40
+
41
+ 專案已附上 GitHub Actions 流程 `.github/workflows/release.yml`:推送 `v*` tag 後,會自動驗證、打包、簽章,並建立 GitHub Release。ToolDock 商店會從 Release 下載並驗證簽章。
42
+
43
+ **第一次設定(只需做一次)**
44
+
45
+ 1. 產生簽章金鑰:
46
+
47
+ ```bash
48
+ npx tooldock-ext keygen
49
+ ```
50
+
51
+ 私鑰會存到 `~/.tooldock/keys/tooldock-signing-key.pem`(權限 600),終端機會印出公鑰字串。請另外備份私鑰,**不要提交到 git**。
52
+
53
+ 2. 把私鑰加入 GitHub repo 的 secret `TOOLDOCK_SIGNING_KEY`:
54
+
55
+ ```bash
56
+ gh secret set TOOLDOCK_SIGNING_KEY < ~/.tooldock/keys/tooldock-signing-key.pem
57
+ ```
58
+
59
+ 也可以到 GitHub repo →「Settings → Secrets and variables → Actions」新增,內容貼上私鑰檔的全部文字(包含 `-----BEGIN PRIVATE KEY-----` 那兩行)。
60
+
61
+ 3. 把公鑰字串提交到 ToolDock 商店索引。
62
+ 4. 選用:把公鑰設為 repo variable `TOOLDOCK_PUBLIC_KEY`,CI 發佈前會再驗證一次,可以及早發現 secret 設錯:
63
+
64
+ ```bash
65
+ gh variable set TOOLDOCK_PUBLIC_KEY --body "<公鑰字串>"
66
+ ```
67
+
68
+ **每次發佈**
69
+
70
+ ```bash
71
+ npm version patch # 或 minor / major;會更新 package.json 並建立 v<版本> tag
72
+ git push --follow-tags
73
+ ```
74
+
75
+ tag 必須是 `v` 加上 `package.json` 的版本(例如 `v0.2.0`),不一致時 CI 會失敗。`package-lock.json` 必須提交,CI 使用 `npm ci` 安裝。
76
+
77
+ Release 會附上三個檔案:
78
+
79
+ | 檔案 | 內容 |
80
+ |---|---|
81
+ | `{{id}}-<版本>.tbx` | 擴充套件 |
82
+ | `{{id}}-<版本>.tbx.sha256` | `.tbx` 的 SHA-256 |
83
+ | `{{id}}-<版本>.tbx.sig` | Ed25519 簽章 |
84
+
85
+ 沒有設定 `TOOLDOCK_SIGNING_KEY` 時,CI 仍會發佈 `.tbx` 和 `.sha256`,但會顯示「未簽章,商店不會收錄」的警告。
86
+
87
+ **在本機簽章與驗證**
88
+
89
+ ```bash
90
+ npx tooldock-ext pack --sign --key ~/.tooldock/keys/tooldock-signing-key.pem
91
+ npx tooldock-ext verify dist/{{id}}-<版本>.tbx --public-key <公鑰字串>
92
+ ```
93
+
39
94
  ## 專案結構
40
95
 
41
96
  ```
@@ -43,6 +98,7 @@ package.json manifest(tooldock 欄位:畫面、指令、設定、生命
43
98
  backend/index.js 後端:activate(ctx) / deactivate()
44
99
  ui/ 畫面(如果有)
45
100
  .tbxignore 打包時要排除的檔案
101
+ .github/workflows/release.yml 推送 v* tag 時自動發佈
46
102
  ```
47
103
 
48
104
  ## 加入函式庫
@@ -0,0 +1,114 @@
1
+ # 推送 v* tag 時自動驗證、打包、簽章並建立 GitHub Release
2
+ #
3
+ # npm version patch # 更新 package.json 版本並建立 v<版本> tag
4
+ # git push --follow-tags
5
+ #
6
+ # 需要的設定(GitHub repo → Settings → Secrets and variables → Actions):
7
+ # Secret TOOLDOCK_SIGNING_KEY 簽章私鑰(tooldock-ext keygen 產生的 PEM 檔完整內容)
8
+ # Variable TOOLDOCK_PUBLIC_KEY 選用:公鑰字串,設定後發佈前會再驗證一次簽章
9
+ #
10
+ # 沒有設定 TOOLDOCK_SIGNING_KEY 時仍會發佈 .tbx 與 .sha256,但未簽章,商店不會收錄。
11
+ # 詳細說明見本專案 README 的「發佈」一節,以及 ToolDock repo 的 docs/RELEASE.md。
12
+
13
+ name: Release
14
+
15
+ on:
16
+ push:
17
+ tags:
18
+ - 'v*'
19
+
20
+ permissions:
21
+ contents: write
22
+
23
+ concurrency:
24
+ group: release-${{ github.ref }}
25
+ cancel-in-progress: false
26
+
27
+ jobs:
28
+ release:
29
+ runs-on: ubuntu-latest
30
+ steps:
31
+ - uses: actions/checkout@v5
32
+
33
+ - uses: actions/setup-node@v5
34
+ with:
35
+ node-version: 22
36
+ cache: npm
37
+
38
+ - name: 安裝相依套件
39
+ run: npm ci
40
+
41
+ - name: 驗證 manifest
42
+ run: npm run validate
43
+
44
+ - name: 檢查 tag 與 package.json 版本一致
45
+ id: meta
46
+ run: |
47
+ VERSION="$(node -p "require('./package.json').version")"
48
+ ID="$(node -p "require('./package.json').tooldock.id")"
49
+ if [ "$GITHUB_REF_NAME" != "v$VERSION" ]; then
50
+ echo "::error title=版本不一致::tag 是 $GITHUB_REF_NAME,但 package.json 的版本是 $VERSION(tag 應為 v$VERSION)。請用 npm version 更新版本後重新建立 tag。"
51
+ exit 1
52
+ fi
53
+ echo "version=$VERSION" >> "$GITHUB_OUTPUT"
54
+ echo "id=$ID" >> "$GITHUB_OUTPUT"
55
+ echo "tbx=dist/$ID-$VERSION.tbx" >> "$GITHUB_OUTPUT"
56
+
57
+ - name: 打包並簽章
58
+ id: pack
59
+ env:
60
+ TOOLDOCK_SIGNING_KEY: ${{ secrets.TOOLDOCK_SIGNING_KEY }}
61
+ run: |
62
+ rm -rf dist
63
+ if [ -n "$TOOLDOCK_SIGNING_KEY" ]; then
64
+ npx tooldock-ext pack --sign
65
+ echo "signed=true" >> "$GITHUB_OUTPUT"
66
+ else
67
+ echo "::warning title=未簽章,商店不會收錄::沒有設定 secret TOOLDOCK_SIGNING_KEY,這次只會發佈 .tbx 與 .sha256。請執行 npx tooldock-ext keygen 產生金鑰並把私鑰加入 secret。"
68
+ npx tooldock-ext pack --checksum
69
+ echo "signed=false" >> "$GITHUB_OUTPUT"
70
+ fi
71
+
72
+ - name: 以公鑰驗證簽章
73
+ if: steps.pack.outputs.signed == 'true' && vars.TOOLDOCK_PUBLIC_KEY != ''
74
+ env:
75
+ TOOLDOCK_PUBLIC_KEY: ${{ vars.TOOLDOCK_PUBLIC_KEY }}
76
+ TBX: ${{ steps.meta.outputs.tbx }}
77
+ run: npx tooldock-ext verify "$TBX"
78
+
79
+ - name: 建立 GitHub Release
80
+ env:
81
+ GH_TOKEN: ${{ github.token }}
82
+ TBX: ${{ steps.meta.outputs.tbx }}
83
+ VERSION: ${{ steps.meta.outputs.version }}
84
+ SIGNED: ${{ steps.pack.outputs.signed }}
85
+ run: |
86
+ FILES=("$TBX" "$TBX.sha256")
87
+ if [ "$SIGNED" = "true" ]; then FILES+=("$TBX.sig"); fi
88
+ for f in "${FILES[@]}"; do
89
+ [ -f "$f" ] || { echo "::error::找不到發佈檔 $f"; exit 1; }
90
+ done
91
+
92
+ FLAGS=()
93
+ # 版本含 - (例如 1.2.0-beta.1)視為預先發行版
94
+ case "$VERSION" in *-*) FLAGS+=(--prerelease) ;; esac
95
+
96
+ if gh release view "$GITHUB_REF_NAME" > /dev/null 2>&1; then
97
+ echo "Release $GITHUB_REF_NAME 已存在,覆寫附件"
98
+ gh release upload "$GITHUB_REF_NAME" "${FILES[@]}" --clobber
99
+ else
100
+ gh release create "$GITHUB_REF_NAME" "${FILES[@]}" \
101
+ --verify-tag \
102
+ --title "$GITHUB_REF_NAME" \
103
+ --generate-notes \
104
+ "${FLAGS[@]}"
105
+ fi
106
+
107
+ {
108
+ echo "### 已發佈 $GITHUB_REF_NAME"
109
+ for f in "${FILES[@]}"; do echo "- \`$(basename "$f")\`"; done
110
+ if [ "$SIGNED" != "true" ]; then
111
+ echo ""
112
+ echo "> ⚠️ 未簽章,商店不會收錄。請設定 secret \`TOOLDOCK_SIGNING_KEY\` 後重新發佈。"
113
+ fi
114
+ } >> "$GITHUB_STEP_SUMMARY"
@@ -2,3 +2,5 @@ node_modules/
2
2
  dist/
3
3
  *.tbx
4
4
  .DS_Store
5
+ # 簽章私鑰,絕不提交
6
+ tooldock-signing-key*.pem