feat: document task bot (#25)

Related to #23, closes #20

Reviewed-on: https://codeberg.org/nhcarrigan/docs/pulls/25
Co-authored-by: Naomi Carrigan <commits@nhcarrigan.com>
Co-committed-by: Naomi Carrigan <commits@nhcarrigan.com>

astro.config.mjs

@@ -7,8 +7,13 @@ export default defineConfig({
   integrations: [starlight({
     title: "Naomi's Documentation",
     sidebar: navigation,
-    tableOfContents: true,
+    tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 4},
     description: "Helpful documentation we want to share with everyone.",
+    editLink: {
+      baseUrl: "https://codeberg.org/nhcarrigan/docs/_edit/main/",
+      label: "Edit this page on Codeberg"
+    },
+    lastUpdated: true,
     social: {
       codeberg: "https://codeberg.org/nhcarrigan",
       github: "https://github.com/nhcarrigan",

src/components/navigation.ts

@@ -83,6 +83,16 @@ export const navigation = [
       }
     ]
   },
+  {
+    label: "Project Documentation",
+    items: [
+      {
+        label: "Task Bot",
+        link: "/projects/task-bot",
+        badge: { text: "v1.0.0", variant: "tip"}
+      }
+    ]
+  },
   {
     label: "Staff Guidelines",
     items: [

src/content/docs/about/contact.md

@@ -2,8 +2,6 @@
 title: Contact Policy
 ---
 
-**Effective 7 July 2024**
-
 ## 1. Support and Communication Channels
 
 ### 1.1 Public Support Channels

src/content/docs/about/donate.md

@@ -2,8 +2,6 @@
 title: Support Our Work 💜
 ---
 
-**Effective 7 July 2024**
-
 We are passionate about creating and maintaining free-to-use projects and providing guidance in various programming communities. Your support helps us continue this mission and expand our efforts.
 
 ## 1. Why Support Us?

src/content/docs/about/hire.md

@@ -2,8 +2,6 @@
 title: Hire us!
 ---
 
-**Effective 7 July 2024**
-
 We're excited about the opportunity to collaborate with you and contribute to the success of your goals. Our team brings a wealth of experience and a passion for delivering high-quality solutions tailored to your specific needs.
 
 !["If you knew I was so unstable, why'd you hire me?](https://cdn.nhcarrigan.com/hire.jpeg)

src/content/docs/archive/vtubing.md

@@ -2,8 +2,6 @@
 title: Naomi's VTubing Setup
 ---
 
-**Effective 14 July 2024**
-
 Naomi uses her VTuber model for all of her client meetings, as well as streaming. Getting the software to work on Linux is a bit of a nightmare, so this page documents how she does so.
 
 ## 1. OpenSeeFace

src/content/docs/community/appeal.md

@@ -2,8 +2,6 @@
 title: Appealing a Sanction
 ---
 
-**Effective 7 July 2024**
-
 Our moderators exercise careful discretion when implementing disciplinary measures (including but not limited to temporary suspensions, permanent bans, or other access restrictions). However, we acknowledge that misunderstandings or errors may occasionally occur.
 
 If you believe you have been unjustly restricted from participating in our community, you may initiate our formal appeal process as outlined below.

src/content/docs/community/coc.md

@@ -2,8 +2,6 @@
 title: Code of Conduct
 ---
 
-**Effective 7 July 2024**
-
 ## 1. Definitions
 
 ### 1.1. "Our Community"

src/content/docs/community/guide.md

@@ -2,8 +2,6 @@
 title: Community Guidelines
 ---
 
-**Effective 7 July 2024**
-
 ## 1. Introduction
 
 Welcome to our community. These guidelines are designed to foster a safe, respectful, and productive environment for all members. While not exhaustive or legally binding, adherence to these principles is strongly encouraged to maintain the integrity and value of our community.

src/content/docs/dev/contributing.md

@@ -2,8 +2,6 @@
 title: Contributing Documentation
 ---
 
-**Effective 7 July 2024**
-
 ## 1. Scope and General Contribution Guidelines
 
 ### 1.1 Overview

src/content/docs/dev/covenant.md

@@ -2,8 +2,6 @@
 title: nhcarrigan Contributor Covenant
 ---
 
-**Effective 7 July 2024**
-
 Copyright (C) 2024 nhcarrigan and its contributors.
 
 Everyone is permitted to copy and distribute verbatim copies of this

src/content/docs/dev/environment.md

@@ -2,8 +2,6 @@
 title: Development Environment
 ---
 
-**Effective 14 July 2024**
-
 This page documents Naomi's local development environment. The information here is provided to allow contributors to mirror the environment as closely as possible, ensuring the smoothest developer experience.
 
 ## 1. System Information

src/content/docs/dev/hall-of-fame.md

@@ -2,8 +2,6 @@
 title: Security Hall of Fame
 ---
 
-**Effective 7 July 2024**
-
 ## 1. Purpose
 This document recognises the folks who have reported security vulnerabilities in our Applications pursuant to our [security policy](/security).
 

src/content/docs/dev/labels.md

@@ -2,8 +2,6 @@
 title: Labels
 ---
 
-**Effective 14 July 2024**
-
 We use very specific labels to help categorise our issues. This page explains what each label means.
 
 ## 1. Contribution Labels

src/content/docs/dev/servers.md

@@ -2,8 +2,6 @@
 title: Server Setup
 ---
 
-**Effective 14 July 2024**
-
 This document outlines how we set up our remote servers for running projects.
 
 ## 1. Provision a Server

src/content/docs/legal/dmca.md

@@ -2,8 +2,6 @@
 title: DMCA and Intellectual Property Compliance Policy
 ---
 
-**Effective 7 July 2024**
-
 ## 1. General Principles
 
 - Respect for intellectual property rights is fundamental to our community's ethos and operations.

src/content/docs/legal/license.md

@@ -2,8 +2,6 @@
 title: Naomi's Public License
 ---
 
-**Effective 7 July 2024**
-
 All of Our Open Source Software are licensed under these terms.
 
 ## 1. Definitions

src/content/docs/legal/privacy.md

@@ -2,8 +2,6 @@
 title: Privacy Policy
 ---
 
-**Effective 7 July 2024**
-
 ## 1. Overview and Scope
 
 ### 1.1. General Applicability

src/content/docs/legal/security.md

@@ -2,8 +2,6 @@
 title: Security Policy
 ---
 
-**Effective 7 July 2024**
-
 ## 1. Introduction
 
 This Security Policy outlines the procedures for reporting security vulnerabilities in our applications and the terms under which we handle such reports. By participating in our security reporting process, you agree to comply with this policy.

src/content/docs/legal/terms.md

@@ -2,8 +2,6 @@
 title: Terms of Service
 ---
 
-**Effective 7 July 2024**
-
 ## 1. OVERVIEW AND ACCEPTANCE OF TERMS
 
 ### 1.1 Application Operator

src/content/docs/projects/task-bot.md

@@ -0,0 +1,294 @@
+---
+title: Task Bot
+---
+
+Task Bot (hereinafter the "Application") is a custom utility we developed for [Retro Island Gaming](https://retroisland.ny), but the source code is available for all to use as denoted in our software license.
+
+We do NOT offer a public instance of this Application. Instead, please refer to Section 2 for instructions on setting up your own version.
+
+## 1. User Documentation
+
+This section is for those interacting with a live instance of the Application.
+
+### 1.1. User Interactivity
+
+Interaction with the Application is done through a series of slash commands ("Commands") exposed via Discord's native UI. The primary function of the Application is to allow users to create and manage "tasks", or records of objectives that must be completed.
+
+#### 1.1.1. `assign` Command
+
+The `/assign` command allows you to assign a specific Discord user to a task. A task may have multiple assignees.
+
+![A discord slash command named Assign, taking a task and assignee argument](/images/task-bot/assign.png)
+
+##### 1.1.1.1. Required Arguments
+
+- `task`: An integer greater than 0, which is the unique identifier of the task you want to edit.
+- `assignee`: The user to assign to (or unassign from) a ticket.
+
+##### 1.1.1.2. Optional Arguments
+
+- `null`
+
+##### 1.1.1.3. Execution
+
+Once the command has been called, a database query will be made to confirm a task exists with the given `task` ID.
+
+If a task does not exist, you will be notified.
+
+If a task does exist, the Application will determine whether the `assignee` has been added to the task previously or not. If the `assignee` is already on the task, they will be removed. If they are not on the task, they will be assigned. You will be shown a confirmation message indicating which action the Application performed.
+
+#### 1.1.2. `complete` Command
+
+The `/complete` command allows you to mark a task as completed. Once completed, a task can not be uncompleted. It can still be modified and deleted.
+
+![A discord slash command named Complete, taking a task argument](/images/task-bot/complete.png)
+
+##### 1.1.2.1. Required Arguments
+
+- `task`: An integer greater than 0, which is the unique identifier of the task you want to edit.
+
+##### 1.1.2.2. Optional Arguments
+
+- `null`
+
+##### 1.1.2.3. Execution
+
+Once the command has been called, a database query will be made to confirm a task exists with the given `task` ID.
+
+If a task does not exist, you will be notified.
+
+If a task does exist, the Application will mark the task as completed and inform you of the success.
+
+#### 1.1.3. `create` Command
+
+The `/create` command allows you to create a new task.
+
+![A discord slash command named Create, which takes no arguments](/images/task-bot/create.png)
+
+##### 1.1.2.1. Required Arguments
+
+- `null`
+
+##### 1.1.2.2. Optional Arguments
+
+- `null`
+
+##### 1.1.2.3. Execution
+
+Once the command has been called, the Application will construct and show a Discord-powered modal form. There are three fields you must complete.
+
+![A discord modal titled New Task, with title, description, and due date fields.](/images/task-bot/create-modal.png)
+
+- `TITLE`: The title of the task. This should be a short summary.
+- `DESCRIPTION`: The description of the task. This may be longer, and supports multiple lines.
+- `DUE DATE`: The date the task is due. This must be a format that can be parsed, such as `September 1, 2000`.
+
+:::caution
+If the Application cannot parse your `DUE DATE` value, it will fall back to the current date. You can edit this with the `/update` command.
+:::
+
+When you submit the modal form, the Application will insert a new task into the database and assign it an incremental ID. It will provide this ID to you as confirmation.
+
+#### 1.1.4. `delete` Command
+
+The `/delete` command allows you to "delete" a task from the database. The task record will remain present, as the incremental ID logic requires records to persist. All information will be scrubbed from the task and replaced with default values.
+
+:::danger
+Deleting a task is a very destructive action. You will not be able to undo it. Our support team will not be able to undo it. The data will be purged from our records.
+:::
+
+![A discord slash command named Delete, which takes a task argument](/images/task-bot/delete.png)
+
+##### 1.1.4.1. Required Arguments
+
+- `task`: The numerical identifier of the task you wish to delete.
+
+##### 1.1.4.2. Optional Arguments
+
+- `null`
+
+##### 1.1.4.3. Execution
+
+Once the command has been called, a database query will be made to confirm a task exists with the given `task` ID.
+
+If a task does not exist, you will be notified.
+
+If a task does exist, the Application will mark the task as `deleted`, and set the following default values:
+
+```json
+{
+    "assignees":   [],
+    "deleted":     true,
+    "description": "This task has been deleted.",
+    "dueAt":       Date,
+    "priority":    "deleted",
+    "tags":        [],
+    "title":       "Deleted Task",
+
+}
+```
+
+You will receive confirmation when the deletion is complete.
+
+#### 1.1.5. `list` Command
+
+The `list` command allows you to view your tasks, optionally applying filters to narrow the results.
+
+![A discord slash command named List, which takes priority, tag, assignee, and completed arguments](/images/task-bot/list.png)
+
+##### 1.1.5.1. Required Arguments
+
+- `null`
+
+##### 1.1.5.2. Optional Arguments
+
+- `priority`: Only show tasks which are at this priority level. If omitted, will show all priorities.
+- `tag`: Only show tasks whose tags include this tag. If omitted, will not restrict query by any tags.
+- `assignee`: Only show tasks whose assignees include this user. If omitted, will not restrict query by any assignees.
+- `completed`: Show either complete or incomplete tasks. If omitted, will show incomplete tasks.
+
+##### 1.1.5.3. Execution
+
+The Application will construct your selected filters into a database query and use that to fetch the tasks.
+
+If your query returns no tasks, the Application will notify you to adjust your filters. Otherwise, you will receive a list of task titles and IDs.
+
+#### 1.1.6. `priority` Command
+
+The priority command allows you to modify the priority level of a task. A task may have one of the following priorities: `Low`, `Medium`, `High`, `Critial`, and `None`.
+
+![A discord slash command named Priority, which takes task and priority arguments](/images/task-bot/priority.png)
+
+##### 1.1.6.1. Required Arguments
+
+- `null`
+
+##### 1.1.6.2. Optional Arguments
+
+- `null`
+
+##### 1.1.6.3. Execution
+
+Once the command has been called, a database query will be made to confirm a task exists with the given `task` ID.
+
+If a task does not exist, you will be notified.
+
+If a task does exist, the Application will update the `priority` field and send you a confirmation.
+
+#### 1.1.7. `tag` Command
+
+The `/tag` command allows you to assign a specific tag to a task. A task may have multiple tags.
+
+![A discord slash command named Tag, taking a task and tag argument](/images/task-bot/tag.png)
+
+##### 1.1.7.1. Required Arguments
+
+- `task`: An integer greater than 0, which is the unique identifier of the task you want to edit.
+- `tag`: The case-sensitive tag to apply.
+
+##### 1.1.7.2. Optional Arguments
+
+- `null`
+
+##### 1.1.7.3. Execution
+
+Once the command has been called, a database query will be made to confirm a task exists with the given `task` ID.
+
+If a task does not exist, you will be notified.
+
+If a task does exist, the Application will determine whether the `tag` has been added to the task previously or not. If the `tag` is already on the task, it will be removed. If it is not on the task, it will be added. You will be shown a confirmation message indicating which action the Application performed.
+
+#### 1.1.8. `update` Command
+
+The `/update` command allows you to update an existing task.
+
+![A discord slash command named update, which takes no arguments](/images/task-bot/update.png)
+
+##### 1.1.8.1. Required Arguments
+
+- `null`
+
+##### 1.1.8.2. Optional Arguments
+
+- `null`
+
+##### 1.1.8.3. Execution
+
+Once the command has been called, the Application will construct and show a Discord-powered modal form. There is one field you MUST complete, and three fields you MAY complete.
+
+![A discord modal titled Update Task, with title, description, and due date fields.](/images/task-bot/update-modal.png)
+
+- `TASK NUMBER`: The numerical identifier of the task you wish to update.
+- `TITLE`: The title of the task. This should be a short summary.
+- `DESCRIPTION`: The description of the task. This may be longer, and supports multiple lines.
+- `DUE DATE`: The date the task is due. This must be a format that can be parsed, such as `September 1, 2000`.
+
+If you do not want to update a field, leave it blank and the Application will not modify it.
+
+:::caution
+If the Application cannot parse your `DUE DATE` value, it will fall back to the current date.
+:::
+
+When you submit the modal form, the Application will construct an update query from your fields. It will then try to update the task in the database, using the ID you provide. If it fails to find a record with that ID, it will notify you. Otherwise, it will send a confirmation message.
+
+#### 1.1.9. `view` Command
+
+The view command allows you to query a task by its ID and see all the information on that task.
+
+![A discord slash command named view, which accepts a single id argument](/images/task-bot/view.png)
+
+##### 1.1.9.1. Required Arguments
+
+- `id`: The numerical ID of the task you wish to view.
+
+##### 1.1.9.2. Optional Arguments
+
+- `null`
+
+##### 1.1.9.3. Execution
+
+When you run the command, the bot will fetch the task matching your specified ID from the database. If no task is found, the bot will notify you.
+
+![A discord embed showing the details of a task, including the title, description, due date, tags, and priority](/images/task-bot/view-embed.png)
+
+Otherwise, the bot will display an embed containing all of the information about that task.
+
+### 1.2. User Access Permissions
+
+:::danger
+The Application does not perform any permission validation against users calling commands. All commands are available to all users.
+:::
+
+If you need to restrict access to specific commands based on a user's permission levels, you can do so through Discord's native UI.
+
+![Discord's command permissions screen, with the everyone role denied access, the Staff role granted access, and the complete command indicating it has overrides](/images/task-bot/command-permissions.png)
+
+This functionality will allow you to hide commands from users with or without specific roles, or grant scoped access to individual commands and channels. For more instructions on how to leverage this tool, please review [Discord's support article for command permissions](https://support.discord.com/hc/en-us/articles/4644915651095-Command-Permissions).
+
+### 1.3. Application Access Permissions
+
+The Application should not require any specific Discord permissions to function in your community.
+
+### 1.4. Errors
+
+We strive to deliver reliable and quality applications, but we are not perfect. If the Application generates an error, it will provide you with a Snowflake ID and a link to [our support server](https://chat.nhcarrigan.com).
+
+When you join the server and share the ID with us, we will be able to look up the specific log and determine the cause of the error.
+
+Note that not all errors are caused by the Application. Errors can occur for many reasons, including misconfigured permissions on the user side, external platform outages, and more. Our support team will be happy to assist you with any errors that you encounter, but we kindly ask that you demonstrate patience toward our team (many of whom are volunteers).
+
+## 2. Technical Documentation
+
+:::note
+This section is coming soon!
+:::
+
+This section is for those interested in running their own instance of the Application.
+
+## 3. Legal Documentation
+
+:::note
+This section is coming soon!
+:::
+
+This section is for expansions to our legal policies specific to the Application.

src/content/docs/staff/apply.md

@@ -2,8 +2,6 @@
 title: Join Our Staff Team
 ---
 
-**Effective 7 July 2024**
-
 ## 1. Volunteer Positions
 
 Unless explicitly stated otherwise in a separate written agreement, all positions within our organization are on a voluntary basis. No compensation, monetary or otherwise, should be expected for these roles.

src/content/docs/staff/handbook.md

@@ -2,8 +2,6 @@
 title: Staff Handbook
 ---
 
-**Effective 7 July 2024**
-
 Welcome to our organization. This Staff Handbook serves as a comprehensive guide to our policies, procedures, and expectations. It is designed to help you understand your role in our community and how you can contribute to our collective success.
 
 We rely on every staff member, regardless of position, to help keep our community running smoothly and efficiently. Your dedication, skills, and adherence to our standards are crucial in achieving our organizational goals.

src/styles/style.css

@@ -51,3 +51,15 @@ header {
   color: var(--primary-color) !important;
   background-color: var(--background-color) !important;
 }
+
+.right-sidebar-panel :where(a) {
+  color: var(--primary-color) !important;
+}
+
+footer > div > a, footer > div > a:visited, footer > div > p {
+  color: var(--primary-color) !important;
+}
+
+.right-sidebar-panel :where(a):hover {
+  color: white !important;
+}