virello 0.0.0-stage → 0.1.0

package/BREAKING_CHANGES.md

@@ -0,0 +1,69 @@
+# Breaking changes
+
+## Rilo rename
+
+- Install `rilo` and update all imports and subpath imports from `kairojs` to
+  `rilo`. TypeScript declaration augmentation must target `rilo`.
+- Rename `KairoClient` and `KairoClientOptions` to `RiloClient` and
+  `RiloClientOptions`. The previous names are no longer exported.
+- Replace the `KAIRO_` prefix with `RILO_` in environment variables and GitHub
+  repository variables, including `RILO_RELEASES` and `RILO_TEST_REDIS_URL`.
+- Upgrade coordinators, hosts and children together: transport headers and the
+  reserved stats request now use `x-rilo-*` and `rilo:stats`.
+- Redis task keys now use `rilo:tasks:v1:`. Existing tasks in the previous
+  namespace are not read; drain or migrate them before switching. Branded
+  symbols and pagination component IDs also use the new name, so avoid mixing
+  framework versions in one application and recreate active pagination messages.
+
+## Stricter utility types
+
+- Loose value types now use `unknown`; narrow formatter values, translation
+  dictionaries, and other untyped data before accessing their properties.
+- `ok()` defaults its absent error type to `never`, `err()` defaults its absent
+  value type to `never`, and `none` carries `never`. Supply explicit Result
+  generics when a consumer needs a particular type for the absent branch.
+- Constructor utility types accept arbitrary signatures as constraints. Supply
+  the parameter tuple when invoking a value typed as `Ctor`, `AbstractCtor`,
+  `Constructor`, or `AbstractConstructor`.
+- `PaginatedFieldMessageEmbed.formatItems()` returns the same instance with the
+  transformed item type. Continue chaining from that return value.
+- Empty interfaces that only renamed another type are now aliases. Extend the
+  alias or augment its underlying interface when adding application fields.
+  `Tasks`, `ShardRequests`, and `DetailedDescriptionCommandObject` remain
+  augmentable interfaces.
+
+## Shard maintenance and coordinator reconciliation
+
+- Upgrade coordinator, hosts and children together. The internal protocol now
+  authenticates per-process leases and acknowledges assignment application.
+- Coordinator loss retains children and Discord sessions in `client.maintenance`,
+  with a default fifteen-minute unreconciled outage cutoff. `reconnect: false`
+  retains its explicit stop-on-loss behavior.
+- Fixed shard totals remain the default. `workers[].shards` are initial placement
+  preferences; leases decide ownership. Distinct authenticated supervisor
+  instances can connect together; duplicate sockets for one instance are refused.
+- Disconnected leases remain reserved during the coordinator lifetime until the
+  owner confirms exit/release. A new supervisor does not prove old children died.
+  Restarting the coordinator rebuilds slots without a global grace period, which
+  can allow overlapping old and replacement Discord sessions until recovery or
+  the outage cutoff. There is no zero-duplicate-processing guarantee.
+- Processes without capacity remain dormant, with no Discord session and
+  `client.sharding.id === null`. They poll every thirty seconds by default.
+  `login()` and transport-only `sharding.connect()` wait for the first assignment.
+- Changed totals close the old gateway before reconnecting, even for the same ID.
+  Assignment changes reset guild/channel/user caches and gateway resume data,
+  preserving the client, modules and application listeners. Extension login hooks
+  run once; Discord ready events may repeat.
+- `ShardProcessStatus.shard` is nullable. `slot` identifies the local process
+  position; `maintenance` and `dormant` are new states. Slots are not Discord IDs.
+- Coordinator calls fail immediately by default. Use
+  `{ waitForCoordinator: true, timeoutMs }` for a bounded wait. Broadcasts share
+  one deadline across waiting and all targets. Dispatched calls are never replayed.
+- Configure `assignmentPollIntervalMs`, `maxDisconnectedLifetimeMs`, and optionally
+  a minimum standby `processCount` on `ShardManager`. Existing crash/backoff and
+  opt-in automatic scaling policies remain. Reservations belonging to disconnected
+  instances block scaling until reconciled or released.
+
+Disk-backed ownership remains removed. No state migration is needed. See
+[shard recovery](docs/sharding-recovery.md) for the full contract and supervision
+boundary.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lilsnibbi
+
+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

