ops-wiki-agent-kit 0.1.0

package/.github/skills/database-query/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: database-query
+description: "通用 DB 查詢 workflow。當 agent 需要從 repo 找出 DB 連線資訊、選擇安全的查詢方式，並透過 helper scripts、native CLI clients 或 repo 既有工具，對 Oracle、PostgreSQL、SQL Server、MySQL、MariaDB、SQLite、IBM Db2、H2 或其他 SQL databases 執行 read-only SQL investigation 時使用。"
+---
+
+# Database Query
+
+## Overview
+
+用這個 skill 協助 AI agent 在陌生 repo 中查詢 DB。流程優先從 repo 內找既有 DB 連線設定與查詢工具，找不到完整資訊時才向 user 要求必要連線資料。
+
+預設只做 read-only investigation。除非 user 明確要求且確認目標環境，否則不要執行 `INSERT`、`UPDATE`、`DELETE`、`MERGE`、`TRUNCATE`、`CREATE`、`ALTER`、`DROP`、`GRANT`、`REVOKE`，或任何具有 side effects 的 stored procedure/function call。
+
+## Core Rules
+
+- 除非有明確證據證明 DB 是 local、可丟棄或僅供 test，否則一律視為 live DB。
+- 優先使用 repo 既有的 helper scripts、已設定好的 app tools 或 native clients，不要先自行發明新的 connector。
+- 回答中絕對不要輸出 plaintext passwords、tokens、wallet paths、private keys，或包含完整 credentials 的 URL。
+- 不要建立或提交新的 credential files。需要 credentials 時，使用 session environment variables 或 user 提供的暫時性值。
+- 如果存在多組 DB config，查詢前先辨識目標 environment：`local`、`dev`、`test`、`uat`、`stage`、`prod`、tenant、schema、service 或 container。
+- 若 repo 同時出現多個 DB backend、datasource profile 或 environment 線索，`SELECT 1` 成功只代表 client 可連線，不代表你已連到正確的 business authority。開始 inventory / business query 前，必須記錄目前 session 的 user、schema、service / database identity。
+- 查詢要有邊界。加入 row limits、filters、schema qualifiers，以及精準的 column lists。
+- 記錄實際執行的 SQL、DB type、connection info 來源、row counts 與不確定性，並遮蔽敏感的 connection fields。
+- 若 repo 提供 PowerShell / shell helper 包裝 native client，優先直接呼叫 helper 或先產生 temp SQL/file 再執行；不要把 helper 再嵌進過長、重 quoting 的 one-liner，避免把 shell 展開問題誤判成 DB query failure。
+
+## Workflow
+
+### 1. Clarify The Query Goal
+
+先確認 user 要的是哪一類 DB 查詢：
+
+- schema discovery：table、column、index、constraint、view、sequence、procedure/package。
+- data validation：count、sample rows、status distribution、date range、duplicate check。
+- application debugging：從 source code 追蹤 table usage、驗證預期 records、比對 config values。
+- operational check：job status、queue state、scheduler metadata、lock/session inspection。
+- migration/release check：確認 DDL state 或 migration history。
+
+如果 user 的需求暗示會修改資料，先停下來要求明確核准與 rollback/backup plan。
+
+### 2. Discover DB Type And Connection Candidates
+
+先從 repo 取得證據，不要直接詢問 user：
+
+1. 從 repo root 執行 `python -B .github/skills/database-query/scripts/find_db_config.py <repo-path>`，找出 DB URLs、datasource keys、env placeholders 與 config files，並確保輸出已做 redaction。使用 `-B` 避免留下 `__pycache__` 或 `*.pyc` runtime cache。
+2. 在整個 repo 的 source、config、scripts、deployment manifests 與 dependency metadata 中搜尋 DB drivers、connection strings、ORM/data-access packages、DSN 與 env var patterns；不要假設 repo 一定是 Java 或 Web 專案：
+   - generic: `DATABASE_URL`, `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASSWORD`, `ConnectionStrings`, `ODBC DSN`, `DSN=`, `Data Source=`, `Server=`, `Host=`, `User ID=`
+   - `jdbc:oracle:thin`, `oracle.jdbc`, `tnsnames.ora`, `sqlplus`, `sqlcl`
+   - `jdbc:postgresql`, `org.postgresql`, `PGHOST`, `DATABASE_URL`
+   - `jdbc:sqlserver`, `com.microsoft.sqlserver`, `sqlcmd`, `Data Source=`
+   - `jdbc:mysql`, `jdbc:mariadb`, `com.mysql`, `org.mariadb`
+   - `jdbc:db2`, `com.ibm.db2`, `db2 connect`
+   - `jdbc:h2`, `jdbc:sqlite`, `sqlite3`
+   - Java/JVM: `spring.datasource.*`, `r2dbc.*`, `hibernate.connection.*`, `persistence.xml`, `context.xml`, `javax.sql.DataSource`
+   - .NET/C#: `appsettings*.json`, `web.config`, `*.config`, `*.csproj`, `System.Data.SqlClient`, `Microsoft.Data.SqlClient`, `Npgsql`, `Oracle.ManagedDataAccess`, `MySqlConnector`, `EntityFramework`, `Dapper`
+   - Node.js/TypeScript: `pg`, `mysql2`, `mssql`, `oracledb`, `typeorm`, `sequelize`, `prisma`, `knex`
+   - Python: `sqlalchemy`, `psycopg`, `psycopg2`, `cx_Oracle`, `oracledb`, `pyodbc`, `pymysql`, `sqlite3`
+   - PHP/Ruby and other stacks: `PDO`, `mysqli`, `ActiveRecord`, `database.yml`, `config/database.*`
+3. 檢查常見的 config 與 runtime 位置，依 repo 實際技術棧調整，不要只看單一語言慣例：
+   - `.env*`, `appsettings*.json`, `web.config`, `*.config`, `database.yml`, `database.*`, `settings.*`
+   - `application*.properties`, `application*.yml`, `docker-compose*.yml`
+   - `helm/`, `k8s/`, `deployment*.yaml`, `values*.yaml`, `configmap`, `secret`
+   - `pom.xml`, `build.gradle`, `*.csproj`, `packages.config`, `package.json`, `requirements.txt`, `pyproject.toml`, `composer.json`, `Gemfile`
+   - Jenkins/GitLab CI files, startup scripts, container scripts, scheduled task definitions
+   - `config/`, `conf/`, `resources/`, `src/main/resources/`, `WEB-INF/`, `Properties/`, `App_Data/`
+
+如果 repo 內只有 `${DB_PASSWORD}` 這類 placeholders，先找出變數名稱，並在可行時檢查目前 process environment。若值不可得，再請 user 提供。
+
+### 3. Decide Whether To Prompt User
+
+只有在 repo discovery 無法補齊完整 connection profile 時，才詢問 user。
+
+只詢問最小必要缺漏資訊：
+
+- `db_type`: Oracle, PostgreSQL, SQL Server, MySQL, MariaDB, SQLite, IBM Db2, H2, etc.
+- `host`, `port`, `database` or `service_name`/`SID`, and optional `schema`.
+- `username` and password/token, preferably read-only and temporary.
+- environment name: `local`, `dev`, `test`, `uat`, `prod`.
+- preferred access method if security policy requires one: VPN, bastion, container exec, app helper, wallet, Kerberos, IAM, ODBC DSN.
+
+告知 user 可以提供 placeholders 或僅限本次 session 使用的值。不要要求 user 把 secrets 提交進 repo。
+
+### 4. Choose The Query Method
+
+依照以下順序選擇：
+
+1. Existing repo helper: scripts, Makefile/Gradle/Maven tasks, app admin CLI, migration tooling, DAO/repository tests, or documented SQL utilities.
+2. Native DB client:
+   - Oracle: `sqlplus` or `sql`
+   - PostgreSQL: `psql`
+   - SQL Server: `sqlcmd`
+   - MySQL/MariaDB: `mysql` or `mariadb`
+   - SQLite: `sqlite3`
+   - IBM Db2: `db2`
+   - H2: app console, JDBC tool, or repo-provided test utility
+3. Container-local client: `docker compose exec`, `kubectl exec`, or DB client inside an app/DB container when local tooling is unavailable.
+4. Temporary helper script in the current work session only if dependencies are already installed or user approves installation. Do not add DB driver dependencies to the repo for a one-off query.
+
+可參考 `references/client-commands.md` 取得 native client command templates，並參考 `references/query-safety.md` 了解 read-only 與 row-limit patterns。
+
+### 5. Validate Connection With A Minimal Query
+
+在正式 investigation 前，先執行無害的 identity/version query：
+
+- Oracle: `SELECT 1 FROM dual`
+- PostgreSQL: `SELECT 1`
+- SQL Server: `SELECT 1`
+- MySQL/MariaDB: `SELECT 1`
+- SQLite: `SELECT 1`
+- IBM Db2: `SELECT 1 FROM sysibm.sysdummy1`
+- H2: `SELECT 1`
+
+如果 connection 失敗，回報精確但不含 secrets 的錯誤類型：network、auth、service/database name、missing client、missing driver、SSL/TLS、VPN/bastion、permission denied 或 syntax mismatch。
+
+若 repo 有多組連線線索、同時存在多個 datasource，或 user 問題依賴特定 schema / service，`SELECT 1` 後再執行 identity query，記錄目前 session 的 user、schema、service / database。例如 Oracle 可用 `SELECT USER, SYS_CONTEXT('USERENV','CURRENT_SCHEMA'), SYS_CONTEXT('USERENV','SERVICE_NAME') FROM dual`；其他 DB 使用對應 identity function。
+
+### 6. Run Bounded SQL
+
+撰寫剛好能回答問題的最小查詢：
+
+- 先從 metadata tables 開始，不要一開始就掃 business tables。
+- 使用 `WHERE`、date bounds、primary keys，以及 `LIMIT`/`TOP`/`FETCH FIRST`。
+- 除非 table 很小，或 user 明確要求 raw inspection，否則避免使用 `SELECT *`。
+- 面對大表時，先跑 counts 或 grouped summaries。
+- 如果 query 可能代價很高，先說明風險，再徵求同意後執行。
+- 明確區分 SQL dialect-specific syntax，不要假設 PostgreSQL 語法可以直接套用到 Oracle 或 SQL Server。
+- 明確區分 dialect-specific semantics。只有在已辨識目前 DB 是 Oracle 時，才套用 Oracle 的 empty-string/NULL 規則；其他 DB 依各自語意處理。
+- Oracle 查非空字串時，不要寫 `= ''`、`<> ''`，也不要寫 `TRIM(NVL(col, '')) <> ''`。Oracle 會把 `''` 視為 `NULL`，這類 predicate 容易把原本有值的 rows 全部過濾掉。判斷 trim 後非空時，優先使用 `LENGTH(TRIM(NVL(col, ' '))) > 0`；若只是判斷有無值，可用 `TRIM(col) IS NOT NULL`。
+- 若第一個 bounded inventory query 回傳 0 rows，但依 repo/catalog/context 應有資料，先回頭確認目前 schema / service 是否正確、table/view 是否在當前 namespace 可見，再決定這是 validated empty 還是連錯環境 / authority 不明。
+
+### 7. Report Results
+
+回報時包含：
+
+- DB type and environment, if known.
+- Connection source: config file path, env var names, DSN name, container, or user-provided session values. Redact secrets.
+- SQL statements executed, with sensitive literals removed if needed.
+- Result summary: row count, key rows, anomalies,.
+- Follow-up gaps: missing schema permission, unresolved config placeholder, ambiguous environment, or query not run.
+
+最終輸出不要包含 plaintext credentials。

