# @darkmoon_ai/client

> Cross-version common client contract for Darkmoon OSS (CLI) and Darkmoon Pro (REST). Foundation for the 5 official integrations.

Latest version **0.1.1** (published 2026-09-24) · MIT license · 0 weekly downloads

## Install

```sh
npm install @darkmoon_ai/client
pnpm add @darkmoon_ai/client
yarn add @darkmoon_ai/client
bun add @darkmoon_ai/client
```

Provides the command `darkmoon-ci`.

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.1.1 |
| Published | 2026-09-24 |
| First published | 2026-09-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18 |
| Dependencies | 1 |
| Unpacked size | 490.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | ASC-IT |
| Maintainers | darkmoon_pentest |
| Keywords | darkmoon, pentest, security, sast, dast, ci, vulnerability |

## Links

- npm: https://www.npmjs.com/package/@darkmoon_ai/client
- Repository: https://github.com/ASCIT31/darkmoon-client
- Homepage: https://github.com/ASCIT31/darkmoon-client#readme
- Issues: https://github.com/ASCIT31/darkmoon-client/issues
- npm.io page: https://npm.io/package/@darkmoon_ai/client

## Dependencies (1)

- [zod](https://npm.io/package/zod.md) ^3.23.8

## Alternatives

- [random-seedable](https://npm.io/package/random-seedable.md) — 27.9K weekly downloads
- [n2words](https://npm.io/package/n2words.md) — 22.2K weekly downloads
- [@stdlib/math-base-special-factorialln](https://npm.io/package/@stdlib/math-base-special-factorialln.md) — 5.7K weekly downloads
- [@stdlib/math-base-special-abs2](https://npm.io/package/@stdlib/math-base-special-abs2.md) — 1.7K weekly downloads
- [commons-math-interpolation](https://npm.io/package/commons-math-interpolation.md) — 1.4K weekly downloads

## Recent versions

- 0.1.1 (latest) — 2026-09-24
- 0.1.0 — 2026-09-24

## README

# @darkmoon_ai/client


## ⭐ Darkmoon ecosystem

Darkmoon is open-source — **a star really helps us grow.** [![Star the Darkmoon core](https://img.shields.io/github/stars/ASCIT31/Dark-Moon?style=social&label=Star%20Darkmoon)](https://github.com/ASCIT31/Dark-Moon)

🌐 **Website:** [dark-moon.org](https://dark-moon.org) · 📚 **Docs:** [docs.dark-moon.org](https://docs.dark-moon.org) · ⭐ **Star the core:** [github.com/ASCIT31/Dark-Moon](https://github.com/ASCIT31/Dark-Moon)

**Install the integrations, right where you work:**

| Platform | Get it |
|---|---|
| VS Code | [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=Darkmoon.darkmoon-vscode) |
| JetBrains | [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/34497-darkmoon) |
| GitHub Actions | [GitHub Marketplace](https://github.com/marketplace/actions/darkmoon-pentest) |
| GitLab CI/CD | [CI/CD Catalog](https://gitlab.com/explore/catalog/Dark-Moon-X/darkmoon-scan) |
| Jenkins | [Download the .hpi](https://github.com/ASCIT31/darkmoon-jenkins/releases) |
| Client & CLI | [npm: @darkmoon_ai/client](https://www.npmjs.com/package/@darkmoon_ai/client) |


## Install / build

```bash
npm install
npm run ci        # lint → typecheck → test → build
```

## Library usage

```ts
import { DarkmoonClient, computeFailPolicy } from "@darkmoon_ai/client";

const client = new DarkmoonClient({
  mode: "auto",
  pro: { baseUrl: "http://host:8000", username: "ci", password: process.env.DM_PASS },
  oss: { dataDir: "/data/darkmoon-settings", reportsDir: "/data/reports" },
});

const caps = await client.detect();                       // which edition + features
const launched = await client.launchCampaign({ target: "http://app:3000", focus: ["sqli"] });
const campaign = await client.waitForCompletion(launched, { timeoutMs: 30 * 60_000 });
const summary  = await client.getSeveritySummary(campaign.id);
const findings = await client.listFindings({ campaignId: campaign.id });
const verdict  = computeFailPolicy(findings, "critical,high");
if (verdict.failed) process.exit(verdict.exitCode);       // exit 2
```

## CLI (`darkmoon-ci`)

```bash
darkmoon-ci detect  --mode auto --pro-url http://host:8000
darkmoon-ci run     --target http://app:3000 --fail-on critical,high --json
darkmoon-ci summary <campaignId> --mode oss --oss-data-dir /data/darkmoon-settings
darkmoon-ci report  <campaignId> --out report.md          # redacted by default
```

Exit codes: `0` pass · `2` fail-policy tripped · `1` tool/usage error.
Backends configure via flags or env (`DARKMOON_PRO_URL`, `DARKMOON_PRO_USER`,
`DARKMOON_PRO_PASS`, `DARKMOON_PRO_TOKEN`, `DARKMOON_OSS_DATA_DIR`, …).

## Editions

| | OSS (`OssLocalBackend`) | Pro (`ProHttpBackend`) |
|---|---|---|
| Transport | reads the on-disk JSON tree, launches `darkmoon.sh` | `/api/v1` REST + JWT + SSE |
| Launch | `opencode run "TARGET: … PROGRAM=ci-<nonce>"` | `POST /run/campaign` |
| Correlation | snapshot-diff + session-id + mtime | `run_id`→campaign via session-id / diff |
| Progress | synthetic poll stream | live SSE `/run/{id}/stream` |
| Report not ready | missing/empty file | placeholder-200 → `ReportNotReady` |
| Dashboard / remediation / scheduler | no | yes (Pro only) |

The OSS CLI produces terminal/JSON + Markdown reports; the web dashboard and the
remediation→PR flow are **Pro only** and are never presented as open source.

## Layout

```
src/            library (contract, backends, normalize, redact, schema, fail-policy)
cli/            darkmoon-ci portable CLI
fixtures/       real captured campaigns/vulns + conformance goldens
test/           unit · integration · conformance (both backends) · fault injection
CONTRACT.md     the frozen API + link method for the 5 integrations
```

## Tests

Real OSS validation runs against the local WSL stack and an authorized lab
(Juice Shop). Pro validation runs against the real Front-API FastAPI locally and
a contract mock for fault injection. See `test/` and the delivery notes.

---
_Source: https://npm.io/package/@darkmoon_ai/client · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._