@@ -1,3 +1,162 @@
-# Temporary Holding Version
+# Rilo
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A modular Discord framework for Bun, written in TypeScript and built on discord.js. Organise your bot into commands, listeners and services, with explicit module loading and shared lifecycle management.
+
+## Features
+
+- Slash commands, context menus, message commands and interaction handlers.
+- Argument parsing, preconditions, permissions and cooldowns.
+- Localisation for replies and application commands through i18next.
+- Scheduled tasks with in-memory or Redis-backed storage.
+- Shard coordination, host supervision, typed messaging and opt-in [automatic scaling](docs/sharding-scaling.md).
+- [Shard maintenance and recovery](docs/sharding-recovery.md), with per-process leases and bounded coordinator outages.
+- [Live shard statistics](docs/sharding-stats.md) through `container.sharding.stats()`, with fresh samples and explicit failures.
+- Pagination, validation, collections, time helpers and other utilities.
+
+## Original engine milestone
+
+The experimental [native Discord engine](docs/engine.md) is available through `rilo/engine`. It owns gateway sessions, REST and cache while the existing framework keeps its current runtime. Run `bun examples/engine/offline.ts` for a local connect/reply/resume demonstration with no Discord credentials.
+
+## Getting started
+
+Use **Bun 1.4.3 or newer**. Rilo runs TypeScript directly; no compilation step is required.
+
+From this repository, install dependencies:
+
+```sh
+bun install --frozen-lockfile
+```
+
+The [example bot](examples/README.md) includes a coordinator, shard host, three slash commands and an [env template](examples/.env.example).
+
+Copy `examples/.env.example` to `examples/.env`, fill in your bot token and a generated host secret, then start these in separate terminals:
+
+```sh
+bun --env-file=examples/.env examples/coordinator.ts
+bun --env-file=examples/.env examples/host.ts
+```
+
+The host starts two bot processes by default. Try `/ping`, `/stats` and `/shard`. The example guide covers server setup, secrets and running hosts on separate machines.
+
+### Create your own bot
+
+In a separate Bun project, install your local Rilo checkout and discord.js. Replace the path with your checkout location:
+
+```sh
+bun add /absolute/path/to/Rilo discord.js
+```
+
+Use this layout:
+
+```text
+my-bot/
+├── commands/
+│   └── ping.ts
+├── .env
+└── index.ts
+```
+
+Create `index.ts`:
+
+```ts
+import { GatewayIntentBits } from "discord.js";
+import { RiloClient } from "rilo";
+
+const token = Bun.env.DISCORD_TOKEN;
+if (!token) throw new Error("Set DISCORD_TOKEN in your .env file.");
+
+const client = new RiloClient({
+	intents: [GatewayIntentBits.Guilds],
+	root: import.meta.dir,
+	modules: { commands: "commands/**/*.ts" },
+});
+
+process.once("SIGINT", () => {
+	void client.destroy();
+});
+
+await client.login(token);
+```
+
+Create `commands/ping.ts`:
+
+```ts
+import { Command } from "rilo";
+
+export default class PingCommand extends Command {
+	static override options: Command.Options = {
+		description: "Check whether the bot is awake.",
+	};
+
+	override registerApplicationCommands(registry: Command.Registry): void {
+		registry.registerChatInputCommand((builder) =>
+			builder.setName(this.name).setDescription(this.description),
+		);
+	}
+
+	override async chatInputRun(
+		interaction: Command.ChatInputCommandInteraction,
+	): Promise<void> {
+		await interaction.reply("Pong!");
+	}
+}
+```
+
+Set `DISCORD_TOKEN` in your bot's `.env`, add `.env` to its `.gitignore`, then run:
+
+```sh
+bun index.ts
+```
+
+The filename supplies the command name. Module paths are explicit glob patterns relative to `root`; folders are not scanned automatically. Restart the process after changing code, module patterns or translations.
+
+## Imports
+
+Import from the package root or a focused entrypoint:
+
+```ts
+import { RiloClient } from "rilo/client";
+import { Command, Precondition } from "rilo/commands";
+import { Task } from "rilo/scheduling";
+import { Result } from "rilo/utilities";
+```
+
+Other entrypoints include `modules`, `events`, `extensions`, `localisation`, `services`, `sharding`, `discord`, `time` and `validation`. Root and category imports share the same classes and state. Keep TypeScript declaration augmentation on `rilo`.
+
+## Examples
+
+| Example                              | Demonstrates                                                            |
+| ------------------------------------ | ----------------------------------------------------------------------- |
+| [Example guide](examples/README.md)  | Setup, environment settings, shard roles and running across machines    |
+| [Bot](examples/bot.ts)               | Shared entrypoint for each managed shard                                |
+| [Commands](examples/commands/)       | Local replies, broadcasts and single-shard requests                     |
+| [Offline check](examples/offline.ts) | The same bot modules in two real child processes, without Discord login |
+
+Try `bun examples/offline.ts` without a Discord token.
+
+## Development
+
+Use **Bun canary**, the project's standard toolchain. Install it with `bun upgrade --canary`; CI follows the canary channel through `packageManager` in `package.json`.
+
+| Command           | Purpose                                 |
+| ----------------- | --------------------------------------- |
+| `bun test`        | Run Bun tests                           |
+| `bun check`       | Check TypeScript without emitting files |
+| `bun lint`        | Run Bun's built-in lint rules           |
+| `bun fmt --check` | Check formatting without writing files  |
+| `bun fmt`         | Apply formatting                        |
+
+Redis integration tests require `RILO_TEST_REDIS_URL` pointing to a disposable Redis instance; otherwise those tests are skipped locally.
+
+Run `bun scripts/ci.ts` with that loopback Redis URL for complete validation: zero skipped tests, native Bun type checking, linting, formatting and both offline examples. On the Ubuntu x64 CI runner, `bash scripts/checkActions.sh` also checks the workflow with checksum-pinned actionlint.
+
+See [migration notes](BREAKING_CHANGES.md) when moving from an earlier Rilo API.
+
+See [console logging](docs/console-logging.md) for readable text/JSON output,
+redaction, custom logger compatibility and the offline `bun scripts/logging-demo.ts` preview.
+
+Source lives in `src/`, tests in `tests/` and runnable examples in `examples/`. See [Repository Guidelines](AGENTS.md) for contribution conventions.
+
+## Licence
+
+The package declares `MIT AND Apache-2.0`. See the root [MIT licence](LICENSE), the [sharding Apache-2.0 licence](src/sharding/LICENSE), the shipped [source attribution](docs/source-retention.md) and retained notices alongside individual modules.

