build docs

feat: dedicated cli information

docs/cli/README.md

@@ -0,0 +1,30 @@
+# CLI
+
+Publish commands to the API, install plugins, and use other tools provided by our cli.
+
+The CLI is your pocketknife for discord bot development. It'll have all features necessary for developing and shipping to production.
+```
+Usage: sern [options] [command]
+
+
+  ___  ___ _ __ _ __
+ / __|/ _ \ '__| '_ \
+ \__ \  __/ |  | | | |
+ |___/\___|_|  |_| |_|
+
+ Welcome!
+ If you're new to sern, run npm create @sern/bot for an interactive setup to your new bot project!
+
+ If you have any ideas, suggestions, bug reports, kindly join our support server: https://sern.dev/discord
+
+Options:
+  -v, --version      output the version number
+  -h, --help         display help for command
+
+Commands:
+  init [options]     Quickest way to scaffold a new project [DEPRECATED]
+  plugins [options]  Install plugins from https://github.com/sern-handler/awesome-plugins
+  extra              Easy way to add extra things in your sern project
+  commands           Defacto way to manage your slash commands
+  help [command]     display help for command
+```

docs/cli/build.md

@@ -0,0 +1,211 @@
+```sh
+Usage: sern build [options]
+
+Build your bot
+
+Options:
+  -f --format [fmt]        The module system of your application. `cjs` or `esm` (default: "esm")
+  -m --mode [mode]         the mode for sern to build in. `production` or `development` (default: "development")
+  -W --suppress-warnings   suppress experimental warning
+  -p --project [filePath]  build with this sern.build file
+  -h, --help               display help for command
+```
+
+## Guiding Principles
+
+When designing the `sern build` command, our aim was to make building bot applications as simple as possible for the majority of developers. The setup process has been streamlined, and most of the configuration details have been handled for you. Here are some key points to keep in mind:
+
+1. **Minimal Configuration**: In the vast majority (99%) of use cases, developers do not need to configure the bot application building process. We believe that simplicity is key, so only a few decisions need to be made on the developer's end.
+
+2. **Optimal Defaults**: We've chosen sensible defaults. This means you can get started without getting bogged down by complex, unneeded configurations.
+
+3. **Finetuned for production bots**: Our CLI leverages an opinionated build solution powered by esbuild. This ensures that bots are built without issues and can be shipped easily.
+
+## Experimental Features
+
+Both the `sern build` and `sern publish` commands are marked as experimental. While they might not be completely stable, they are designed to work for the majority of users. We appreciate any feedback in helping us make these features even better.
+
+## Features
+
+The `sern build` command comes equipped with a range of features designed to enhance your development process. Here's a glimpse of what it offers:
+
+- **esbuild Integration**: our CLI takes inspiration from the efficiency of SvelteKit, ensuring your bot application is built effectively and with type safety. Leverage the [esbuild plugin ecosystem](https://github.com/esbuild/community-plugins).
+
+- **Zero Configuration**: Building your bot application without additional configuration. The CLI handles most of the setup for you.
+
+- **Experimental Image Support**: We've introduced experimental support for top-level imports of PNG and JPG files, making it easier to include images in your bot application.
+
+- **Compile Time Constants**: Customize your build with constants such as \_\_DEV\_\_, \_\_PROD\_\_, allowing you to tailor your application to different production stages.
+
+- **Development and Production Modes**: The CLI supports both development and production modes, enabling you to tailor your bot application for different stages of development.
+
+
+- **Type-safe `process.env`**: The CLI generates a type-safe `process.env`, reducing potential errors.
+## Implicits 
+- command line arguments take precendence over sern.build configuration file
+- default build format is ESM
+- defineVersion = true
+- __DEV__ AND __PROD__ constants are configured. 
+- only a [few tsconfig options](https://esbuild.github.io/content-types/#tsconfig-json) are respected.
+### sern.build.js
+- For any extra configuration you may need
+- the cli was intentionally made to be installed globally, and we can't provide typings at a project level. If you need typings, here they are:
+```ts
+type BuildOptions = {
+    /**
+      * Define __VERSION__
+      * This option is a quick switch to defining the __VERSION__ constant which will be a string of the version provided in 
+      * cwd's package.json
+      */
+    defineVersion?: boolean 
+    /**
+      * default = esm
+      */
+    format?: 'cjs' | 'esm'
+    /** 
+      * extra esbuild plugins to build with sern.
+      */
+    esbuildPlugins?: esbuild.Plugin[]
+    /**
+     * https://esbuild.github.io/api/#drop-labels
+     **/
+    dropLabels?: string[]
+    /**
+     * https://esbuild.github.io/api/#define
+     **/
+    define?: Record<string, string>
+    /** 
+    * Path to tsconfig
+    **/
+    tsconfig?: string;
+    /**
+      * default = 'development'
+      */
+    mode: 'production' | 'development',
+    /**
+      * will search for env file. If none exists, 
+      * default to .env.
+      */
+    env?: string
+}
+```
+
+## Usage 
+```
+sern build
+```
+(that was easy)
+
+## Adapting older projects 
+- Change your tsconfig.json to extend our generated one. 
+
+```json
+{ 
+    // highlight-start
+    "extends": "./.sern/tsconfig.json",
+    // highlight-end
+    "compilerOptions" : {
+        //all of your old fields  
+    }
+}
+```
+## In depth
+We use the `define` and `drop labels` api in C style macros to have easy development stage differences. 
+[Here](https://esbuild.github.io/api/#drop-labels) is the esbuild full API documentation
+### drop labels
+
+```sh 
+# mode is set to production
+sern build
+```
+
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<Tabs>
+<TabItem value="input" label="Input">
+
+```ts
+__DEV__: console.log('This is for production only')
+__PROD__: console.log('This is for either mode')
+```
+
+</TabItem>
+
+<TabItem value="sh" label="Running build for production">
+
+```sh 
+# mode is set to production
+sern build
+```
+
+</TabItem>
+
+
+<TabItem value="output" label="Output">
+
+```ts 
+__PROD__ console.log('This is for either mode')
+```
+
+</TabItem>
+
+</Tabs>
+
+### constants 
+sern builds with three default constants. \_\_DEV\_\_, \_\_PROD\_\_, \_\_VERSION\_\_. 
+
+<Tabs>
+
+<TabItem value="input" label="Preprocess">
+
+```sh
+sern build
+```
+
+</TabItem>
+
+<TabItem value="sh" label="Constants available and typesafe!">
+
+```ts 
+if(__PROD__) {
+    console.log('Bot version: ' + __VERSION__)
+}
+```
+
+</TabItem>
+
+</Tabs>
+
+Full esbuild documentation [here](https://esbuild.github.io/api/#define)
+Add more to the `define` field in build options (only availible with a `sern.build` file at the moment.
+
+### process.env
+We generate your process.env with `dotenv` and generate typings for process.env. Less hassle!
+
+<Tabs>
+
+<TabItem value="input" label=".env">
+
+```sh
+DISCORD_TOKEN=<your token>
+```
+```ts 
+process.env.DISCORD_TOKEN // string | undefined (not typesafe :()
+```
+
+</TabItem>
+
+<TabItem value="sh" label="sern build">
+
+```sh 
+sern build
+```
+```ts 
+process.env.DISCORD_TOKEN // string  (typesafe :))
+```
+
+</TabItem>
+
+</Tabs>

docs/cli/extra.md

@@ -0,0 +1,11 @@
+
+```sh
+Usage: sern extra [options]
+
+Easy way to add extra things in your sern project
+
+Options:
+  -h, --help  display help for command
+```
+
+This command is pretty straightfoward. Install utilities into your application. Assumes you have a sern.config.json.

docs/cli/publish.md

@@ -0,0 +1,91 @@
+```sh
+Usage: sern commands publish [options] [path]
+
+New way to manage your slash commands
+
+Arguments:
+  path                          path with respect to current working directory that will locate all published files
+
+Options:
+  -i, --import [scriptPath...]  Prerequire a script to load into publisher
+  -t, --token [token]
+  --appId [applicationId]
+  -h, --help                    display help for command
+```
+## Implicits
+- Automatically reads a .env in the working directory. For seamless integration, your .env file should look like this:
+```txt title=".env" 
+DISCORD_TOKEN=<YOUR_TOKEN>
+APPLICATION_ID=<YOUR_APPLICATION_ID>
+MODE=<DEV|PROD>
+```
+- Calls the discord API with the [PUT route](https://discord.com/developers/docs/interactions/application-commands#bulk-overwrite-global-application-commands). Wherever your commands directory is located, publish will override the existing application commands at Discord. Existing commands do not count towards the command limit creation daily. 
+
+You may pass these in as command line arguments as well. **CLI arguments take precedence.**
+If you do not know how to obtain either of these credentials, [click here](https://github.com/reactiflux/discord-irc/wiki/Creating-a-discord-bot-&-getting-a-token)
+
+## Usage 
+
+![usage](../../static/img/Code_-_Insiders_2kTVzm0uIQ.gif)
+
+
+## Features
+- Automatically syncs api with your command base
+- generates JSON file of output (**.sern/command-data-remote.json**)
+- supports publishing direct esm typescript files
+- commonjs users need to compile first and then run sern publish on the dist/ output
+- prerequire scripts.
+- supports a configuration that is the same as the original publish plugin.
+
+
+Each command file can have an extra config that follows this typescript interface:
+PermissionResolvable is a discord.js type, but it will accept anything that the discord API accepts
+
+```ts 
+interface ValidPublishOptions {
+	guildIds: string[];
+	dmPermission: boolean;
+	defaultMemberPermissions: PermissionResolvable;
+}
+
+```
+## Prerequiring 
+Is there a [service](../guide/walkthrough/services) that is required at the top level of a command?
+- Create an ES6 script anywhere: 
+
+```ts title="scripts/prerequire.mjs"
+import { makeDependencies, single } from '@sern/handler'
+import { Client } from 'discord.js'
+
+await makeDependencies({
+    root => root.add({ '@sern/client': single(() => new Client(...options) }))    
+}) 
+
+await Service('@sern/client').login()
+```
+This will create a container for publishing. (as of 0.6.0, client is required or this will crash)
+
+### Example: command published in guild
+
+#### Script ran:
+```
+sern commands publish -i ./scripts/prerequire.mjs
+```
+```ts title=src/commands/ping.ts
+import { commandModule, Service, CommandType } from '@sern/handler'
+
+const client = Service('@sern/client');
+
+export const config = { 
+    guildIds: ["889026545715400705"]
+}
+
+export default commandModule( {
+    type: CommandType.Slash
+    description: `${client.user.username}'s ping`,
+    execute: (ctx) => { 
+        ctx.reply('pong')
+    }
+})
+
+```

docs/guide/walkthrough/cli.md

@@ -20,6 +20,7 @@ sern plugins
 Make sure to have a correct [sern.config.json](./good-to-know.md#sernconfigjson)
 :::
 
+
 This will display a menu selection of all installable plugins. <br />
 
 **Note**: You must have a [sern.config.json](good-to-know.md) to use this command.
@@ -30,3 +31,4 @@ If you want to view plugins, visit the repository linked above.
 sern extra
 ```
 
+We have a more in depth [guide](../../cli/README.md) of the CLI

docs/guide/walkthrough/services.md

@@ -2,11 +2,12 @@
 sidebar_position: 6
 ---
 
+# Services
+
 :::tip
 This is version 3 api only!!
 :::
 
-# Services
 
 :::tip
 TLDR: The direct upgrade to useContainer. if you set up a bot with create-bot, check dependencies.d.ts. 
@@ -46,16 +47,110 @@ export default commandModule({
     }
    // 
 })
-
 ```
-## Safety 
+
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+
+## Safety
+- Services cannot be called in other services while makeDependencies is forming.
+
+<Tabs>
+
+<TabItem value="good" label="A good example">
+
+Lets pass a logger into our database.
+```ts title="index.ts" showLineNumbers
+await makeDependencies({ 
+    build: root => root
+        //Overriding the default logger provided.
+        .upsert({ '@sern/logger': single(() => new Logger()) })
+
+        // Wiring our logger into the database.
+        .add(ctx =>  {
+            return { database: single(() => new Database(ctx['sern/logger']))) }
+        })
+})
+```
+</TabItem>
+
+<TabItem value="bad" label="Don't do this">
+
+```ts title="index.ts" showLineNumbers
+await makeDependencies({ 
+    build: root => root
+        //Overriding the default logger provided.
+        .upsert({ '@sern/logger': single(() => new Logger()) })
+
+        // Wiring our logger into the database.
+        // We wire our database incorrectly. Logger should be passed INTO the constructor
+        .add({ database: single(() => new Database()) })
+})
+```
+
+```ts title="index.ts" showLineNumbers
+import { Service, makeDependencies } from '@sern/handler';
+
+//Calling Service prematurely!
+const logger = Service('@sern/logger');
+
+class Database {
+    
+    constructor() {
+        this.logger = logger
+    }
+}
+```
+This is a code smell anyway. It breaks encapsulation and defeats the purpose of wiring dependencies
+</TabItem>
+</Tabs>
+
 - Services can only be used after sern has made dependencies. 
     - Calling a service before will crash your application. 
-- Services can be safely used outside of commandModules.
+- Services can be safely used outside of commandModules. 
     - Be careful to not cause too many side effects.
 
 
-## Related api 
+
+- You will need to wire dependencies together.
+
+<Tabs>
+<TabItem value="good" label="A good example">
+
+```ts title="index.ts" showLineNumbers
+await makeDependencies(...pass your options here)
+```
+```ts title="commands/ping.ts" showLineNumbers
+// This is guaranteed to be defined if configured correctly
+import { Service } from '@sern/handler';
+const client = Service('@sern/client');
+```
+
+</TabItem>
+
+<TabItem value="bad" label="Don't do this">
+
+```ts title="index.ts" showLineNumbers
+import { Service, makeDependencies } from '@sern/handler';
+/* DON'T USE SERVICES BEFORE CALLING makeDependencies */
+const logger = Service('@sern/logger');
+
+await makeDependencies()
+```
+
+</TabItem>
+
+</Tabs>
+
+- Services can only be used after sern has made dependencies. 
+    - Calling a service before will crash your application. 
+- Services can be safely used outside of commandModules. 
+    - Be careful to not cause too many side effects.
+
+
+## Related api
 - use `Service` for single dependency.
 - use `Services` for multiple dependencies.