@starlight-ai/discord-waifus 0.3.3 → 1.0.1

package/README.md

@@ -1,66 +1,120 @@
-# @starlight-ai/discord-waifus
+# Discord Waifus
 
-`@starlight-ai/discord-waifus` provides the global `waifus` command for the local Discord Waifus stack.
+Local Discord waifu orchestrator with a backend, web UI, Discord gateway clients, provider-specific AI model pipelines, and a global `waifus` CLI.
 
-## Install
+The app runs on your machine, stores its user data under `~/.dc-waifus`, and lets one orchestrator bot decide which configured waifu bot should answer in each Discord channel.
 
-```bash
-npm install -g @starlight-ai/discord-waifus
+## Install From npm
+
+Requires Node.js 20 or newer.
+
+```sh
+npm install -g @starlight-ai/discord-waifus@latest
+waifus start
 ```
 
-From a clone:
+Open the web UI:
 
-```bash
-pnpm --filter @starlight-ai/discord-waifus build
-pnpm --filter @starlight-ai/discord-waifus link --global
+```text
+http://127.0.0.1:3888
 ```
 
-## Typical Flow
+## Install From a GitHub Release
 
-### Existing clone
+Download the `.tgz` release asset, then install it globally:
 
-```bash
-waifus use /path/to/Discord-Waifus
-waifus init-config
-waifus build
+```sh
+npm install -g ./starlight-ai-discord-waifus-1.0.0.tgz
 waifus start
-waifus open
 ```
 
-### First run with no existing project
+## Build From Source
 
-```bash
-waifus
-waifus open
+```sh
+git clone https://github.com/HeavenllyDemon/Discord-Waifus.git
+cd Discord-Waifus
+npm install
+npm run build
+npm run waifus -- start
 ```
 
-On first run, `waifus` downloads the latest GitHub Release bundle into `~/Discord-Waifus`, verifies the checksum when available, saves that directory as the default project root, runs `pnpm install --prod --frozen-lockfile` with the bundled pnpm, initializes local runtime files, and starts the local stack.
+For local development:
+
+```sh
+npm run waifus -- dev
+npm run dev:frontend
+```
 
-### Refresh an existing release-bundle install
+## CLI
 
-```bash
+```text
+waifus help
+waifus start [--host 127.0.0.1] [--port 3888] [--data-root PATH]
+waifus stop [--data-root PATH]
+waifus restart [--host 127.0.0.1] [--port 3888] [--data-root PATH]
+waifus status [--data-root PATH]
+waifus doctor [--data-root PATH]
+waifus clean [--force] [--include-logs] [--data-root PATH]
 waifus update
 ```
 
-`waifus update` downloads the latest GitHub Release bundle into the existing project root, preserves local runtime data such as `.waifus/`, reinstalls runtime dependencies, and restarts the stack if it was already running. It prints progress while resolving the release, downloading, verifying, extracting, applying files, and installing dependencies.
+`DC_WAIFUS_HOME=PATH` overrides the default `~/.dc-waifus` data root.
 
-### Download from GitHub into a custom directory
+## Discord Setup
 
-```bash
-waifus init ~/Discord-Waifus --repo https://github.com/HeavenllyDemon/Discord-Waifus
-waifus start
-waifus open
+Create one Discord application for the orchestrator and one application for each waifu bot. In the web UI:
+
+1. Configure the orchestrator bot token and Application ID in **Orchestrator**.
+2. Configure provider API keys in **Providers**.
+3. Configure each waifu model, persona, and bot token in **Waifus**.
+4. Invite the bots to your Discord server from **Servers**.
+5. Select at least one waifu for each channel where the system should run.
+
+Required gateway intents:
+
+```text
+GUILDS
+GUILD_MESSAGES
+GUILD_MESSAGE_REACTIONS
+MESSAGE_CONTENT
+```
+
+`MESSAGE_CONTENT` must be enabled in the Discord Developer Portal for complete channel context.
+
+## AI Providers
+
+The app groups supported models under:
+
+- x.ai
+- DeepSeek
+- Anthropic
+- OpenAI
+- Z.AI
+
+Each model has its own backend pipeline so provider-specific options can be exposed without flattening everything into one generic request shape.
+
+## Data Layout
+
+By default, runtime and user configuration lives in:
+
+```text
+~/.dc-waifus
 ```
 
-You can also pin a specific GitHub Release:
+Important folders:
 
