cfgov-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,56 @@
+# cfgov-cli
+
+> **Status: early development (P0).** Private, pre-release. The command surface and APIs may change without notice until `v0.1.0`.
+
+Governed CLI for the configuration-governance domain. `cfgov-cli` aims to be the single entry point for config / rule / service-governance middleware (Nacos, Sentinel rules, Apollo, and more), built on the shared [`opskit-core`](https://github.com/JiangHe12/opskit-core) governance engine. It sits alongside `dbgov-cli` (database governance) and `srvgov-cli` (server governance).
+
+P0 ships a Nacos-only governance kernel that proves the spine: a unified backend abstraction, the R0–R3 authorization ladder with protected-context escalation, fail-closed config-write risk classification, audit, and capabilities introspection.
+
+## Architecture
+
+`cfgov-cli` is built on two orthogonal layers:
+
+- **Storage backends** — a namespaced key/value + blob store with revisions and CAS. P0 implements **Nacos**; Apollo / Consul / etcd / Kubernetes are planned. Backend-specific addressing (e.g. Nacos `group/dataId`) is confined to the adapter.
+- **Typed schemas** — config blobs today; Sentinel rules and other policy types (gateway routes, feature flags, …) layer on top of any backend in later phases.
+
+A backend is bound to a context (`ctx set --backend nacos`), like `dbgov`'s engine selection; `--backend` overrides per command.
+
+## Governance Model
+
+| Risk | Meaning | Authorization |
+|---|---|---|
+| R0 | reads and local inspection (still audited) | none |
+| R1 | ordinary writes (`config push`) | `--yes` or interactive confirmation |
+| R2 | destructive / elevated (`config delete`) | `--ticket` + `--yes` |
+| R3 | protected destructive operations | `--ticket` + command-specific `--allow-*` + `--yes` |
+
+Protected contexts raise every operation one tier (`config delete` in a protected context becomes R3 and requires `--allow-production-config-delete`). Impact and blast radius come from the CLI's own `--dry-run` / `--diff`, never from a model guess. **AI agents and automation must never invent `--ticket`, `--allow-*`, or a high-risk `--yes`** — surface missing authorization to the operator.
+
+## Commands (P0)
+
+```
+cfgov ctx set <name> --backend nacos --server <url> [--username <u>] [--namespace <ns>] [--protected]
+cfgov ctx use|list|current
+cfgov config get    --key <dataId|group/dataId>
+cfgov config push   --key <key> --file <path> [--type text|properties|json|yaml] [--dry-run]
+cfgov config delete --key <key> [--ticket <t> --yes] [--allow-production-config-delete]
+cfgov capabilities
+cfgov audit query|verify
+cfgov version
+```
+
+Use `-o json` for automation and AI agents. Credentials are stored via the `opskit-core` credential store; prefer the `NACOS_PASSWORD` env var over `--password`.
+
+## Build & Verify
+
+```bash
+go build ./...
+go test -count=1 ./...
+gofmt -l main.go cmd internal      # must print nothing
+golangci-lint run --timeout=5m
+go vet -tags=integration ./...
+```
+
+## License
+
+[MIT](LICENSE)

package/bin/cfgov-cli.js

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

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "cfgov-cli",
+  "version": "0.1.0",
+  "description": "Governed configuration and Sentinel-rule operations CLI for AI agents (Nacos and Apollo)",
+  "bin": {
+    "cfgov": "bin/cfgov-cli.js",
+    "cfgov-cli": "bin/cfgov-cli.js"
+  },
+  "files": [
+    "bin/",
+    "scripts/install.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/install.js"
+  },
+  "keywords": [
+    "config",
+    "nacos",
+    "apollo",
+    "sentinel",
+    "governance",
+    "cli",
+    "ai"
+  ],
+  "author": "JiangHe12",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JiangHe12/cfgov-cli.git"
+  },
+  "homepage": "https://github.com/JiangHe12/cfgov-cli",
+  "engines": {
+    "node": ">=14"
+  }
+}

package/scripts/install.js