package/.github/skills/database-query/references/client-commands.md

@@ -0,0 +1,189 @@
+# DB Client Commands
+
+這份 reference 提供使用 native CLI 進行查詢的方式。實際使用時需依 repo 的 DB type、environment、schema、VPN/bastion/container 條件調整。
+
+## General Handling
+
+- 優先使用 password prompts、wallets、DSN 或 session environment variables，避免把 password 直接放在 command-line arguments。
+- 查詢完成後，清除暫時性的 environment variables。
+- 可以的話，優先使用 read-only users。
+- query files 應維持為暫時用途，不要 commit。
+- logs 與 final answers 中的 credentials 要遮蔽。
+
+## Oracle
+
+建議使用的 clients: `sqlplus`、Oracle SQLcl `sql`。
+
+```powershell
+sqlplus -L /nolog
+```
+
+接著在 client session 內連線：
+
+```sql
+connect <username>/<password>@//<host>:<port>/<service_name>
+SELECT 1 FROM dual;
+exit
+```
+
+實用的 inspection queries：
+
+```sql
+SELECT owner, table_name
+FROM all_tables
+WHERE owner = UPPER('<schema>')
+FETCH FIRST 50 ROWS ONLY;
+
+SELECT owner, table_name, column_name, data_type, nullable
+FROM all_tab_columns
+WHERE owner = UPPER('<schema>')
+  AND table_name = UPPER('<table_name>')
+ORDER BY column_id;
+```
+
+較舊的 Oracle versions 可能需要使用 `WHERE ROWNUM <= 50`，而不是 `FETCH FIRST`。
+
+## PostgreSQL
+
+建議使用的 client: `psql`。
+
+```powershell
+$env:PGPASSWORD = "<password>"
+psql -h <host> -p <port> -U <username> -d <database> -c "SELECT 1;"
+Remove-Item Env:\PGPASSWORD
+```
+
+實用的 inspection queries：
+
+```sql
+SELECT table_schema, table_name
+FROM information_schema.tables
+WHERE table_schema NOT IN ('pg_catalog', 'information_schema')
+ORDER BY table_schema, table_name
+LIMIT 50;
+
+SELECT column_name, data_type, is_nullable
+FROM information_schema.columns
+WHERE table_schema = '<schema>'
+  AND table_name = '<table_name>'
+ORDER BY ordinal_position;
+```
+
+## SQL Server
+
+建議使用的 client: `sqlcmd`。
+
+```powershell
+$env:SQLCMDPASSWORD = "<password>"
+sqlcmd -S <host>,<port> -d <database> -U <username> -Q "SELECT 1;"
+Remove-Item Env:\SQLCMDPASSWORD
+```
+
+若使用 Windows authentication：
+
+```powershell
+sqlcmd -S <host>,<port> -d <database> -E -Q "SELECT 1;"
+```
+
+實用的 inspection queries：
+
+```sql
+SELECT TOP (50) TABLE_SCHEMA, TABLE_NAME
+FROM INFORMATION_SCHEMA.TABLES
+WHERE TABLE_TYPE = 'BASE TABLE'
+ORDER BY TABLE_SCHEMA, TABLE_NAME;
+
+SELECT COLUMN_NAME, DATA_TYPE, IS_NULLABLE
+FROM INFORMATION_SCHEMA.COLUMNS
+WHERE TABLE_SCHEMA = '<schema>'
+  AND TABLE_NAME = '<table_name>'
+ORDER BY ORDINAL_POSITION;
+```
+
+## MySQL And MariaDB
+
+建議使用的 clients: `mysql`、`mariadb`。
+
+```powershell
+$env:MYSQL_PWD = "<password>"
+mysql --host=<host> --port=<port> --user=<username> --database=<database> --execute="SELECT 1;"
+Remove-Item Env:\MYSQL_PWD
+```
+
+實用的 inspection queries：
+
+```sql
+SELECT TABLE_SCHEMA, TABLE_NAME
+FROM information_schema.TABLES
+WHERE TABLE_SCHEMA = '<database>'
+ORDER BY TABLE_NAME
+LIMIT 50;
+
+SELECT COLUMN_NAME, DATA_TYPE, IS_NULLABLE
+FROM information_schema.COLUMNS
+WHERE TABLE_SCHEMA = '<database>'
+  AND TABLE_NAME = '<table_name>'
+ORDER BY ORDINAL_POSITION;
+```
+
+## SQLite
+
+建議使用的 client: `sqlite3`。
+
+```powershell
+sqlite3 <database_file> "SELECT 1;"
+```
+
+實用的 inspection commands：
+
+```sql
+.tables
+PRAGMA table_info('<table_name>');
+SELECT name, type FROM sqlite_master WHERE type IN ('table', 'view') ORDER BY name LIMIT 50;
+```
+
+## IBM Db2
+
+建議使用的 client: `db2`。
+
+```powershell
+db2 connect to <database> user <username> using <password>
+db2 -x "SELECT 1 FROM sysibm.sysdummy1"
+db2 connect reset
+```
+
+實用的 inspection queries：
+
+```sql
+SELECT tabschema, tabname
+FROM syscat.tables
+WHERE type = 'T'
+ORDER BY tabschema, tabname
+FETCH FIRST 50 ROWS ONLY;
+
+SELECT colname, typename, nulls
+FROM syscat.columns
+WHERE tabschema = UPPER('<schema>')
+  AND tabname = UPPER('<table_name>')
+ORDER BY colno;
+```
+
+## H2
+
+H2 常見於 tests 或 local development 中以 embedded 方式使用。優先使用 repo 的 test profile 或 app 提供的 console/tooling。
+
+常見的 JDBC URL patterns：
+
+```text
+jdbc:h2:mem:<database>
+jdbc:h2:file:<path>
+```
+
+實用的 inspection query：
+
+```sql
+SELECT TABLE_SCHEMA, TABLE_NAME
+FROM INFORMATION_SCHEMA.TABLES
+ORDER BY TABLE_SCHEMA, TABLE_NAME
+LIMIT 50;
+```