-```bash
-waifus init ~/Discord-Waifus --release app-v0.3.0
+```text
+~/.dc-waifus/config.toml
+~/.dc-waifus/user/providers.json
+~/.dc-waifus/user/discord-bots.json
+~/.dc-waifus/user/waifus/
+~/.dc-waifus/user/servers/
+~/.dc-waifus/user/memories.json
+~/.dc-waifus/app/logs/
 ```
 
-## Runtime Model
+Use `waifus clean` only when you intentionally want to delete saved user data.
 
-- committed defaults live in `defaults/`
-- local runtime state lives in `.waifus/`
+## Release Notes
 
-This CLI is for local-machine usage. The dashboard runs on `http://localhost:3000` and the backend API runs on `http://127.0.0.1:4000`.
+Version `1.0.0` is the first stable release for the local backend, web UI, Discord runtime, npm CLI, and prebuilt waifu configuration flow.

package/bin/waifus.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL, fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const compiled = path.join(root, "dist", "cli", "main.js");
+const source = path.join(root, "src", "cli", "main.ts");
+
+if (existsSync(compiled)) {
+  await import(pathToFileURL(compiled).href);
+} else if (existsSync(source)) {
+  const tsxBin = path.join(
+    root,
+    "node_modules",
+    ".bin",
+    process.platform === "win32" ? "tsx.cmd" : "tsx"
+  );
+
+  if (!existsSync(tsxBin)) {
+    console.error(
+      "waifus is not built yet and local tsx is missing. Run `npm install`, then `npm run build` or retry the command."
+    );
+    process.exit(1);
+  }
+
+  const result = spawnSync(tsxBin, [source, ...process.argv.slice(2)], {
+    cwd: root,
+    stdio: "inherit"
+  });
+  process.exit(result.status ?? 1);
+} else {
+  console.error("waifus CLI entrypoint is missing. Reinstall @starlight-ai/discord-waifus.");
+  process.exit(1);
+}

package/dist/api/errors.d.ts

@@ -0,0 +1,9 @@
+export declare class ApiError extends Error {
+    readonly statusCode: number;
+    readonly details?: unknown | undefined;
+    constructor(statusCode: number, message: string, details?: unknown | undefined);
+}
+export declare function badRequest(message: string, details?: unknown): ApiError;
+export declare function notFound(message: string): ApiError;
+export declare function conflict(message: string, details?: unknown): ApiError;
+export declare function preconditionRequired(message: string): ApiError;

package/dist/api/errors.js

@@ -0,0 +1,23 @@
+export class ApiError extends Error {
+    statusCode;
+    details;
+    constructor(statusCode, message, details) {
+        super(message);
+        this.statusCode = statusCode;
+        this.details = details;
+        this.name = "ApiError";
+    }
+}
+export function badRequest(message, details) {
+    return new ApiError(400, message, details);
+}
+export function notFound(message) {
+    return new ApiError(404, message);
+}
+export function conflict(message, details) {
+    return new ApiError(409, message, details);
+}
+export function preconditionRequired(message) {
+    return new ApiError(428, message);
+}
+//# sourceMappingURL=errors.js.map

package/dist/api/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/api/errors.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,QAAS,SAAQ,KAAK;IAEtB;IAEA;IAHX,YACW,UAAkB,EAC3B,OAAe,EACN,OAAiB;QAE1B,KAAK,CAAC,OAAO,CAAC,CAAC;QAJN,eAAU,GAAV,UAAU,CAAQ;QAElB,YAAO,GAAP,OAAO,CAAU;QAG1B,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;IACzB,CAAC;CACF;AAED,MAAM,UAAU,UAAU,CAAC,OAAe,EAAE,OAAiB;IAC3D,OAAO,IAAI,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,OAAe;IACtC,OAAO,IAAI,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,OAAe,EAAE,OAAiB;IACzD,OAAO,IAAI,QAAQ,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,OAAe;IAClD,OAAO,IAAI,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;AACpC,CAAC"}

package/dist/api/server.d.ts

@@ -0,0 +1,19 @@
+import { FastifyInstance } from "fastify";
+import { Logger } from "../backend/logger.js";
+import { RuntimeState } from "../backend/runtime.js";
+import { RuntimeOrchestrator } from "../orchestration/runtime.js";
+import { StorageService } from "../storage/storageService.js";
+export type ApiServerOptions = {
+    dataRoot: string;
+    storage?: StorageService;
+    runtime: RuntimeState;
+    runtimeOrchestrator?: RuntimeOrchestrator;
+    runtimeControl?: {
+        getOrchestrator: () => RuntimeOrchestrator | undefined;
+        pause: () => Promise<void>;
+        resume: () => Promise<void>;
+        reload: (reason: string) => Promise<void>;
+    };
+    logger?: Logger;
+};
+export declare function createApiServer(options: ApiServerOptions): Promise<FastifyInstance>;