opencode-plan-cards-plugin 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.1.1] - 2026-02-16
+
+### Added
+
+- CLI setup command for one-command installation:
+  - `npx -y opencode-plan-cards-plugin@latest setup`
+- Automatic `opencode.json` update with:
+  - `plugin: ["opencode-plan-cards-plugin@0.1.1"]`
+  - `agent.ask.hidden = true`
+- Automatic backup creation before writing config.
+
+### Changed
+
+- Added package binary entry for CLI execution.
+- Updated multilingual README files with one-command setup guide.
+
 ## [0.1.0] - 2026-02-16
 
 ### Added

package/README.en.md

@@ -15,8 +15,28 @@ A plugin that enhances card-based planning interactions for original OpenCode (D
 
 - OpenCode: `1.2.x` (Desktop / CLI)
 - Plugin distribution: both `file://` and npm package
+- One-command installer: Node.js `18+`
 
-## Installation (Method A: Git + file://, recommended first)
+## Installation (Method A: npm one-command setup, recommended)
+
+```powershell
+npx -y opencode-plan-cards-plugin@latest setup
+```
+
+By default this command:
+
+- creates a backup of `~/.config/opencode/opencode.json`
+- writes `plugin: ["opencode-plan-cards-plugin@0.1.1"]`
+- writes `agent.ask.hidden = true`
+
+Optional flags:
+
+```powershell
+npx -y opencode-plan-cards-plugin@latest setup --plugin opencode-plan-cards-plugin@0.1.1
+npx -y opencode-plan-cards-plugin@latest setup --config "C:\Users\<you>\.config\opencode\opencode.json"
+```
+
+## Installation (Method B: Git + file://)
 
 ```powershell
 git clone <your-repo-url> opencode-plan-cards-plugin
@@ -43,7 +63,7 @@ Configure plugin in `~/.config/opencode/opencode.json`:
 
 > On Windows, use `file:///` paths and encode spaces as `%20`.
 
-## Installation (Method B: npm)
+## Installation (Method C: npm manual config)
 
 After publishing, user config:
 
@@ -51,7 +71,7 @@ After publishing, user config:
 {
   "$schema": "https://opencode.ai/config.json",
   "plugin": [
-    "opencode-plan-cards-plugin@0.1.0"
+    "opencode-plan-cards-plugin@0.1.1"
   ],
   "agent": {
     "ask": {

package/README.ja.md

@@ -15,8 +15,28 @@
 
 - OpenCode: `1.2.x`（Desktop / CLI）
 - プラグイン配布形態：`file://` と npm の両対応
+- ワンコマンド設定: Node.js `18+`
 
-## インストール（方式 A：Git + file://、初回推奨）
+## インストール（方式 A：npm ワンコマンド設定、推奨）
+
+```powershell
+npx -y opencode-plan-cards-plugin@latest setup
+```
+
+このコマンドは自動で以下を実行します：
+
+- `~/.config/opencode/opencode.json` のバックアップ作成
+- `plugin: ["opencode-plan-cards-plugin@0.1.1"]` を設定
+- `agent.ask.hidden = true` を設定
+
+オプション：
+
+```powershell
+npx -y opencode-plan-cards-plugin@latest setup --plugin opencode-plan-cards-plugin@0.1.1
+npx -y opencode-plan-cards-plugin@latest setup --config "C:\Users\<you>\.config\opencode\opencode.json"
+```
+
+## インストール（方式 B：Git + file://）
 
 ```powershell
 git clone <your-repo-url> opencode-plan-cards-plugin
@@ -43,7 +63,7 @@ npm run build
 
 > Windows では `file:///` 形式を使用し、空白は `%20` にしてください。
 
-## インストール（方式 B：npm）
+## インストール（方式 C：npm 手動設定）
 
 公開後、ユーザー設定：
 
@@ -51,7 +71,7 @@ npm run build
 {
   "$schema": "https://opencode.ai/config.json",
   "plugin": [
-    "opencode-plan-cards-plugin@0.1.0"
+    "opencode-plan-cards-plugin@0.1.1"
   ],
   "agent": {
     "ask": {

package/README.md

@@ -20,8 +20,28 @@ Language / 语言 / 言語:
 
 - OpenCode: `1.2.x`（桌面端 / CLI）
 - 插件形态：`file://` 与 npm 包均可
+- 一键安装器：Node.js `18+`
 
-## 安装（方式 A：Git + file://，推荐首发）
+## 安装（方式 A：npm 一键写配置，推荐）
+
+```powershell
+npx -y opencode-plan-cards-plugin@latest setup
+```
+
+默认会自动：
+
+- 备份 `~/.config/opencode/opencode.json`
+- 写入 `plugin: ["opencode-plan-cards-plugin@0.1.1"]`
+- 写入 `agent.ask.hidden = true`
+
+可选参数：
+
+```powershell
+npx -y opencode-plan-cards-plugin@latest setup --plugin opencode-plan-cards-plugin@0.1.1
+npx -y opencode-plan-cards-plugin@latest setup --config "C:\Users\<you>\.config\opencode\opencode.json"
+```
+
+## 安装（方式 B：Git + file://）
 
 ```powershell
 git clone <your-repo-url> opencode-plan-cards-plugin
@@ -48,7 +68,7 @@ npm run build
 
 > Windows 路径需要使用 `file:///`，空格写成 `%20`。
 
-## 安装（方式 B：npm）
+## 安装（方式 C：npm 手动配置）
 
 发布后，用户配置：
 
@@ -56,7 +76,7 @@ npm run build
 {
   "$schema": "https://opencode.ai/config.json",
   "plugin": [
-    "opencode-plan-cards-plugin@0.1.0"
+    "opencode-plan-cards-plugin@0.1.1"
   ],
   "agent": {
     "ask": {

package/README.zh-CN.md

@@ -15,8 +15,28 @@
 
 - OpenCode: `1.2.x`（桌面端 / CLI）
 - 插件形态：`file://` 与 npm 包均可
+- 一键安装器：Node.js `18+`
 
-## 安装（方式 A：Git + file://，推荐首发）
+## 安装（方式 A：npm 一键写配置，推荐）
+
+```powershell
+npx -y opencode-plan-cards-plugin@latest setup
+```
+
+默认会自动：
+
+- 备份 `~/.config/opencode/opencode.json`
+- 写入 `plugin: ["opencode-plan-cards-plugin@0.1.1"]`
+- 写入 `agent.ask.hidden = true`
+
+可选参数：
+
+```powershell
+npx -y opencode-plan-cards-plugin@latest setup --plugin opencode-plan-cards-plugin@0.1.1
+npx -y opencode-plan-cards-plugin@latest setup --config "C:\Users\<you>\.config\opencode\opencode.json"
+```
+
+## 安装（方式 B：Git + file://）
 
 ```powershell
 git clone <your-repo-url> opencode-plan-cards-plugin
@@ -43,7 +63,7 @@ npm run build
 
 > Windows 路径需要使用 `file:///`，空格写成 `%20`。
 
-## 安装（方式 B：npm）
+## 安装（方式 C：npm 手动配置）
 
 发布后，用户配置：
 
@@ -51,7 +71,7 @@ npm run build
 {
   "$schema": "https://opencode.ai/config.json",
   "plugin": [
-    "opencode-plan-cards-plugin@0.1.0"
+    "opencode-plan-cards-plugin@0.1.1"
   ],
   "agent": {
     "ask": {

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json");
+function usage() {
+    const defaultPlugin = `${pkg.name ?? "opencode-plan-cards-plugin"}@${pkg.version ?? "latest"}`;
+    return [
+        "Usage:",
+        "  opencode-plan-cards-plugin setup [options]",
+        "",
+        "Options:",
+        "  --plugin <spec>   Plugin spec to inject (default: current package version)",
+        "  --config <path>   Path to opencode.json",
+        "  --dry-run         Preview changes without writing files",
+        "  --no-backup       Skip backup file creation",
+        "  -h, --help        Show help",
+        "",
+        "Example:",
+        `  npx -y ${pkg.name ?? "opencode-plan-cards-plugin"}@latest setup`,
+        `  npx -y ${pkg.name ?? "opencode-plan-cards-plugin"}@latest setup --plugin ${defaultPlugin}`,
+    ].join("\n");
+}
+function parseArgs(argv) {
+    const options = {
+        dryRun: false,
+        noBackup: false,
+        help: false,
+    };
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "-h" || arg === "--help") {
+            options.help = true;
+            continue;
+        }
+        if (arg === "--dry-run") {
+            options.dryRun = true;
+            continue;
+        }
+        if (arg === "--no-backup") {
+            options.noBackup = true;
+            continue;
+        }
+        if (arg === "--plugin") {
+            const value = argv[index + 1];
+            if (!value)
+                throw new Error("Missing value for --plugin");
+            options.plugin = value.trim();
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--plugin=")) {
+            options.plugin = arg.slice("--plugin=".length).trim();
+            continue;
+        }
+        if (arg === "--config") {
+            const value = argv[index + 1];
+            if (!value)
+                throw new Error("Missing value for --config");
+            options.config = value.trim();
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith("--config=")) {
+            options.config = arg.slice("--config=".length).trim();
+            continue;
+        }
+        if (!options.command && !arg.startsWith("-")) {
+            options.command = arg;
+            continue;
+        }
+        throw new Error(`Unknown argument: ${arg}`);
+    }
+    return options;
+}
+function resolveConfigPath(configOverride) {
+    if (configOverride && configOverride.trim()) {
+        return resolve(configOverride.trim());
+    }
+    const configRoot = process.env.XDG_CONFIG_HOME?.trim() || join(homedir(), ".config");
+    return join(configRoot, "opencode", "opencode.json");
+}
+function readJSONFile(filePath) {
+    if (!existsSync(filePath))
+        return {};
+    const raw = readFileSync(filePath, "utf8");
+    const normalized = raw.replace(/^\uFEFF/, "");
+    if (!normalized.trim())
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(normalized);
+    }
+    catch {
+        throw new Error(`Invalid JSON in config file: ${filePath}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`Config root must be a JSON object: ${filePath}`);
+    }
+    return parsed;
+}
+function extractPackageName(spec) {
+    const trimmed = spec.trim();
+    const match = /^(@[^/\s]+\/[^@\s/]+|[^@\s/]+)(?:@.+)?$/.exec(trimmed);
+    return match?.[1];
+}
+function isSamePlugin(existing, targetSpec) {
+    if (existing === targetSpec)
+        return true;
+    const targetName = extractPackageName(targetSpec);
+    if (!targetName)
+        return false;
+    const existingName = extractPackageName(existing);
+    return !!existingName && existingName === targetName;
+}
+function upsertPlugin(config, pluginSpec) {
+    const current = config.plugin;
+    if (current !== undefined &&
+        typeof current !== "string" &&
+        !Array.isArray(current)) {
+        throw new Error('Config key "plugin" must be a string or an array');
+    }
+    const pluginList = Array.isArray(current)
+        ? [...current]
+        : typeof current === "string"
+            ? [current]
+            : [];
+    let matched = false;
+    let changed = !Array.isArray(current);
+    for (let index = 0; index < pluginList.length; index += 1) {
+        const value = pluginList[index];
+        if (typeof value !== "string")
+            continue;
+        if (!isSamePlugin(value, pluginSpec))
+            continue;
+        matched = true;
+        if (value !== pluginSpec) {
+            pluginList[index] = pluginSpec;
+            changed = true;
+        }
+    }
+    if (!matched) {
+        pluginList.push(pluginSpec);
+        changed = true;
+    }
+    config.plugin = pluginList;
+    return changed;
+}
+function ensureObject(parent, key) {
+    const value = parent[key];
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        return value;
+    }
+    const next = {};
+    parent[key] = next;
+    return next;
+}
+function updateAskHidden(config) {
+    const agent = ensureObject(config, "agent");
+    const ask = ensureObject(agent, "ask");
+    if (ask.hidden === true)
+        return false;
+    ask.hidden = true;
+    return true;
+}
+function applySetup(config, pluginSpec) {
+    const pluginUpdated = upsertPlugin(config, pluginSpec);
+    const askHiddenUpdated = updateAskHidden(config);
+    return {
+        changed: pluginUpdated || askHiddenUpdated,
+        pluginUpdated,
+        askHiddenUpdated,
+    };
+}
+function backupPath(configPath) {
+    const stamp = new Date().toISOString().replace(/\.\d{3}Z$/, "Z").replace(/[:]/g, "-");
+    return `${configPath}.bak-${stamp}`;
+}
+function writeConfig(configPath, config, createBackup) {
+    mkdirSync(dirname(configPath), { recursive: true });
+    let savedBackup;
+    if (createBackup && existsSync(configPath)) {
+        savedBackup = backupPath(configPath);
+        copyFileSync(configPath, savedBackup);
+    }
+    writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+    return savedBackup;
+}
+function run() {
+    const options = parseArgs(process.argv.slice(2));
+    if (options.help || !options.command) {
+        console.log(usage());
+        return;
+    }
+    if (options.command !== "setup") {
+        throw new Error(`Unknown command: ${options.command}`);
+    }
+    const packageName = pkg.name ?? "opencode-plan-cards-plugin";
+    const packageVersion = pkg.version ?? "latest";
+    const pluginSpec = options.plugin?.trim() || `${packageName}@${packageVersion}`;
+    const configPath = resolveConfigPath(options.config);
+    const config = readJSONFile(configPath);
+    const result = applySetup(config, pluginSpec);
+    if (!result.changed) {
+        console.log(`No changes needed: ${configPath}`);
+        return;
+    }
+    if (options.dryRun) {
+        console.log(`[dry-run] Config file: ${configPath}`);
+        console.log(`[dry-run] plugin updated: ${result.pluginUpdated}`);
+        console.log(`[dry-run] ask.hidden updated: ${result.askHiddenUpdated}`);
+        console.log(JSON.stringify(config, null, 2));
+        return;
+    }
+    const savedBackup = writeConfig(configPath, config, !options.noBackup);
+    console.log(`Updated: ${configPath}`);
+    if (savedBackup) {
+        console.log(`Backup: ${savedBackup}`);
+    }
+    console.log(`Plugin: ${pluginSpec}`);
+    console.log("Done. Restart OpenCode and run /plan card on in your session.");
+}
+try {
+    run();
+}
+catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`Error: ${message}`);
+    console.error("");
+    console.error(usage());
+    process.exitCode = 1;
+}

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "opencode-plan-cards-plugin",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Plan card interaction enhancement plugin for OpenCode",
   "type": "module",
   "main": "dist/index.js",
+  "bin": {
+    "opencode-plan-cards-plugin": "./dist/cli.js"
+  },
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
@@ -34,6 +37,7 @@
   "devDependencies": {
     "@opencode-ai/plugin": "^1.2.0",
     "@opencode-ai/sdk": "^1.2.0",
+    "@types/node": "^22.13.10",
     "typescript": "^5.7.3"
   }
 }