Manifest V1 - Thinking long term

[Pkmmte]

Manifest v1

Historically, Robo has keep a .json file in .robo for configuration. We call this the Robo Manifest and is meant for internal tracking such as config, metadata, and handlers. By pre-computing certain data, we improve startup time and now have a standard way to debug and define Robo projects.

Our initial scope of Robo.js was to provide a simple, yet powerful, way to build Discord bots. We've since expanded to include a wide range of features and plugins and are limited in granularity by past assumptions.

Granularity

The fact that we have a single file for configuration, metadata, and handlers is a problem. It's hard to debug, hard to maintain, and hard to extend. We need to split this file into multiple files for better organization and faster reads.

I propose each there be a manifest directory in .robo rather than a single manifest.json file. This directory would contain the following files:

• config.json - Serialized configuration map for Robo.js, plugins, and anything else like Vite.
• hooks - Registered event handlers folder, each file being a namespace with dot notation for nested namespaces.
  • @.json - Contain metadata such as which plugins handle which hooks.
    • commands.json - All registered commands, plugin reference, and their handlers paths.
    • commands.*.json - Subcommands for a command.
    • commands.*.*.json - Subcommand groups for a subcommand.
    • context.message.json - Context menu for messages.
    • context.user.json - Context menu for users.
  • events.json - All registered events, plugin reference, and their handlers paths.
  • events.**.json - Allows deep folder support for event handlers.
  • robo.json - Core hooks like start and stop.
  • robo.build.json - Build hooks.
• metadata - Allows plugins to define their own mini manifest.
  • @robojs/ai - Assistant data to precompute instead of runtime. (like bot slash commands)
  • @robojs/discordjs - Maintain things like permissions and intents.
• plugins.json - General plugin data such as name, version, path, and registered hooks.
• robo.json - Core metadata about the project. (language, version, mode, etc.)
• seeds - Folder containing seed file matadata arrays.
• ../../README.md - Basically saying not to touch these files.

Hooks

Contents in hook files are strictly always arrays for uniformity. Hooks all have these properties:

• id - Unique identifier for the hook.
• plugin - Plugin reference for the hook. (package name)
• handler - Path to the handler file.

Hooks are allowed to include arbitrary data for either pre-computation or runtime use. This data is not used by Robo.js itself, but by plugins and handlers.

• description - Human-readable description of the hook.
• options - Options for the hook. (e.g. once, parallel, serial)
• ... rest of command data

Config and Plugins

config.json and plugins.json use mapped data for easy access, instead of arrays. Think of it like Record<string, unknown>.

Modes

Subfolders by default. e.g. .robo/manifest/production and .robo/manifest/development.

Portal

Lazy load by default for instant startup. Only load what's needed. Include ability to "reload" hooks for proper HMR.

API

import { Manifest } from 'robo.js'

Manifest.use()
Manifest.config()
Manifest.metadata()
Manifest.hooks()
Manifest.plugins()

// TODO:

• Go over all planned use cases and ensure they're covered.
• Define the structure of each file, especially robo hooks.