dbgov-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JiangHe12
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# dbgov-cli
+
+[English](README.md) | [中文](README_zh.md)
+
+Governed MySQL operations CLI for AI agents and operators. It provides read queries, schema planning and apply, governed DML, GitOps import/reconcile/rollback, audit, RBAC, and local credential management.
+
+## Overview
+
+`dbgov` is built around a governance spine: connect to MySQL, classify risk, require explicit authorization for writes, execute through backend interfaces, and write structured audit events. It is MySQL-only today; PostgreSQL is planned but not enabled unless capabilities report it.
+
+## Install
+
+```bash
+npm install -g dbgov-cli
+# or
+go install github.com/JiangHe12/dbgov-cli@latest
+```
+
+Release binaries are available from GitHub Releases. npm installs download the matching platform binary.
+
+## Quickstart
+
+```bash
+DBGOV_PASSWORD='<password>' dbgov ctx set local --engine mysql --host 127.0.0.1 --port 3306 --database app --username appuser -o json
+dbgov ctx use local -o json
+dbgov query --sql "SELECT 1" -o json
+dbgov explain --sql "SELECT * FROM users WHERE id = 1" -o json
+dbgov schema list -o json
+```
+
+Use `-o json` for automation and AI agents.
+
+## Governance Model
+
+| Risk | Meaning | Authorization |
+|---|---|---|
+| R0 | read-only operations and local inspection | no approval required, still audited |
+| R1 | incremental writes such as add column, small WHERE DML, incremental import | `--yes` or interactive confirmation |
+| R2 | large-impact WHERE DML or protected-context R1 | non-empty `--ticket` plus `--yes` |
+| R3 | destructive schema, no-WHERE UPDATE/DELETE, prune, destructive rollback | `--ticket`, required `--allow-*`, and `--yes` |
+
+Allow flags are precise: schema drop/modify uses `--allow-destructive`, no-WHERE DML uses `--allow-no-where`, table prune uses `--allow-production-prune`. Rollback has an R2 floor and may require one or both destructive/prune allow flags. If a context defines `ticketPattern`, tickets must match it; by default no pattern is enforced.
+
+RBAC applies to writes: `reader` is R0, `writer` is up to R2, and `admin` is up to R3. AI agents and automation must not auto-fill `--ticket`, `--allow-*`, or high-risk `--yes`. Impact must come from `dbgov explain`, `schema plan`, or `--dry-run`, never model guesses.
+
+All operations, including denied and failed attempts, append to `~/.dbgov/audit.log`. Use `audit query`, `audit verify`, and `audit prune` to inspect, validate, and clean rotated logs.
+
+## Usage
+
+```bash
+dbgov version -o json
+dbgov capabilities -o json
+dbgov doctor config -o json
+dbgov ctx list -o json
+dbgov ctx export local > local.ctx.yaml
+dbgov ctx import -f local.ctx.yaml --rename local-copy -o json
+dbgov query --sql "SELECT * FROM users" -o json
+dbgov explain --sql "SELECT * FROM users WHERE active = 1" -o json
+dbgov schema dump --dir ./schema -o json
+dbgov schema plan -f desired.sql -o json
+dbgov schema apply -f desired.sql --dry-run -o json
+dbgov data exec --sql "UPDATE users SET active=0 WHERE id=1" --dry-run -o json
+dbgov export --dir ./schema -o json
+dbgov import ./schema --dry-run -o json
+dbgov reconcile ./schema --dry-run -o json
+dbgov rollback list -o json
+dbgov audit query --since 24h -o json
+```
+
+## Configuration and Contexts
+
+Contexts live under `~/.dbgov`. Use `ctx set`, `ctx use`, `ctx current`, and `ctx list` to manage them. Credentials may be literal during setup, read from `DBGOV_PASSWORD`, or migrated to secure backends:
+
+```bash
+dbgov ctx export prod > prod.ctx.yaml
+dbgov ctx import -f prod.ctx.yaml --rename prod-copy -o json
+dbgov ctx migrate-credentials --to encrypted-file -o json
+dbgov ctx role set prod --target-operator alice --role writer -o json
+```
+
+Portable context export redacts passwords by default. `--include-credentials` is only allowed for `plain-yaml` or empty credential backends; secure backend credentials must be shared out of band.
+
+Set `DBGOV_OPERATOR` in CI to make audit and RBAC identity stable.
+
+## Rollback and Snapshots
+
+Schema mutations capture a pre-change DDL snapshot before execution. `rollback --to <snapshot>` restores structure only; MySQL data dropped by table or column deletion is not recovered. dbgov prints this warning during rollback planning and execution.
+
+## Build from Source
+
+```bash
+go build ./...
+go test -count=1 ./...
+gofmt -l main.go cmd internal
+golangci-lint run --timeout=5m
+```
+
+MySQL integration tests are opt-in with `DBGOV_TEST_MYSQL_DSN`.
+
+## AI Skill
+
+```bash
+dbgov install claude --skills
+dbgov install codex --skills
+```
+
+## Contributing, Security, License
+
+See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and [LICENSE](LICENSE).