@@ -0,0 +1,230 @@
+#!/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 pkg = require('../package.json');
+const VERSION = pkg.version;
+const REPO = 'JiangHe12/cfgov-cli';
+const TIMEOUT_MS = 30000;
+
+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);
+    return ALLOWED_REDIRECT_HOSTS.has(parsed.hostname) || parsed.hostname.endsWith('.github.io');
+  } catch {
+    return false;
+  }
+}
+
+function applyMirror(canonicalUrl) {
+  const mirror = process.env.CFGOV_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 platformMap = { win32: 'windows', darwin: 'darwin', linux: 'linux' };
+  const archMap = { x64: 'amd64', arm64: 'arm64' };
+  return {
+    os: platformMap[process.platform] || process.platform,
+    arch: archMap[process.arch] || process.arch,
+  };
+}
+
+function getBinaryName() {
+  const { os, arch } = getPlatform();
+  const ext = os === 'windows' ? '.exe' : '';
+  return `cfgov-cli-${os}-${arch}${ext}`;
+}
+
+function getDownloadUrl() {
+  const binary = getBinaryName();
+  return applyMirror(`https://github.com/${REPO}/releases/download/v${VERSION}/${binary}`);
+}
+
+function request(url, onResponse) {
+  const req = pickClient(url).get(url, onResponse);
+  req.setTimeout(TIMEOUT_MS, () => {
+    req.destroy(new Error(`Download timed out after ${TIMEOUT_MS / 1000}s`));
+  });
+  return req;
+}
+
+function redirectTarget(currentUrl, response) {
+  return new URL(response.headers.location, currentUrl).toString();
+}
+
+function download(url, dest, redirectCount = 0) {
+  return new Promise((resolve, reject) => {
+    if (redirectCount > 5) {
+      reject(new Error('Too many redirects'));
+      return;
+    }
+
+    const req = request(url, (response) => {
+      if (response.statusCode === 301 || response.statusCode === 302 ||
+          response.statusCode === 307 || response.statusCode === 308) {
+        response.resume();
+        const target = redirectTarget(url, response);
+        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) {
+        response.resume();
+        reject(new Error(`Download failed: ${response.statusCode}`));
+        return;
+      }
+
+      const file = fs.createWriteStream(dest);
+      response.pipe(file);
+      file.on('finish', () => file.close(resolve));
+      file.on('error', (err) => {
+        response.destroy();
+        fs.unlink(dest, () => {});
+        reject(err);
+      });
+    });
+    req.on('error', (err) => {
+      fs.unlink(dest, () => {});
+      reject(err);
+    });
+  });
+}
+
+function getChecksumsUrl() {
+  return `https://github.com/${REPO}/releases/download/v${VERSION}/checksums.txt`;
+}
+
+function downloadToString(url, redirectsLeft = 5) {
+  return new Promise((resolve, reject) => {
+    const req = request(url, (response) => {
+      if (response.statusCode === 301 || response.statusCode === 302 ||
+          response.statusCode === 307 || response.statusCode === 308) {
+        response.resume();
+        if (redirectsLeft <= 0) {
+          reject(new Error('Too many redirects'));
+          return;
+        }
+        const target = redirectTarget(url, response);
+        if (!isAllowedRedirectHost(target)) {
+          reject(new Error(`Redirect to non-allowed host rejected: ${target}`));
+          return;
+        }
+        downloadToString(target, redirectsLeft - 1).then(resolve).catch(reject);
+        return;
+      }
+      if (response.statusCode !== 200) {
+        response.resume();
+        reject(new Error(`Download failed: ${response.statusCode}`));
+        return;
+      }
+      let data = '';
+      response.setEncoding('utf8');
+      response.on('data', (chunk) => { data += chunk; });
+      response.on('end', () => resolve(data));
+    });
+    req.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 match = line.trim().match(/^([a-f0-9]{64})\s+\*?(.+)$/);
+    if (match) checksums[match[2]] = match[1];
+  }
+  return checksums;
+}
+
+async function verifyDownloadedBinary(binaryPath, binaryName) {
+  if (process.env.CFGOV_CLI_SKIP_VERIFY === '1') {
+    console.log('Verification skipped (CFGOV_CLI_SKIP_VERIFY=1)');
+    return;
+  }
+  const checksumsUrl = getChecksumsUrl();
+  let checksums;
+  try {
+    checksums = parseChecksums(await downloadToString(checksumsUrl));
+  } catch (err) {
+    throw new Error(
+      `Could not fetch canonical checksums.txt from ${checksumsUrl}: ${err.message}. ` +
+      'Set CFGOV_CLI_SKIP_VERIFY=1 to install without checksum verification.'
+    );
+  }
+  if (!checksums[binaryName]) {
+    throw new Error(
+      `No checksum found for ${binaryName}. ` +
+      'Set CFGOV_CLI_SKIP_VERIFY=1 to install without checksum verification.'
+    );
+  }
+  const actual = await sha256File(binaryPath);
+  if (actual !== checksums[binaryName]) {
+    try { fs.unlinkSync(binaryPath); } catch {}
+    throw new Error(
+      `SHA-256 mismatch for ${binaryName}\n` +
+      `  Expected: ${checksums[binaryName]}\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' ? 'cfgov.exe' : 'cfgov');
+
+  console.log(`Installing cfgov v${VERSION} for ${os}/${arch}...`);
+  fs.mkdirSync(destDir, { recursive: true });
+
+  try {
+    await download(url, dest);
+    await verifyDownloadedBinary(dest, binary);
+    if (os !== 'windows') fs.chmodSync(dest, 0o755);
+    console.log('cfgov installed successfully!');
+  } catch (err) {
+    console.error('Failed to install cfgov:', err.message);
+    console.error('');
+    console.error('Please download manually from:');
+    console.error(`  ${url}`);
+    process.exit(1);
+  }
+}
+
+main();