@dac-tech-team-tw/gtm-cli 0.0.0-stage → 1.7.1

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.
Files changed (5) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +186 -2
  3. package/bin/gtm +44 -0
  4. package/install.js +77 -0
  5. package/package.json +44 -4
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 owntag
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,187 @@
1
- # Temporary Holding Version
1
+ # GTM CLI
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ GTM CLI 是以 Deno 和 Cliffy 建立的 Google Tag Manager 命令列工具。這個分支由 [dac-tech-team-tw](https://github.com/dac-tech-team-tw/gtm-cli) 維護,源自 [owntag/gtm-cli](https://github.com/owntag/gtm-cli)。可用來管理帳戶、容器、工作區及代碼等資源,也適合自動化與 CI/CD。
4
+
5
+ ## 安裝
6
+
7
+ 預先編譯的發行檔支援 macOS Apple Silicon/Intel、Linux x64 與 Windows x64。安裝腳本和 npm 安裝都需要本分支已有相應的 GitHub Release 資產。
8
+
9
+ ### macOS / Linux
10
+
11
+ ```bash
12
+ curl -fsSL https://raw.githubusercontent.com/dac-tech-team-tw/gtm-cli/main/install.sh | bash
13
+ ```
14
+
15
+ ### Windows x64
16
+
17
+ 在 PowerShell 執行:
18
+
19
+ ```powershell
20
+ irm https://raw.githubusercontent.com/dac-tech-team-tw/gtm-cli/main/install.ps1 | iex
21
+ ```
22
+
23
+ 腳本將 `gtm.exe` 安裝至 `%LOCALAPPDATA%\Programs\gtm`,並加入使用者 PATH;若其他終端機尚未取得新的 PATH,請重新開啟終端機。
24
+
25
+ ### npm
26
+
27
+ `@dac-tech-team-tw/gtm-cli` 已發布至 npm。安裝時會下載套件版本對應的 GitHub Release 二進位檔,因此該版本的 Release 資產必須存在。
28
+
29
+ ```bash
30
+ npm install -g @dac-tech-team-tw/gtm-cli
31
+ # 或指定已發布的版本
32
+ npm install -g @dac-tech-team-tw/gtm-cli@<版本>
33
+ ```
34
+
35
+ ### 手動下載或從原始碼建置
36
+
37
+ 從本分支的 [GitHub Releases](https://github.com/dac-tech-team-tw/gtm-cli/releases) 下載對應檔案:
38
+
39
+ | 平台 | 檔案 |
40
+ | --- | --- |
41
+ | macOS Apple Silicon | `gtm-darwin-arm64` |
42
+ | macOS Intel | `gtm-darwin-x64` |
43
+ | Linux x64 | `gtm-linux-x64` |
44
+ | Windows x64 | `gtm-windows-x64.exe` |
45
+
46
+ macOS/Linux 可將下載檔重新命名為 `gtm`、使用 `chmod +x gtm` 賦予執行權限,再移至 PATH 中的目錄。Windows 可將檔案命名為 `gtm.exe` 並放入 PATH。
47
+
48
+ 安裝 [Deno 2](https://deno.com/) 後,也可自行建置:
49
+
50
+ ```bash
51
+ git clone https://github.com/dac-tech-team-tw/gtm-cli.git
52
+ cd gtm-cli
53
+ deno task compile
54
+ ```
55
+
56
+ 產生的執行檔為 `gtm`(Windows 為 `gtm.exe`)。原始碼建置的 OAuth 憑證需自行提供,詳見下方認證說明。
57
+
58
+ ## 認證
59
+
60
+ ### 瀏覽器 OAuth
61
+
62
+ ```bash
63
+ gtm auth login
64
+ gtm auth status
65
+ ```
66
+
67
+ 登入流程會開啟瀏覽器,並使用 `http://localhost:8085/callback` 接收回呼。使用的 Google 帳戶必須具備所需的 GTM 權限。
68
+
69
+ 自行建置或執行原始碼時,請在 Google Cloud 專案啟用 Tag Manager API,建立 OAuth 2.0 用戶端並設定 `GOOGLE_CLIENT_ID`、`GOOGLE_CLIENT_SECRET`。若使用 Web application 類型,請將上述回呼網址加入授權重新導向 URI。執行 `deno task start` 時也可在專案根目錄的 `.env` 提供這些變數;已編譯程式則可使用執行環境變數。發行建置可由維護者在 CI 中嵌入用戶端憑證。
70
+
71
+ ### 服務帳戶
72
+
73
+ 啟用 Tag Manager API,建立服務帳戶及 JSON 金鑰,並在 GTM 中授予該服務帳戶所需的帳戶或容器權限:
74
+
75
+ ```bash
76
+ gtm auth login --service-account /path/to/key.json
77
+ # 或設定環境變數,供後續指令使用
78
+ export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json
79
+ gtm accounts list
80
+ ```
81
+
82
+ PowerShell 使用 `$env:GOOGLE_APPLICATION_CREDENTIALS = 'C:\path\to\key.json'`。此環境變數優先於其他認證方式;妥善保管金鑰,不要提交至版本庫。
83
+
84
+ ```bash
85
+ gtm auth status
86
+ gtm auth logout
87
+ ```
88
+
89
+ 登出會清除已儲存的認證設定;服務帳戶金鑰檔不會被刪除,環境變數也不會被清除。
90
+
91
+ ## 快速開始與設定
92
+
93
+ ```bash
94
+ gtm --help
95
+ gtm accounts list
96
+ gtm containers list --account-id 123456
97
+ gtm workspaces list --account-id 123456 --container-id 789
98
+ gtm tags list --account-id 123456 --container-id 789 --workspace-id 1
99
+ ```
100
+
101
+ 可先執行互動式設定選擇預設帳戶、容器及工作區:
102
+
103
+ ```bash
104
+ gtm config setup
105
+ gtm config get
106
+ gtm config set defaultAccountId 123456
107
+ gtm config set defaultContainerId 789
108
+ gtm config set defaultWorkspaceId 1
109
+ gtm config unset defaultWorkspaceId
110
+ ```
111
+
112
+ 可設定的鍵為 `defaultAccountId`、`defaultContainerId`、`defaultWorkspaceId` 和 `outputFormat`(`table`、`json`、`compact`)。各指令支援的選項與預設值可能不同,請用 `--help` 確認;部分操作即使設定預設值,仍要求明確提供資源 ID。
113
+
114
+ 設定與認證檔預設位於 macOS/Linux 的 `~/.config/gtm-cli`,Windows 的 `%APPDATA%\gtm-cli`;可用 `GTM_CLI_CONFIG_DIR` 覆寫,也支援 `XDG_CONFIG_HOME`。請保護這些檔案中的憑證。
115
+
116
+ ## 常用指令
117
+
118
+ 以下假設已設定適當的預設帳戶、容器與工作區。實際可用操作及必要參數請參閱各指令的 `--help`。
119
+
120
+ ```bash
121
+ # 容器與工作區
122
+ gtm containers list
123
+ gtm containers create --name "My Container" --type web
124
+ gtm workspaces list
125
+ gtm workspaces create --name "Feature Branch"
126
+ gtm workspaces status --workspace-id 1
127
+
128
+ # 工作區資源
129
+ gtm tags list --output json
130
+ gtm tags get --tag-id 42
131
+ gtm triggers list
132
+ gtm variables list
133
+ gtm folders list
134
+
135
+ # 容器版本:發布會變更正式環境
136
+ gtm version-headers list
137
+ gtm versions live
138
+ gtm versions create --name "Release"
139
+ gtm versions publish --version-id 42
140
+ ```
141
+
142
+ 其他指令群組包括 `environments`、`built-in-variables`、`clients`、`templates`、`transformations`、`zones`、`destinations`、`gtag-configs` 與 `user-permissions`。使用 `gtm <指令> --help` 查看操作;`gtm agent guide` 提供代理程式使用指南。許多清單或查詢指令接受 `--output json`、`table` 或 `compact`;`--quiet` 可減少非必要輸出,`--no-color` 可停用色彩。
143
+
144
+ 要傳 JSON 或 `.tpl` 範本時,建議先儲存成 UTF-8 檔,再用 `--config-file`、`--container-access-file` 或 `--template-data-file` 傳檔案路徑,避免 shell 引號和命令列長度限制。檔案旗標不可與對應的行內旗標同時使用。
145
+
146
+ Windows PowerShell 5.1 寫檔請用 `Set-Content -Encoding UTF8`;預設的 `Set-Content` 和 `>` 可能產生非 UTF-8 檔案。
147
+
148
+ ```bash
149
+ gtm upgrade --check
150
+ gtm upgrade
151
+ ```
152
+
153
+ `upgrade` 可檢查或安裝較新版本;升級依賴對應平台的 Release 資產。
154
+
155
+ ## 開發
156
+
157
+ 需要 Deno 2。從專案目錄執行:
158
+
159
+ ```bash
160
+ deno task start --help # 執行 CLI
161
+ deno task dev # 監看檔案並執行
162
+ deno task check # 型別檢查
163
+ deno task lint # 靜態檢查
164
+ deno task fmt # 格式化
165
+ deno task compile # 建置目前平台的執行檔
166
+ ```
167
+
168
+ `deno.json` 是 CLI 版本來源。需要 OAuth 時,請依認證章節設定本機環境變數或 `.env`;勿將憑證提交至版本庫。
169
+
170
+ ## 發行與 npm trusted publishing
171
+
172
+ 維護者可在乾淨的 `main` 分支執行以下其中一項(此操作會推送至 `origin`):
173
+
174
+ ```bash
175
+ deno task release patch
176
+ deno task release minor
177
+ deno task release major
178
+ deno task release 2.0.0
179
+ ```
180
+
181
+ 腳本會拉取 `origin/main`、同步更新 `deno.json` 與 `npm/package.json` 的版本、執行型別檢查、建立提交與 `v` 標籤,並推送分支及標籤。標籤會觸發 `.github/workflows/release.yml`,建置各平台二進位檔、建立 GitHub Release,並在資產上傳後透過 OIDC 發布 npm 套件。若要讓發行檔支援內建 OAuth,須先在 GitHub repository secrets 設定 `GOOGLE_CLIENT_ID` 與 `GOOGLE_CLIENT_SECRET`;請使用本分支自己的 Google OAuth 用戶端。
182
+
183
+ npm 發布前,維護者須擁有 `@dac-tech-team-tw` scope 的發布權限。在 npm 套件設定中新增 GitHub Actions trusted publisher,指定擁有者 `dac-tech-team-tw`、儲存庫 `gtm-cli` 與工作流程檔名 `release.yml`,並允許直接執行 `npm publish`;若工作流程使用受保護環境,也須指定相符的環境。新設定須在兩天內成功發布一次,否則會過期。OIDC 發布需要工作流程具備 `id-token: write` 權限及支援 trusted publishing 的 npm 版本。發布前亦須確認 npm 套件版本與 GitHub Release 資產相符。
184
+
185
+ ## 授權與致謝
186
+
187
+ 本專案採用 [MIT License](LICENSE)。原始專案由 owntag 建立;保留原始版權聲明:Copyright (c) 2026 owntag。使用、修改或散布時請遵守授權條款並保留所需的版權與授權聲明。
package/bin/gtm ADDED
@@ -0,0 +1,44 @@
1
+ #!/usr/bin/env node
2
+
3
+ /**
4
+ * GTM CLI wrapper script
5
+ *
6
+ * This script runs the downloaded binary. If the binary doesn't exist,
7
+ * it will attempt to download it first.
8
+ */
9
+
10
+ const { spawn, spawnSync } = require("child_process");
11
+ const fs = require("fs");
12
+ const path = require("path");
13
+
14
+ const BIN_NAME = process.platform === "win32" ? "gtm-binary.exe" : "gtm-binary";
15
+ const BIN_PATH = path.join(__dirname, BIN_NAME);
16
+ const INSTALL_SCRIPT = path.join(__dirname, "..", "install.js");
17
+
18
+ // Check if the binary exists
19
+ if (!fs.existsSync(BIN_PATH)) {
20
+ console.error("GTM CLI binary not found. Running install script...");
21
+ const install = spawnSync(process.execPath, [INSTALL_SCRIPT], { stdio: "inherit" });
22
+ if (install.error || install.status !== 0) {
23
+ if (install.error) console.error(`Failed to run installer: ${install.error.message}`);
24
+ process.exit(install.status || 1);
25
+ }
26
+ }
27
+
28
+ // Run the binary with all arguments
29
+ const child = spawn(BIN_PATH, process.argv.slice(2), {
30
+ stdio: "inherit",
31
+ });
32
+
33
+ child.on("close", (code, signal) => {
34
+ if (signal) {
35
+ process.kill(process.pid, signal);
36
+ } else {
37
+ process.exit(code ?? 1);
38
+ }
39
+ });
40
+
41
+ child.on("error", (error) => {
42
+ console.error(`Failed to run GTM CLI: ${error.message}`);
43
+ process.exit(1);
44
+ });
package/install.js ADDED
@@ -0,0 +1,77 @@
1
+ #!/usr/bin/env node
2
+
3
+ // Download the binary corresponding to this package's exact version.
4
+ const https = require("https");
5
+ const fs = require("fs");
6
+ const path = require("path");
7
+ const { pipeline } = require("stream");
8
+ const { promisify } = require("util");
9
+
10
+ const REPO = "dac-tech-team-tw/gtm-cli";
11
+ const BIN_DIR = path.join(__dirname, "bin");
12
+ const BIN_PATH = path.join(BIN_DIR, process.platform === "win32" ? "gtm-binary.exe" : "gtm-binary");
13
+ const streamPipeline = promisify(pipeline);
14
+
15
+ function getBinaryName() {
16
+ const target = `${process.platform}-${process.arch}`;
17
+ const binaries = {
18
+ "darwin-x64": "gtm-darwin-x64",
19
+ "darwin-arm64": "gtm-darwin-arm64",
20
+ "linux-x64": "gtm-linux-x64",
21
+ "win32-x64": "gtm-windows-x64.exe",
22
+ };
23
+ if (!binaries[target]) {
24
+ throw new Error(`Unsupported platform: ${target}. Supported: ${Object.keys(binaries).join(", ")}.`);
25
+ }
26
+ return binaries[target];
27
+ }
28
+
29
+ function download(url, dest, redirects = 0) {
30
+ return new Promise((resolve, reject) => {
31
+ https.get(url, (response) => {
32
+ if ([301, 302, 303, 307, 308].includes(response.statusCode)) {
33
+ const location = response.headers.location;
34
+ response.resume();
35
+ if (!location || redirects >= 10) {
36
+ reject(new Error("Invalid or excessive download redirects"));
37
+ return;
38
+ }
39
+ const next = new URL(location, url);
40
+ if (next.protocol !== "https:") {
41
+ reject(new Error("Refusing non-HTTPS download redirect"));
42
+ return;
43
+ }
44
+ resolve(download(next, dest, redirects + 1));
45
+ return;
46
+ }
47
+ if (response.statusCode !== 200) {
48
+ response.resume();
49
+ reject(new Error(`Failed to download: HTTP ${response.statusCode}`));
50
+ return;
51
+ }
52
+ resolve(streamPipeline(response, fs.createWriteStream(dest)));
53
+ }).on("error", reject);
54
+ });
55
+ }
56
+
57
+ async function main() {
58
+ const version = require("./package.json").version;
59
+ const binaryName = getBinaryName();
60
+ const url = `https://github.com/${REPO}/releases/download/v${version}/${binaryName}`;
61
+ const temporaryPath = `${BIN_PATH}.${process.pid}.tmp`;
62
+ console.log(`Downloading GTM CLI v${version} for ${process.platform}-${process.arch}...`);
63
+ fs.mkdirSync(BIN_DIR, { recursive: true });
64
+ try {
65
+ await download(url, temporaryPath);
66
+ if (process.platform !== "win32") fs.chmodSync(temporaryPath, 0o755);
67
+ fs.renameSync(temporaryPath, BIN_PATH);
68
+ console.log("GTM CLI installed successfully!");
69
+ } finally {
70
+ if (fs.existsSync(temporaryPath)) fs.unlinkSync(temporaryPath);
71
+ }
72
+ }
73
+
74
+ main().catch((error) => {
75
+ console.error(`Failed to install GTM CLI: ${error.message}`);
76
+ process.exitCode = 1;
77
+ });
package/package.json CHANGED
@@ -1,6 +1,46 @@
1
1
  {
2
2
  "name": "@dac-tech-team-tw/gtm-cli",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.7.1",
4
+ "description": "Command-line interface for Google Tag Manager",
5
+ "keywords": [
6
+ "google-tag-manager",
7
+ "gtm",
8
+ "cli",
9
+ "google",
10
+ "tag-manager",
11
+ "analytics"
12
+ ],
13
+ "homepage": "https://github.com/dac-tech-team-tw/gtm-cli",
14
+ "bugs": {
15
+ "url": "https://github.com/dac-tech-team-tw/gtm-cli/issues"
16
+ },
17
+ "repository": {
18
+ "type": "git",
19
+ "url": "git+https://github.com/dac-tech-team-tw/gtm-cli.git"
20
+ },
21
+ "license": "MIT",
22
+ "author": "dac-tech-team-tw",
23
+ "bin": {
24
+ "gtm": "bin/gtm"
25
+ },
26
+ "files": [
27
+ "bin",
28
+ "install.js",
29
+ "README.md"
30
+ ],
31
+ "scripts": {
32
+ "postinstall": "node install.js"
33
+ },
34
+ "engines": {
35
+ "node": ">=16"
36
+ },
37
+ "os": [
38
+ "darwin",
39
+ "linux",
40
+ "win32"
41
+ ],
42
+ "cpu": [
43
+ "x64",
44
+ "arm64"
45
+ ]
46
+ }