package/bin/dbgov-cli.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+function getBinaryPath() {
+  const platform = os.platform();
+  const binDir = path.join(__dirname);
+  const binaryName = platform === 'win32' ? 'dbgov.exe' : 'dbgov';
+  return path.join(binDir, binaryName);
+}
+
+function main() {
+  const binaryPath = getBinaryPath();
+
+  if (!fs.existsSync(binaryPath)) {
+    console.error('dbgov binary not found. Please reinstall:');
+    console.error('  npm install -g dbgov-cli');
+    process.exit(1);
+  }
+
+  const args = process.argv.slice(2);
+
+  try {
+    const result = spawn(binaryPath, args, {
+      stdio: 'inherit'
+    });
+
+    result.on('exit', (code) => {
+      process.exit(code || 0);
+    });
+  } catch (err) {
+    console.error('Failed to run dbgov:', err.message);
+    process.exit(1);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "dbgov-cli",
+  "version": "0.1.0",
+  "description": "Governed MySQL operations CLI for AI agents",
+  "bin": {
+    "dbgov": "bin/dbgov-cli.js"
+  },
+  "files": [
+    "bin/",
+    "scripts/install.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/install.js"
+  },
+  "keywords": [
+    "database",
+    "mysql",
+    "cli",
+    "ai",
+    "governance"
+  ],
+  "author": "JiangHe12",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JiangHe12/dbgov-cli.git"
+  },
+  "homepage": "https://github.com/JiangHe12/dbgov-cli",
+  "engines": {
+    "node": ">=14"
+  }
+}

