@wolfstar/http-framework 3.3.0 → 3.4.0-next-20260904111115

package/README.md

@@ -21,6 +21,7 @@ A powerful HTTP framework for building your Discord bots, powered by [`node:http
 
 - Support for reloading and unloading commands
 - Built-in Hot Module Reloading for every store
+- Built-in logger, extendable by plugins
 - Support for attachment responses
 - Seamless integration with low-level libraries
 - Thin wrapper on top of raw data for maximum performance
@@ -311,6 +312,39 @@ await client.load();
 await client.listen({ port: 3000 });
 ```
 
+### Logger
+
+The framework ships a minimal logger, available as `container.logger` (and as `client.logger`) as soon as
+`@wolfstar/http-framework` is imported. It writes to the matching `console` method and filters entries by
+`LogLevel`, which defaults to `LogLevel.Info`:
+
+```typescript
+import { container, Client, LogLevel } from '@wolfstar/http-framework';
+
+const client = new Client({ logger: { level: LogLevel.Debug } });
+
+container.logger.info('Ready');
+container.logger.debug('Interaction received', interaction.id);
+```
+
+The built-in implementation is intentionally bare: it has no timestamps, colours, or transports. Those belong to a
+logger plugin, which replaces it by assigning an `ILogger` to `options.logger.instance` from a
+`preGenericsInitialization` hook:
+
+```typescript
+import { Plugin, preGenericsInitialization, type ClientOptions } from '@wolfstar/http-framework';
+
+export class LoggerPlugin extends Plugin {
+	public static [preGenericsInitialization](options: ClientOptions): void {
+		options.logger ??= {};
+		options.logger.instance = new MyLogger(options.logger);
+	}
+}
+```
+
+Because the plugin only has to satisfy the `ILogger` interface, the rest of the framework — including Hot Module
+Reloading and the command router — keeps logging through `container.logger` without any change.
+
 ### Client events
 
 The `Client` extends an event emitter typed by the `ClientEvents` interface. Every event name is also available as a
@@ -426,6 +460,87 @@ client.on(Events.HmrPieceReloaded, async (piece) => {
 > registered exactly once. HMR does not push the updated commands to Discord on its own, subscribe to the events above
 > if you want that behaviour.
 
+### Project configuration (`stars.config.*`)
+
+`@wolfstar/http-framework` owns the typed project configuration consumed by the [`stars` CLI](../cli) — the
+`defineConfig` helper and the config loader live here, not in the CLI, so any tool can resolve a project's
+configuration without pulling in `@wolfstar/cli`.
+
+```typescript
+// stars.config.ts
+import { defineConfig } from '@wolfstar/http-framework/config';
+
+export default defineConfig({
+	entry: 'src/main.ts',
+	build: { tool: 'tsdown' }
+});
+```
+
+`@wolfstar/http-framework/config` has no side effects — importing it (or a `stars.config.ts` that imports it) never
+starts the bot. `loadStarsConfig` discovers `stars.config.{ts,mts,cts,js,mjs,cjs}` from a directory, applies defaults,
+validates every option and resolves all paths to absolute ones.
+
+`dev.url`, the URL `stars dev` shows and health-checks the bot on, needs no configuration either: it is detected the
+way Vite's and Nuxt's dev servers are, from `HTTP_PORT` (env var, `.env.local`/`.env`, or `dev.env`) or `3000`, and
+`localhost` is swapped for `127.0.0.1` at runtime if that is what is actually reachable. Set `dev.url` explicitly only
+to override it, e.g. for a LAN address: `dev: { url: 'http://192.168.1.5:3000' }`.
+
+`dev` also carries the three options that round out the dev loop:
+
+```typescript
+export default defineConfig({
+	entry: 'src/main.ts',
+	build: { tool: 'tsdown' },
+	dev: {
+		// A type checker next to the bot, reported on the dev UI's `tsc` channel. Never blocks a build.
+		// `checker` is 'tsc' | 'golar' | 'tsz' | 'auto' (default: golar when installed, tsc otherwise).
+		typecheck: { checker: 'golar' },
+		// A cloudflared quick tunnel so Discord can reach the interactions endpoint, or an https URL you serve.
+		tunnel: true,
+		// Where the session's logs are mirrored, so a run can be read after the terminal UI is gone.
+		logFile: '.stars/dev.log'
+	}
+});
+```
+
+`tunnel.updateEndpoint` writes the public URL to the Discord application's `interactions_endpoint_url`; it is opt-in
+because it edits a live application, and needs `DISCORD_TOKEN` in the environment or the project's `.env`.
+
+### Experimental flags
+
+`experimental` is the same kind of block Nuxt's own `experimental` is: opt-in booleans, all `false` by default, each
+guarding work that is still landing.
+
+```typescript
+export default defineConfig({
+	entry: 'src/main.ts',
+	// `build.tool: 'vite'` is only accepted with `enableVite`, and `'auto'` only then detects a vite.config.*
+	build: { tool: 'vite' },
+	experimental: {
+		// Vite as the build tool and the HTTP server, in place of tsdown plus the framework's node:http listener.
+		enableVite: true,
+		// The project runs Vite itself: `stars dev` only watches the output and restarts the bot.
+		enableExternalVite: false,
+		// Build and serve through Nitro. Needs the framework's Fetch adapter, so `stars dev`/`stars build` still
+		// refuse it with an actionable error for now.
+		enableNitro: false
+	}
+});
+```
+
+The resolved configuration is also available programmatically:
+
+```typescript
+import { loadStarsConfig } from '@wolfstar/http-framework/config';
+
+const config = await loadStarsConfig({ cwd: process.cwd() });
+console.log(config.entry, config.build.output);
+```
+
+Invalid options raise a `ConfigError` with a stable `code`, the offending option `path`, the `file` it came from, and
+an actionable `hint`. See the [`@wolfstar/cli` README](../cli#configuration) for the full option reference and how the
+`stars` commands (`dev`, `build`, `info`, `codegen`, `prepare`, `commands`) use it.
+
 ### ApplicationCommandRegistry
 
 The `ApplicationCommandRegistry` is `@wolfstar/http-framework`'s centralized registry and uses [`@discordjs/rest`] to register them in Discord.