@daocloud-cli/dce 0.1.0-rc.7

package/README.md

@@ -0,0 +1,267 @@
+# daocloud-skills
+
+A generated CLI and AI skill package for DaoCloud Enterprise (DCE). It wraps the DCE REST API into a `dce` command-line tool and bundles a companion skill for AI agents.
+
+## Overview
+
+- **`dce`** — a CLI generated from DCE OpenAPI specs (global-management, container-management). Supports API discovery, search, and execution with built-in auth management.
+- **`skills/dce`** — an AI agent skill that teaches agents how to use `dce` safely.
+
+Currently supported products:
+
+| Module | Description |
+|---|---|
+| `global-management` | Global Management — users, groups, workspaces, roles, audit |
+| `container-management` | Container Management — clusters, namespaces, workloads, storage |
+| `insight` | Insight — observability, metrics, alerting, and related operations |
+
+## Prerequisites
+
+- Go 1.25+
+- Git (for spec sync)
+- Docker with [buildx](https://docs.docker.com/buildx/working-with-buildx/) (for container image builds)
+
+## Quick Start
+
+```bash
+# Sync OpenAPI specs and regenerate code
+make bootstrap
+
+# Build dce
+make build
+
+# Install dce and symlink skill for local development
+make dev
+```
+
+The `make dev` target installs `dce` to `/usr/local/bin` and symlinks `skills/dce` into `~/.agents/skills/dce` for live local development in an AI agent runtime.
+
+## Install the Skill
+
+Install the `dce` skill globally:
+
+```bash
+npx skills add daocloud/daocloud-skills -g
+```
+
+For non-interactive installs, add confirmation flags:
+
+```bash
+npx -y skills add daocloud/daocloud-skills -g -y
+```
+
+The `-g` flag installs the skill into the selected agent's user-level skills directory, so it is available across projects. Omit `-g` if you want to install the skill only for the current project.
+
+This installs the skill only. The skill helps an AI agent use `dce`, but it does not install the `dce` CLI. Install the CLI separately before running DCE operations.
+
+### Install for a Specific Agent
+
+Use `--agent` to install the `dce` skill for a specific AI coding agent. Common client targets include:
+
+**Claude Code**
+
+```bash
+npx skills add daocloud/daocloud-skills -g --skill dce --agent claude-code
+```
+
+**Codex**
+
+```bash
+npx skills add daocloud/daocloud-skills -g --skill dce --agent codex
+```
+
+**Cursor**
+
+```bash
+npx skills add daocloud/daocloud-skills -g --skill dce --agent cursor
+```
+
+Use `--agent` more than once to install the same skill into multiple agents:
+
+```bash
+npx skills add daocloud/daocloud-skills -g \
+  --skill dce \
+  --agent claude-code \
+  --agent codex \
+  --agent cursor
+```
+
+This installs the skill from the repository's default branch. To inspect available skills before installing:
+
+```bash
+npx skills add daocloud/daocloud-skills --list
+```
+
+To uninstall the global `dce` skill, use `remove` with the same agent target:
+
+```bash
+npx skills remove -g dce --agent codex
+```
+
+After installation, open a new agent session and ask it to use the `dce` skill for DCE operations, for example:
+
+```text
+Use the dce skill to list DCE clusters.
+```
+
+## Install the CLI
+
+The recommended way is via npm:
+
+```bash
+npm install -g @daocloud-cli/dce
+```
+
+Or run on demand without a global install:
+
+```bash
+npx @daocloud-cli/dce --help
+```
+
+The npm package downloads the matching prebuilt binary from GitHub Releases on install and verifies it against `checksums.txt`. Supported platforms: `darwin`/`linux` on `amd64`/`arm64`, Node.js >= 16.
+
+Alternatively, download a prebuilt archive from GitHub Releases directly:
+
+```bash
+VERSION=v0.1.0-rc.6
+OS=darwin
+ARCH=amd64
+PKG="dce-${VERSION}-${OS}-${ARCH}"
+
+curl -fL "https://github.com/DaoCloud/daocloud-skills/releases/download/${VERSION}/${PKG}.tar.gz" -o dce.tar.gz
+tar -xzf dce.tar.gz
+sudo install -m 0755 "${PKG}/dce" /usr/local/bin/dce
+```
+
+Use `OS=darwin` for macOS and `OS=linux` for Linux. Use `ARCH=arm64` for Apple Silicon or ARM64 Linux, and `ARCH=amd64` for Intel macOS or x86_64 Linux.
+
+Verify the CLI is available:
+
+```bash
+dce --help
+```
+
+For source builds from this repository:
+
+```bash
+make build
+sudo cp bin/dce /usr/local/bin/dce
+```
+
+For local development, use `make dev` to build the CLI, copy it to `/usr/local/bin/dce`, and symlink the local skill directory:
+
+```bash
+make dev
+```
+
+## Usage
+
+```bash
+# Log in to a DCE instance
+dce auth login --hostname https://<dce-host>
+
+# Browse available commands
+dce commands --json
+
+# Search for a command by intent
+dce search "list clusters" --json
+
+# Inspect a command before executing
+dce commands show container-management cluster list-clusters --json
+
+# Execute a command
+dce container-management cluster list-clusters -o json
+```
+
+## Container Image
+
+The image bundles the `dce` binary and the `skills/dce` directory under `/app/`, intended for use as a Kubernetes init container to distribute the tooling into a shared volume.
+
+```bash
+# Build multi-arch image locally
+make image
+
+# Build and push to registry
+make image-push IMAGE_REPO=registry.example.com/dce IMAGE_TAG=v1.0.0
+```
+
+Default values: `IMAGE_REPO=daocloud/dce`, `IMAGE_TAG=latest`.
+
+### Init Container Example
+
+```yaml
+initContainers:
+  - name: install-dce
+    image: daocloud/dce:latest
+    command:
+      - sh
+      - -c
+      - |
+        cp /app/dce /target/bin/dce
+        cp -r /app/skills/dce /target/.agents/skills/dce
+    volumeMounts:
+      - name: tools
+        mountPath: /target
+
+volumes:
+  - name: tools
+    emptyDir: {}
+```
+
+After the init container completes, the shared volume contains:
+
+- `/target/bin/dce` — CLI binary
+- `/target/.agents/skills/dce/` — AI agent skill
+
+## Development
+
+| Target | Description |
+|---|---|
+| `make bootstrap` | Sync specs + regenerate all code |
+| `make specsync` | Pull latest OpenAPI specs from upstream |
+| `make codegen` | Regenerate Go code and skill references from specs |
+| `make sync-one SOURCE=<name>` | Sync and regenerate a single source (e.g. `ghippo`) |
+| `make build` | Build `bin/dce` |
+| `make image` | Build multi-arch image locally (`linux/amd64`, `linux/arm64`) |
+| `make image-push` | Build and push multi-arch image to registry |
+| `make dev` | Build, install, and symlink skill for local debugging |
+| `make dev-clean` | Remove installed binary and skill symlink |
+| `make clean` | Remove `.cache` and `bin` |
+
+## Project Structure
+
+```
+.
+├── cli.yaml                  # CLI name and auth config
+├── specs/sources.yaml        # OpenAPI source definitions (pinned commits)
+├── internal/
+│   ├── generated/            # Generated Go command modules (do not edit)
+│   └── overlay/              # Per-source field overrides for codegen
+├── skills/dce/            # AI agent skill (SKILL.md + references)
+├── docs/                     # Developer guides
+├── cmd/dce/main.go        # CLI entrypoint
+└── doc.go                    # Embeds cli.yaml for use by main
+```
+
+## Guides
+
+- [Adding a new product](docs/add-new-product.md) — step-by-step guide for onboarding a new DCE product (spec source, overlay, codegen, verification)
+
+## How It Works
+
+1. **`specsync`** clones the pinned commit of `daocloud-api-docs` and extracts the OpenAPI JSON files into `.cache/specs-sync/`.
+2. **`codegen`** reads each spec, applies the overlay from `internal/overlay/<source>.yaml`, and emits:
+   - Go cobra subcommands under `internal/generated/<source>/`
+   - A command index at `skills/dce/references/modules/<source>.md`
+   - An updated `internal/generated/modules_gen.go` that mounts all modules
+3. **`go build`** compiles everything into a single static binary `bin/dce`.
+
+Overlay files are the only place where human-maintained configuration lives — everything else is generated and should not be edited by hand.
+
+## Updating a Pinned Spec
+
+Update the `pinned_tag` for the relevant source in `specs/sources.yaml`, then run:
+
+```bash
+make sync-one SOURCE=<name>
+```

package/checksums.txt

@@ -0,0 +1,4 @@
+a324997b6acdb1fd01a92e31d024f62bac979e10d0c5057fe19ad3639eec67fe  dce-v0.1.0-rc.7-darwin-amd64.tar.gz
+89214cdfa1f66b34a961932bc2ad55645b5247d742f8a85dd7780f7954facb36  dce-v0.1.0-rc.7-darwin-arm64.tar.gz
+d65367f8ad0d133815914cbdb36fe1b0b46930cf1fabae280b189395014aa5d1  dce-v0.1.0-rc.7-linux-amd64.tar.gz
+60c09746187eaf0f865761e7a36ac8cab6a07c1619b37f652b4897c32c93ca0a  dce-v0.1.0-rc.7-linux-arm64.tar.gz

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@daocloud-cli/dce",
+  "version": "0.1.0-rc.7",
+  "description": "DaoCloud dce CLI",
+  "bin": {
+    "dce": "scripts/run.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/install.js"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DaoCloud/daocloud-skills.git"
+  },
+  "license": "Apache-2.0",
+  "files": [
+    "scripts/install.js",
+    "scripts/run.js",
+    "checksums.txt"
+  ]
+}