package/.github/skills/database-query/references/query-safety.md

@@ -0,0 +1,109 @@
+# Query Safety
+
+## Read-Only Default
+
+除非 user 明確要求資料修改，否則預設只允許 metadata 與 read-only `SELECT`。如果查詢內容涉及下列操作，必須先停下來確認：
+
+- `INSERT`, `UPDATE`, `DELETE`, `MERGE`, `TRUNCATE`
+- `CREATE`, `ALTER`, `DROP`
+- `GRANT`, `REVOKE`
+- 可能修改資料的 stored procedure/function/package calls
+- scheduler/job control、queue dequeue、lock/session kill
+
+## Row Limits By Dialect
+
+請使用有筆數上限的查詢：
+
+```sql
+-- PostgreSQL, MySQL, MariaDB, SQLite, H2
+SELECT <columns>
+FROM <table>
+WHERE <condition>
+LIMIT 50;
+```
+
+```sql
+-- SQL Server
+SELECT TOP (50) <columns>
+FROM <schema>.<table>
+WHERE <condition>;
+```
+
+```sql
+-- Oracle 12c+, IBM Db2
+SELECT <columns>
+FROM <schema>.<table>
+WHERE <condition>
+FETCH FIRST 50 ROWS ONLY;
+```
+
+```sql
+-- Older Oracle
+SELECT <columns>
+FROM <schema>.<table>
+WHERE <condition>
+  AND ROWNUM <= 50;
+```
+
+## Oracle Empty String Semantics
+
+這一節只在已確認 `db_type`、driver 或 client session 是 Oracle 時適用。不要把這組規則套用到 PostgreSQL、SQL Server、MySQL、MariaDB、SQLite、Db2 或其他 DB。
+
+Oracle 會把 `''` 視為 `NULL`。因此 Oracle predicate 對空字串的處理要直接用 `NULL` 語意，不要把 `''` 當成一般字串比較。
+
+- 不要用 `= ''`、`<> ''`，也不要用 `TRIM(NVL(<column>, '')) <> ''` 判斷空值或非空值。
+- 判斷 `NULL` / 非 `NULL` 時，使用 `IS NULL` 或 `IS NOT NULL`。
+- 判斷 trim 後是否有內容時，優先使用 `LENGTH(TRIM(NVL(<column>, ' '))) = 0` 或 `> 0`；若只需要確認 trim 後有值，可用 `TRIM(<column>) IS NOT NULL`。
+- 若 query 結果意外為 0 rows，先檢查是否誤用了 Oracle empty-string 語意，再解讀資料是否真的為空。
+
+範例：
+
+```sql
+-- Avoid in Oracle
+WHERE path_program <> ''
+```
+
+```sql
+-- Avoid in Oracle even after wrapping with TRIM/NVL
+WHERE TRIM(NVL(path_program, '')) <> ''
+```
+
+```sql
+-- Prefer when checking for the presence of a trimmed value
+WHERE TRIM(path_program) IS NOT NULL
+```
+
+```sql
+-- Prefer when checking for a non-empty value after trimming
+WHERE LENGTH(TRIM(NVL(path_program, ' '))) > 0
+```
+
+## Safer Investigation Pattern
+
+1. 先透過 metadata 確認 schema/table 存在。
+2. 只有在安全的前提下，才檢查大致筆數或精確 count。
+3. 先查 grouped summary，再看 row sample。
+4. 以關鍵欄位查詢範圍較小的 sample。
+5. 依照 user request 加上業務過濾條件。
+
+範例：
+
+```sql
+SELECT status, COUNT(*) AS row_count
+FROM <schema>.<table>
+WHERE created_at >= <start_date>
+GROUP BY status
+ORDER BY row_count DESC;
+```
+
+## Reporting
+
+最終回覆應提供足夠證據，讓結果可被重現，同時避免洩露敏感資訊：
+
+- connection source：`src/main/resources/application-dev.yml`、`.env`、`docker-compose.yml`、user-provided session value
+- DB type 與 target environment
+- SQL statements；如果使用了敏感 literal，則改提供摘要化 SQL
+- result rows 或 aggregate summary
+- 不確定之處與 permission gaps
+
+不可包含 plaintext password values、token values、帶有憑證資訊的 URL，或任何 private network secrets。