opencode-plan-cards-plugin 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 All notable changes to this project will be documented in this file.
 
+## [Unreleased]
+
+## [0.1.2] - 2026-02-16
+
+### Added
+
+- Open-source community files:
+  - `CONTRIBUTING.md`
+  - `SECURITY.md`
+  - `CODE_OF_CONDUCT.md`
+- GitHub Actions CI workflow (`.github/workflows/ci.yml`) for type-check and build.
+
+### Changed
+
+- Added npm package metadata: `repository`, `homepage`, `bugs`, `author`, `engines`.
+- Replaced placeholder git clone URLs in all README variants.
+- Added `*.tgz` to `.gitignore`.
+- Card mode is now enabled by default for `plan` sessions after plugin installation.
+- `/plan card off` remains available for session-level opt-out.
+- `/plan card on` can re-enable card mode for that session.
+- Updated multilingual README usage examples for default-on behavior.
+- Updated setup CLI completion message to reflect default-on behavior.
+
+## [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

@@ -9,17 +9,37 @@ A plugin that enhances card-based planning interactions for original OpenCode (D
   - `/plan card off`
 - When enabled, it injects a stricter `plan` workflow: clarify first, confirm, then output a complete plan.
 - Enhances the `question` tool definition to encourage card questions with 2–3 options and clear tradeoff descriptions.
-- Disabled by default; controlled per session.
+- Enabled by default after installation; still controllable per session.
 
 ## Compatibility
 
 - 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
-git clone <your-repo-url> opencode-plan-cards-plugin
+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.2"]`
+- writes `agent.ask.hidden = true`
+
+Optional flags:
+
+```powershell
+npx -y opencode-plan-cards-plugin@latest setup --plugin opencode-plan-cards-plugin@0.1.2
+npx -y opencode-plan-cards-plugin@latest setup --config "C:\Users\<you>\.config\opencode\opencode.json"
+```
+
+## Installation (Method B: Git + file://)
+
+```powershell
+git clone https://github.com/SAKURA1175/opencode-plan-cards-plugin.git opencode-plan-cards-plugin
 cd opencode-plan-cards-plugin
 npm install
 npm run build
@@ -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.2"
   ],
   "agent": {
     "ask": {
@@ -63,14 +83,14 @@ After publishing, user config:
 
 ## Usage
 
-1. In a target session, run `/plan card on`
-2. Continue describing requirements in `plan`; the model prioritizes card-based clarification and confirmation
-3. To restore default behavior, run `/plan card off`
+1. After install and restart, card mode is enabled by default in `plan` sessions
+2. To disable card mode in the current session, run `/plan card off`
+3. To re-enable card mode in the current session, run `/plan card on`
 
 ## Validation Checklist
 
-1. Desktop: card interaction appears after `/plan card on`
-2. CLI: same command works
+1. Desktop: card interaction appears by default in `plan` sessions
+2. CLI: same default behavior works
 3. `/plan card off` restores default `plan` behavior
 4. `agent.ask.hidden=true` hides ask in UI by default
 

package/README.ja.md

@@ -9,17 +9,37 @@
   - `/plan card off`
 - 有効化時、`plan` セッションにのみ「要件確認 → 最終確認 → 完全な実行計画出力」の制約を注入。
 - `question` ツール定義を強化し、2〜3択 + トレードオフ説明のカード質問を促進。
-- デフォルトは無効。セッションごとのスイッチで制御。
+- インストール後はデフォルトで有効。セッションごとに切り替え可能。
 
 ## 互換性
 
 - OpenCode: `1.2.x`（Desktop / CLI）
 - プラグイン配布形態：`file://` と npm の両対応
+- ワンコマンド設定: Node.js `18+`
 
-## インストール（方式 A：Git + file://、初回推奨）
+## インストール（方式 A：npm ワンコマンド設定、推奨）
 
 ```powershell
-git clone <your-repo-url> opencode-plan-cards-plugin
+npx -y opencode-plan-cards-plugin@latest setup
+```
+
+このコマンドは自動で以下を実行します：
+
+- `~/.config/opencode/opencode.json` のバックアップ作成
+- `plugin: ["opencode-plan-cards-plugin@0.1.2"]` を設定
+- `agent.ask.hidden = true` を設定
+
+オプション：
+
+```powershell
+npx -y opencode-plan-cards-plugin@latest setup --plugin opencode-plan-cards-plugin@0.1.2
+npx -y opencode-plan-cards-plugin@latest setup --config "C:\Users\<you>\.config\opencode\opencode.json"
+```
+
+## インストール（方式 B：Git + file://）
+
+```powershell
+git clone https://github.com/SAKURA1175/opencode-plan-cards-plugin.git opencode-plan-cards-plugin
 cd opencode-plan-cards-plugin
 npm install
 npm run build
@@ -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.2"
   ],
   "agent": {
     "ask": {
@@ -63,14 +83,14 @@ npm run build
 
 ## 使い方
 
-1. 対象セッションで `/plan card on` を入力
-2. `plan` で要件を入力すると、カードによる確認フローが優先される
-3. 既定動作に戻す場合は `/plan card off`
+1. インストール後に再起動すると、`plan` セッションではカードモードがデフォルトで有効
+2. 現在のセッションでカードモードを無効化する場合は `/plan card off`
+3. 現在のセッションでカードモードを再有効化する場合は `/plan card on`
 
 ## 動作確認チェックリスト
 
-1. Desktop：`/plan card on` 後にカード質問フローが表示される
-2. CLI：同様にコマンドが有効
+1. Desktop：`plan` セッションでデフォルトでカード質問フローが表示される
+2. CLI：同様にデフォルトで有効
 3. `/plan card off` 後に標準 `plan` 挙動へ復帰
 4. `agent.ask.hidden=true` で UI の ask を非表示化
 

package/README.md

@@ -14,17 +14,37 @@ Language / 语言 / 言語:
   - `/plan card off`
 - 开启后仅在 `plan` 会话注入“先澄清、再确认、再输出完整计划”的系统约束。
 - 强化 `question` 工具描述，推动 2–3 选项 + 权衡说明的卡片提问格式。
-- 默认不强开，按会话开关控制。
+- 安装后默认自动开启卡片模式，可按会话临时关闭。
 
 ## 兼容性
 
 - OpenCode: `1.2.x`（桌面端 / CLI）
 - 插件形态：`file://` 与 npm 包均可
+- 一键安装器：Node.js `18+`
 
-## 安装（方式 A：Git + file://，推荐首发）
+## 安装（方式 A：npm 一键写配置，推荐）
 
 ```powershell
-git clone <your-repo-url> opencode-plan-cards-plugin
+npx -y opencode-plan-cards-plugin@latest setup
+```
+
+默认会自动：
+
+- 备份 `~/.config/opencode/opencode.json`
+- 写入 `plugin: ["opencode-plan-cards-plugin@0.1.2"]`
+- 写入 `agent.ask.hidden = true`
+
+可选参数：
+
+```powershell
+npx -y opencode-plan-cards-plugin@latest setup --plugin opencode-plan-cards-plugin@0.1.2
+npx -y opencode-plan-cards-plugin@latest setup --config "C:\Users\<you>\.config\opencode\opencode.json"
+```
+
+## 安装（方式 B：Git + file://）
+
+```powershell
+git clone https://github.com/SAKURA1175/opencode-plan-cards-plugin.git opencode-plan-cards-plugin
 cd opencode-plan-cards-plugin
 npm install
 npm run build
@@ -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.2"
   ],
   "agent": {
     "ask": {
@@ -68,14 +88,14 @@ npm run build
 
 ## 使用
 
-1. 在目标会话输入：`/plan card on`
-2. 继续在 `plan` 中描述需求，模型会优先走卡片澄清与确认流程
-3. 需要恢复默认行为时输入：`/plan card off`
+1. 安装并重启后，在 `plan` 会话中默认启用卡片澄清与确认流程
+2. 需要关闭当前会话卡片模式时输入：`/plan card off`
+3. 需要重新开启当前会话卡片模式时输入：`/plan card on`
 
 ## 验证清单
 
-1. 桌面端：`/plan card on` 后出现卡片问答流程
-2. CLI：同样命令生效
+1. 桌面端：进入 `plan` 会话后默认出现卡片问答流程
+2. CLI：同样默认生效
 3. `/plan card off` 后恢复原始 `plan` 行为
 4. `agent.ask.hidden=true` 后 UI 默认不展示 ask
 

package/README.zh-CN.md

@@ -9,17 +9,37 @@
   - `/plan card off`
 - 开启后仅在 `plan` 会话注入“先澄清、再确认、再输出完整计划”的系统约束。
 - 强化 `question` 工具描述，推动 2–3 选项 + 权衡说明的卡片提问格式。
-- 默认不强开，按会话开关控制。
+- 安装后默认自动开启卡片模式，可按会话临时关闭。
 
 ## 兼容性
 
 - OpenCode: `1.2.x`（桌面端 / CLI）
 - 插件形态：`file://` 与 npm 包均可
+- 一键安装器：Node.js `18+`
 
-## 安装（方式 A：Git + file://，推荐首发）
+## 安装（方式 A：npm 一键写配置，推荐）
 
 ```powershell
-git clone <your-repo-url> opencode-plan-cards-plugin
+npx -y opencode-plan-cards-plugin@latest setup
+```
+
+默认会自动：
+
+- 备份 `~/.config/opencode/opencode.json`
+- 写入 `plugin: ["opencode-plan-cards-plugin@0.1.2"]`
+- 写入 `agent.ask.hidden = true`
+
+可选参数：
+
+```powershell
+npx -y opencode-plan-cards-plugin@latest setup --plugin opencode-plan-cards-plugin@0.1.2
+npx -y opencode-plan-cards-plugin@latest setup --config "C:\Users\<you>\.config\opencode\opencode.json"
+```
+
+## 安装（方式 B：Git + file://）
+
+```powershell
+git clone https://github.com/SAKURA1175/opencode-plan-cards-plugin.git opencode-plan-cards-plugin
 cd opencode-plan-cards-plugin
 npm install
 npm run build
@@ -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.2"
   ],
   "agent": {
     "ask": {
@@ -63,14 +83,14 @@ npm run build
 
 ## 使用
 
-1. 在目标会话输入：`/plan card on`
-2. 继续在 `plan` 中描述需求，模型会优先走卡片澄清与确认流程
-3. 需要恢复默认行为时输入：`/plan card off`
+1. 安装并重启后，在 `plan` 会话中默认启用卡片澄清与确认流程
+2. 需要关闭当前会话卡片模式时输入：`/plan card off`
+3. 需要重新开启当前会话卡片模式时输入：`/plan card on`
 
 ## 验证清单
 
-1. 桌面端：`/plan card on` 后出现卡片问答流程
-2. CLI：同样命令生效
+1. 桌面端：进入 `plan` 会话后默认出现卡片问答流程
+2. CLI：同样默认生效
 3. `/plan card off` 后恢复原始 `plan` 行为
 4. `agent.ask.hidden=true` 后 UI 默认不显示 ask
 

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,235 @@
+#!/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. Card mode is enabled by default in plan sessions.");
+    console.log("Use /plan card off to disable it for the current 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/dist/index.js

@@ -1,4 +1,5 @@
 const CARD_COMMAND_PATTERN = /^\/plan\s+card\s+(on|off)$/i;
+const DEFAULT_CARD_MODE = true;
 const cardModeBySession = new Map();
 const lastAgentBySession = new Map();
 const PLAN_CARD_SYSTEM_APPENDIX = `
@@ -58,6 +59,12 @@ function appendUniqueDescription(base, appendix) {
         return normalized;
     return `${base.trim()}\n\n${normalized}`;
 }
+function isCardModeEnabled(sessionID) {
+    const mode = cardModeBySession.get(sessionID);
+    if (mode === undefined)
+        return DEFAULT_CARD_MODE;
+    return mode;
+}
 function patchQuestionParameters(parameters) {
     const questionItem = parameters?.properties?.questions?.items;
     const questionProps = questionItem?.properties;
@@ -98,7 +105,7 @@ export const PlanCardsPlugin = async () => {
         "experimental.chat.system.transform": async (input, output) => {
             if (!input.sessionID)
                 return;
-            if (!cardModeBySession.get(input.sessionID))
+            if (!isCardModeEnabled(input.sessionID))
                 return;
             if (lastAgentBySession.get(input.sessionID) !== "plan")
                 return;

package/package.json

@@ -1,9 +1,25 @@
 {
   "name": "opencode-plan-cards-plugin",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Plan card interaction enhancement plugin for OpenCode",
+  "author": "sakura1175",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SAKURA1175/opencode-plan-cards-plugin.git"
+  },
+  "homepage": "https://github.com/SAKURA1175/opencode-plan-cards-plugin#readme",
+  "bugs": {
+    "url": "https://github.com/SAKURA1175/opencode-plan-cards-plugin/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
   "type": "module",
   "main": "dist/index.js",
+  "bin": {
+    "opencode-plan-cards-plugin": "dist/cli.js"
+  },
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
@@ -26,14 +42,13 @@
     "plan",
     "cards"
   ],
-  "author": "",
-  "license": "MIT",
   "peerDependencies": {
     "@opencode-ai/plugin": ">=1.2.0 <2"
   },
   "devDependencies": {
     "@opencode-ai/plugin": "^1.2.0",
     "@opencode-ai/sdk": "^1.2.0",
+    "@types/node": "^22.13.10",
     "typescript": "^5.7.3"
   }
 }