package/scripts/install.js

@@ -0,0 +1,145 @@
+const fs = require("fs");
+const path = require("path");
+const { execFileSync } = require("child_process");
+const os = require("os");
+const crypto = require("crypto");
+
+const VERSION = require("../package.json").version;
+const REPO = "DaoCloud/daocloud-skills";
+const NAME = "dce";
+const ALLOWED_HOSTS = new Set([
+  "github.com",
+  "objects.githubusercontent.com",
+]);
+
+const PLATFORM_MAP = {
+  darwin: "darwin",
+  linux: "linux",
+};
+
+const ARCH_MAP = {
+  x64: "amd64",
+  arm64: "arm64",
+};
+
+const platform = PLATFORM_MAP[process.platform];
+const arch = ARCH_MAP[process.arch];
+
+const TAG = `v${VERSION}`;
+const PKG_NAME = `${NAME}-${TAG}-${platform}-${arch}`;
+const archiveName = `${PKG_NAME}.tar.gz`;
+const GITHUB_URL = `https://github.com/${REPO}/releases/download/${TAG}/${archiveName}`;
+
+const pkgRoot = path.join(__dirname, "..");
+const binDir = path.join(pkgRoot, "bin");
+const dest = path.join(binDir, NAME);
+
+function assertAllowedHost(url) {
+  const { hostname } = new URL(url);
+  if (!ALLOWED_HOSTS.has(hostname)) {
+    throw new Error(`Download host not allowed: ${hostname}`);
+  }
+}
+
+function download(url, destPath) {
+  assertAllowedHost(url);
+  execFileSync(
+    "curl",
+    [
+      "--fail", "--location", "--silent", "--show-error",
+      "--connect-timeout", "10", "--max-time", "120",
+      "--max-redirs", "3",
+      "--output", destPath,
+      url,
+    ],
+    { stdio: ["ignore", "ignore", "pipe"] }
+  );
+}
+
+function getExpectedChecksum(name) {
+  const checksumsPath = path.join(pkgRoot, "checksums.txt");
+  if (!fs.existsSync(checksumsPath)) {
+    throw new Error(
+      "[SECURITY] checksums.txt not found; refusing to install without integrity verification"
+    );
+  }
+  const content = fs.readFileSync(checksumsPath, "utf8");
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const idx = trimmed.indexOf("  ");
+    if (idx === -1) continue;
+    const hash = trimmed.slice(0, idx);
+    const entry = trimmed.slice(idx + 2);
+    if (entry === name) return hash;
+  }
+  throw new Error(`Checksum entry not found for ${name}`);
+}
+
+function verifyChecksum(archivePath, expectedHash) {
+  const hash = crypto.createHash("sha256");
+  const fd = fs.openSync(archivePath, "r");
+  try {
+    const buf = Buffer.alloc(64 * 1024);
+    let bytesRead;
+    while ((bytesRead = fs.readSync(fd, buf, 0, buf.length, null)) > 0) {
+      hash.update(buf.subarray(0, bytesRead));
+    }
+  } finally {
+    fs.closeSync(fd);
+  }
+  const actual = hash.digest("hex");
+  if (actual.toLowerCase() !== expectedHash.toLowerCase()) {
+    throw new Error(
+      `[SECURITY] Checksum mismatch for ${path.basename(archivePath)}: expected ${expectedHash} but got ${actual}`
+    );
+  }
+}
+
+function install() {
+  fs.mkdirSync(binDir, { recursive: true });
+
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), `${NAME}-`));
+  const archivePath = path.join(tmpDir, archiveName);
+
+  try {
+    download(GITHUB_URL, archivePath);
+
+    const expected = getExpectedChecksum(archiveName);
+    verifyChecksum(archivePath, expected);
+
+    execFileSync("tar", ["-xzf", archivePath, "-C", tmpDir], { stdio: "ignore" });
+
+    const extractedRoot = path.join(tmpDir, PKG_NAME);
+    const extractedBinary = path.join(extractedRoot, NAME);
+
+    fs.copyFileSync(extractedBinary, dest);
+    fs.chmodSync(dest, 0o755);
+
+    console.log(`${NAME} ${TAG} installed successfully`);
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+if (require.main === module) {
+  if (!platform || !arch) {
+    console.error(`Unsupported platform: ${process.platform}-${process.arch}`);
+    process.exit(1);
+  }
+
+  // Under `npx`, postinstall fires but the binary is not yet needed —
+  // run.js triggers install() on demand with DCE_RUN=1 set.
+  const isNpxPostinstall =
+    process.env.npm_command === "exec" && !process.env.DCE_RUN;
+  if (isNpxPostinstall) process.exit(0);
+
+  try {
+    install();
+  } catch (err) {
+    console.error(`Failed to install ${NAME}:`, err.message);
+    process.exit(1);
+  }
+}
+
+module.exports = { getExpectedChecksum, verifyChecksum, assertAllowedHost };

package/scripts/run.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+
+const { execFileSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+
+const bin = path.join(__dirname, "..", "bin", "dce");
+const args = process.argv.slice(2);
+
+if (!fs.existsSync(bin)) {
+  try {
+    execFileSync(process.execPath, [path.join(__dirname, "install.js")], {
+      stdio: "inherit",
+      env: { ...process.env, DCE_RUN: "true" },
+    });
+  } catch (_) {
+    console.error(
+      `\nFailed to auto-install dce binary.\n` +
+      `Run the install script manually:\n` +
+      `  node "${path.join(__dirname, "install.js")}"\n`
+    );
+    process.exit(1);
+  }
+}
+
+try {
+  execFileSync(bin, args, { stdio: "inherit" });
+} catch (e) {
+  process.exit(e.status || 1);
+}