package/scripts/install.js

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const https = require('https');
+const http = require('http');
+const crypto = require('crypto');
+const { URL } = require('url');
+const { createWriteStream } = require('fs');
+
+const pkg = require('../package.json');
+const VERSION = pkg.version;
+const REPO = 'JiangHe12/dbgov-cli';
+
+const ALLOWED_REDIRECT_HOSTS = new Set([
+  'github.com',
+  'objects.githubusercontent.com',
+  'github-releases.githubusercontent.com',
+  'release-assets.githubusercontent.com',
+  'github.githubassets.com',
+  'cdn.jsdelivr.net',
+  'fastly.jsdelivr.net',
+]);
+
+function isAllowedRedirectHost(urlStr) {
+  try {
+    const parsed = new URL(urlStr);
+    if (ALLOWED_REDIRECT_HOSTS.has(parsed.hostname)) return true;
+    if (parsed.hostname.endsWith('.github.io')) return true;
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+function applyMirror(canonicalUrl) {
+  const mirror = process.env.DBGOV_CLI_DOWNLOAD_MIRROR;
+  if (!mirror) return canonicalUrl;
+  return mirror.replace(/\/+$/, '') + '/' + canonicalUrl;
+}
+
+function pickClient(url) {
+  return new URL(url).protocol === 'http:' ? http : https;
+}
+
+function getPlatform() {
+  const platform = process.platform;
+  const arch = process.arch;
+
+  const platformMap = {
+    'win32': 'windows',
+    'darwin': 'darwin',
+    'linux': 'linux'
+  };
+
+  const archMap = {
+    'x64': 'amd64',
+    'arm64': 'arm64'
+  };
+
+  return {
+    os: platformMap[platform] || platform,
+    arch: archMap[arch] || arch
+  };
+}
+
+function getBinaryName() {
+  const { os, arch } = getPlatform();
+  const ext = os === 'windows' ? '.exe' : '';
+  return `dbgov-cli-${os}-${arch}${ext}`;
+}
+
+function getDownloadUrl() {
+  const binary = getBinaryName();
+  return applyMirror(`https://github.com/${REPO}/releases/download/v${VERSION}/${binary}`);
+}
+
+function download(url, dest, redirectCount = 0) {
+  return new Promise((resolve, reject) => {
+    if (redirectCount > 5) {
+      reject(new Error('Too many redirects'));
+      return;
+    }
+    const file = createWriteStream(dest);
+
+    pickClient(url).get(url, { timeout: 30000 }, (response) => {
+      if (response.statusCode === 302 || response.statusCode === 301) {
+        const target = response.headers.location;
+        if (!isAllowedRedirectHost(target)) {
+          reject(new Error(`Redirect to non-allowed host rejected: ${target}`));
+          return;
+        }
+        download(target, dest, redirectCount + 1).then(resolve).catch(reject);
+        return;
+      }
+
+      if (response.statusCode !== 200) {
+        reject(new Error(`Download failed: ${response.statusCode}`));
+        return;
+      }
+
+      response.pipe(file);
+      file.on('finish', () => {
+        file.close();
+        resolve();
+      });
+    }).on('error', (err) => {
+      fs.unlink(dest, () => {});
+      reject(err);
+    });
+  });
+}
+
+function getChecksumsUrl() {
+  return `https://github.com/${REPO}/releases/download/v${VERSION}/checksums.txt`;
+}
+
+function downloadToString(url, maxRedirects = 5) {
+  return new Promise((resolve, reject) => {
+    pickClient(url).get(url, { timeout: 30000 }, (response) => {
+      if (response.statusCode === 302 || response.statusCode === 301) {
+        if (maxRedirects <= 0) {
+          reject(new Error('Too many redirects'));
+          return;
+        }
+        downloadToString(response.headers.location, maxRedirects - 1).then(resolve).catch(reject);
+        return;
+      }
+
+      if (response.statusCode !== 200) {
+        reject(new Error(`Download failed: ${response.statusCode}`));
+        return;
+      }
+
+      let data = '';
+      response.on('data', (chunk) => {
+        data += chunk;
+      });
+      response.on('end', () => {
+        resolve(data);
+      });
+    }).on('error', reject);
+  });
+}
+
+function sha256File(filePath) {
+  return new Promise((resolve, reject) => {
+    const hash = crypto.createHash('sha256');
+    const stream = fs.createReadStream(filePath);
+    stream.on('data', (data) => hash.update(data));
+    stream.on('end', () => resolve(hash.digest('hex')));
+    stream.on('error', reject);
+  });
+}
+
+function parseChecksums(text) {
+  const checksums = {};
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const match = trimmed.match(/^([a-f0-9]{64})\s+\*?(.+)$/);
+    if (match) {
+      checksums[match[2]] = match[1];
+    }
+  }
+  return checksums;
+}
+
+async function verifyDownloadedBinary(binaryPath, binaryName) {
+  if (process.env.DBGOV_CLI_SKIP_VERIFY === '1') {
+    console.log('Verification skipped (DBGOV_CLI_SKIP_VERIFY=1)');
+    return;
+  }
+
+  const checksumsUrl = getChecksumsUrl();
+  let checksums = {};
+  try {
+    const checksumsText = await downloadToString(checksumsUrl);
+    checksums = parseChecksums(checksumsText);
+  } catch (err) {
+    throw new Error(
+      `Could not fetch canonical checksums.txt from ${checksumsUrl}: ${err.message}. ` +
+      'Set DBGOV_CLI_SKIP_VERIFY=1 to install without checksum verification.'
+    );
+  }
+
+  if (!checksums[binaryName]) {
+    throw new Error(
+      `No checksum found for ${binaryName}. ` +
+      'Set DBGOV_CLI_SKIP_VERIFY=1 to install without checksum verification.'
+    );
+  }
+
+  const expected = checksums[binaryName];
+  const actual = await sha256File(binaryPath);
+
+  if (actual !== expected) {
+    try { fs.unlinkSync(binaryPath); } catch (e) {}
+    throw new Error(
+      `SHA-256 mismatch for ${binaryName}\n` +
+      `  Expected: ${expected}\n` +
+      `  Actual:   ${actual}\n` +
+      `The downloaded binary may be corrupted or tampered with.`
+    );
+  }
+
+  console.log('SHA-256 verification passed');
+}
+
+async function main() {
+  const { os, arch } = getPlatform();
+  const binary = getBinaryName();
+  const url = getDownloadUrl();
+  const destDir = path.join(__dirname, '..', 'bin');
+  const dest = path.join(destDir, os === 'windows' ? 'dbgov.exe' : 'dbgov');
+
+  console.log(`Installing dbgov v${VERSION} for ${os}/${arch}...`);
+
+  if (!fs.existsSync(destDir)) {
+    fs.mkdirSync(destDir, { recursive: true });
+  }
+
+  try {
+    await download(url, dest);
+    await verifyDownloadedBinary(dest, binary);
+
+    if (os !== 'windows') {
+      fs.chmodSync(dest, 0o755);
+    }
+
+    console.log('dbgov installed successfully!');
+  } catch (err) {
+    console.error('Failed to install dbgov:', err.message);
+    console.error('');
+    console.error('Please download manually from:');
+    console.error(`  ${url}`);
+    process.exit(1);
+  }
+}
+
+main();