package/docs/console-logging.md

@@ -0,0 +1,257 @@
+# Console logging
+
+Rilo uses actual `@lilsnibbi/logger` instances. The library draws the
+timestamps, source names, severity markers, bars, badges, boxes and error trees.
+Rilo prepares safe message content and chooses native per-call display
+options. It adds no console interception, logging service, dependency, buffer
+or background timer.
+
+At normal width, a gateway login reads as three distinct records:
+
+```text
+[Thu 16:45:45.709] ▌ → coordinator › Login queued · host=local shard=0 queued=1
+[Thu 16:45:45.710] ▌ → coordinator › Login permitted · host=local shard=0 2.57s remaining=991
+[Thu 16:45:45.710] ▌ ✓ coordinator › Login confirmed · host=local shard=0
+```
+
+Routine records no longer repeat a full date, component/event row, field grid,
+trace heading and UUID block. Events are not buffered or merged: queueing,
+granting and confirmation remain separate. Request dispatch and outcomes also
+remain separate and keep their correlations in detailed text and JSON.
+
+## Native display selection
+
+| Output                         | Automatic presentation                                                                    |
+| ------------------------------ | ----------------------------------------------------------------------------------------- |
+| Routine terminal activity      | Native `bar`; `→` progress, `✓` successful milestones, `↻` assignment/recovery, `·` debug |
+| Warnings                       | Native `badge` with `ALERT` severity                                                      |
+| Terminal errors                | Native `box` containing the operation and the library's bounded error/cause tree          |
+| Pipes and ordinary Docker logs | Plain native `badge` output, without ANSI or decorative blank lines                       |
+| Very narrow displays           | Native `box` when a normal prefix would crowd out the message                             |
+| JSON                           | One canonical object per line, without native text decoration                             |
+
+The dependency's native severity names are `DEBUG`, `NOTIF` (info), `ALERT`
+(warn) and `ERROR`. Human timestamps use the library's local-clock format;
+JSON timestamps remain full ISO UTC timestamps. Human framework records use
+concise native source names such as `coordinator`, `host`, `commands` and `jobs`.
+The full application/component identity stays in detailed text and JSON.
+
+Debug/info go to stdout; warnings/errors go to stderr. Native frames group one
+failure and its causes together. Routine records have no blank separator.
+Continuations wrap within the selected width. Escaped newlines in supplied
+messages remain literal `\n` and cannot forge additional records.
+
+## Configuration
+
+| Variable          | Values                                                          | Default                                         |
+| ----------------- | --------------------------------------------------------------- | ----------------------------------------------- |
+| `RILO_LOG_LEVEL`  | `debug`, `info`, `warn`, `error`; `notif`/`alert` also accepted | `info`                                          |
+| `RILO_LOG_FORMAT` | `text`, `json`                                                  | `text`                                          |
+| `RILO_LOG_DETAIL` | `compact`, `full`                                               | `compact`; `DEBUG` defaults to `full`           |
+| `RILO_LOG_LAYOUT` | `auto`, `badge`, `bar`, `box`                                   | `auto`                                          |
+| `RILO_LOG_STACKS` | `off`, `short`, `full`                                          | `short`                                         |
+| `RILO_LOG_WIDTH`  | Integer columns, `32`–`200`                                     | Terminal width capped at `120`; pipes use `100` |
+| `NO_COLOR`        | Any defined value disables color                                | Unset                                           |
+| `FORCE_COLOR`     | `0` disables; a nonempty value enables when permitted           | Unset                                           |
+| `TERM`            | `dumb` disables color                                           | Unset                                           |
+
+Invalid environment values fall back to defaults. Explicit `loggerOptions.level`,
+`loggerOptions.layout` and `logging.format/detail/stacks/width` take precedence.
+A native `box.width` is also supported. `COLUMNS` supplies a width when the stream
+has no terminal column count. Destination width and color switches are checked
+for framework events as they are emitted. `NO_COLOR`, `TERM=dumb`,
+`FORCE_COLOR=0` and `colors: false` take precedence over enabling color. JSON is
+always color free.
+
+```ts
+import { RiloClient, createConsoleLogger, logEvent } from "rilo/client";
+
+const client = new RiloClient({
+	intents: [],
+	loggerOptions: { layout: "bar", colors: "auto" },
+	logging: { detail: "compact", stacks: "short", width: 100 },
+});
+
+const logger = createConsoleLogger(
+	"MyBot",
+	{
+		level: "NOTIF",
+		layout: "bar",
+		symbols: { NOTIF: "✓", ALERT: "!" },
+		theme: { name: { color: "cyan" }, errorName: { color: "red", bold: true } },
+	},
+	{ detail: "compact" },
+);
+
+logEvent(logger, "notif", {
+	component: "jobs",
+	event: "batch_finished",
+	message: "Queued notifications have been processed.",
+	context: { processed: 12, failed: 0 },
+});
+await client.destroy();
+await logger.close();
+```
+
+`logEvent(logger, level, entry)` accepts `debug`, `notif`, `alert` or `error`.
+A `ConsoleLogEntry` contains `component`, `event`, `message`, optional `context`
+and the original thrown `error`. Put the operation and next step in the message.
+Unknown application events keep that message; known framework milestones have
+short display wording in compact mode. Full mode restores the original wording.
+
+## Detailed records and collection
+
+Set `RILO_LOG_DETAIL=full` to inspect the original event message, full component,
+every retained safe context field and complete request/connection/generation
+identifiers. `RILO_LOG_LEVEL=debug` additionally enables frame and module
+metadata and defaults to full detail unless compact detail was explicitly chosen.
+No wire bodies are included. Compact request/warning records may show an
+eight-character `ref`; use the full ID from detailed text or JSON for tracing.
+
+```powershell
+$env:RILO_LOG_LEVEL = 'debug'
+$env:RILO_LOG_DETAIL = 'full'
+$env:RILO_LOG_FORMAT = 'json'
+bun --env-file=examples/.env examples/coordinator.ts
+```
+
+JSON keeps the established schema: `timestamp`, `level`, `component`, `event`,
+`message`, and optional `context`/`error`. Compact display choices never remove
+fields from JSON. Native layouts, themes and text width do not decorate or wrap it.
+A broadcast has one request per destination shard. Use `requestId` to pair
+dispatch/outcome and `routeId` to follow a destination invocation; connection IDs
+change after reconnects.
+
+## Native options, files and compatibility
+
+`Logger`, `LoggerOptions` and `LogLevel` still come directly from the dependency.
+`LogLayout`, `LogCallOptions`, `LogBoxOptions`, `LogFileOptions`, `LogTheme` and
+`LogStyle` are also available from `rilo` / `rilo/client`.
+
+Native `layout`, `box` corners, `symbols`, `theme`, `timeformat`,
+`includeTimestamps`, `filter`, `transport` and file options work with built-in safe
+records. Per-call overrides do not mutate the shared logger or caller settings.
+Theme changes through `setTheme()` remain effective, including error/stack tokens.
+The native `name`, `level`, `silent`, `child()`, raw rendering, `divider()`,
+`time()`, `timeEnd()`, `flush()` and `close()` APIs remain available. The framework
+does not add dividers to machine-readable output.
+
+```ts
+const logger = createConsoleLogger(
+	"MyBot",
+	{
+		level: "NOTIF",
+		file: {
+			directory: "logs",
+			filename: "bot",
+			level: "DEBUG",
+			rotate: "daily",
+			maxSize: 5 * 1024 * 1024,
+			maxFiles: 7,
+			json: true,
+		},
+	},
+	{ detail: "compact" },
+);
+```
+
+Text file sinks retain full safe detail even when console presentation is compact.
+`file.level` can retain debug records filtered from the console. `file.json` keeps
+the dependency's native envelope (`time`, `level`, `name`, `message`); parse its
+`message` string as JSON for the canonical Rilo record. The native transport
+receives a plain rendered line and a record whose `value` is the full sanitized
+Rilo record. Filters still run before formatting. File ownership, rotation,
+flushing and closing stay with the dependency.
+
+An explicit `format` / `serialize` hook or native `inspectDepth` / `relativePaths`
+serialization control selects the dependency's original formatting contract and
+owns redaction/presentation. Passing `new Logger(...)`
+directly also retains native behavior. The exported helpers are available on
+`rilo/engine` without importing Discord.js or changing the engine runtime.
+
+Supplying `logger` to a client, coordinator or host preserves that exact instance,
+its settings, method binding and ownership; Rilo never configures or closes it.
+Custom loggers still need only `debug`, `notif`, `alert` and `error`. They receive
+one contextual string for notices or one contextual `Error` whose `cause` is the
+original thrown value. User error callbacks, events and their arguments are
+unchanged. A synchronous sink failure attempts one safe fallback record and
+cannot interrupt startup, retries or cleanup.
+
+## Operational coverage
+
+- Readiness and completed registration stay visible. Identical command
+  definitions, loading progress and per-module traces remain debug. Changed
+  commands and registration failures retain their existing policy and severity.
+- Coordinator listening, connections, shard registration/offline changes, login
+  queue/grant/confirmation, request dispatch/outcomes and graceful host shutdown
+  keep their distinct events. Authentication, capacity, cancellation and timeout
+  failures retain their reasons and codes.
+- `connection_waiting` describes cancellable waits for coordinator availability
+  or an active duplicate host. `identify_startup_wait` reports the startup login
+  cooldown; `host_drained` confirms that a host stopped its shards.
+- Gateway/REST, extensions, loaders, jobs/storage, localisation and pagination
+  use the same built-in presentation. Routine job ticks and job data remain
+  omitted. Error records identify the failing operation and actionable remedy.
+- Raw close reasons, tokens, headers, payloads, results and provider error
+  messages are not printed. Existing trace controls and custom callbacks remain
+  effective.
+
+Logging does not change engine, permissions, rate limits, retries, registration,
+sharding, scheduling or shutdown behavior. Child stdout/stderr remain inherited.
+See [sharding restarts](sharding-recovery.md) for connection-scoped ownership,
+in-memory identify scheduling and process-supervision limits.
+
+## Redaction and bounds
+
+Recognized error type, code/status, actionable hints, causes and aggregate counts
+remain available. Provider messages, arbitrary error properties, request/response
+bodies, stack header text and function labels are omitted. The library's native
+error formatter receives a sanitized bounded error tree, not the provider object.
+
+`short` keeps up to three source locations outside dependencies; `full` keeps up
+to ten including dependencies; `off` omits locations. Compact warning records
+omit routine stack locations; error records retain them. Full detail includes
+the locations selected by the stack setting. Causes are bounded to two levels;
+aggregates retain counts and at most three children at each level.
+
+Private metadata is recursively redacted. Numeric token counts remain useful.
+Configured credential values and encoded variants are scrubbed; values shorter
+than six characters are ignored to avoid erasing ordinary words. HTTP/WS URLs
+retain only their origin; database URLs, webhook/interaction secrets, queries,
+authorization values, email addresses and user content are removed. Controls and
+terminal escapes are removed before native theme styling.
+
+Messages and strings are capped at 320 characters. Context shares a 1,536-character
+budget, 80 nodes, 24 fields per object, three levels and eight array entries.
+Correlation fields are prioritized before unrelated metadata. JSON and built-in
+human records stay within 8 KiB; extreme detail is marked as truncated. Native
+wrapping counts Unicode display cells and preserves theme escape sequences.
+
+## Preview and verification
+
+The demo uses the same built-in native logger as actual framework events:
+
+```sh
+bun scripts/logging-demo.ts --width=100
+bun scripts/logging-demo.ts --width=64 --layout=bar
+bun scripts/logging-demo.ts --layout=box --color
+bun scripts/logging-demo.ts --full
+bun scripts/logging-demo.ts --json
+```
+
+For comparison, the former human login output spent roughly eight or more lines
+per stage on a message, date/component/event, counts and full UUIDs. The three
+native compact records at the top retain the distinct stages in three lines at
+100 columns. Detailed text and JSON keep the original messages and correlations.
+The demo is synthetic and never constructs a client or contacts Discord.
+
+```sh
+bun test tests/core/logging.test.ts tests/core/loggingLayout.test.ts
+bun test tests/sharding/activity.test.ts tests/sharding/consoleLayout.test.ts
+```
+
+Tests cover native layouts/options/themes, compact versus detailed output,
+file/transport semantics, redaction, error trees, Unicode/width/byte bounds,
+colors, pipes and frozen custom loggers. Actual coordinator/host entrypoints
+run against disposable loopback state at 64 and 100 columns; their gateway
+metadata is supplied by a test-only preload. No live Discord failure is provoked.