nhcarrigan/docs
9
0
Fork 0
generated from nhcarrigan/template
Code Issues 2 Pull Requests 6 Actions Releases 1 Activity

feat: document all products, write tests #12

Merged
naomi merged 4 commits from feat/many-docs into main 2025-10-29 18:55:40 -07:00
Conversation 0 Commits 4 Files Changed 68
+8285 -1573
68 changed files with 8285 additions and 1573 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.cspell.json
+34 -1
View File
@@ -32,15 +32,26 @@
"Ghostty",
"Amberol",
"Musicolet",
"wifi"
"wifi",
"neopronouns",
"linters",
"misgendered"
],
"words": [
"Abalise",
"Aeris",
"Alouette",
"Amari",
"Amirei",
"atproto",
"Aurelia",
"Aureline",
"bannable",
"Becca",
"Beccalia",
"Caelia",
"Calenelle",
"Callista",
"CCPA",
"Celestine",
"ČeÅ”tina",
@@ -48,6 +59,10 @@
"Chibika",
"CPACC",
"Dansk",
"Eirene",
"Elaria",
"Elowyn",
"Elunara",
"equivalencies",
"escalatory",
"excludable",
@@ -58,16 +73,26 @@
"Gitea",
"Hikari",
"incentivising",
"Isolda",
"Italiano",
"ITAR",
"Iuvo",
"Jessara",
"KADOKAWA",
"LGBTQ",
"Lietuvių",
"Liora",
"Lyria",
"Maribelle",
"Meliora",
"Meridia",
"minimis",
"Mommy",
"NAMI",
"Nederlands",
"Nymira",
"OFAC",
"Oriana",
"Pavelle",
"PIPEDA",
"Polski",
@@ -83,10 +108,18 @@
"Suomi",
"Svenska",
"Taryne",
"Tessara",
"Thalassa",
"Thessalia",
"TĆ¼rkƧe",
"Umbrelle",
"Veluna",
"Verena",
"Vitalia",
"Vivienne",
"vtubing",
"WCAG",
"Zephra",
"zirs",
"Ī•Ī»Ī»Ī·Ī½Ī¹ĪŗĪ¬",
"Š‘ŃŠŠ»Š³Š°Ń€ŃŠŗŠø",
astro.config.mjs
+8 -8
View File
@@ -33,14 +33,14 @@ export default defineConfig({
label: "Edit this page on Naomi's Self-hosted Git instance",
},
lastUpdated: true,
social: {
github: "https://git.nhcarrigan.com",
discourse: "https://forum.nhcarrigan.com",
mastodon: "https://fedi.nhcarrigan.com/@naomi",
matrix: "https://matrix.nhcarrigan.com",
rss: "https://irc.nhcarrigan.com",
email: "mailto:contact@nhcarrigan.com",
},
social: [
{ icon: 'github', label: 'GitHub', href: 'https://git.nhcarrigan.com' },
{ icon: 'discord', label: 'Discord', href: 'https://chat.nhcarrigan.com' },
{ icon: 'blueSky', label: 'Bluesky', href: 'https://bsky.app/profile/nhcarrigan.com' },
{ icon: 'linkedin', label: 'LinkedIn', href: 'https://www.linkedin.com/company/nhcarrigan/' },
{ icon: 'twitter', label: 'Twitter', href: 'https://x.com/nhcarrigan1' },
{ icon: 'email', label: 'Email', href: 'mailto:contact@nhcarrigan.com' },
],
logo: {
src: "./public/logo.png",
alt: "NHCarrigan Logo",
package.json
+10 -9
View File
@@ -9,18 +9,19 @@
"build": "astro build",
"preview": "astro preview",
"astro": "astro",
"scan": "SONAR_TOKEN='op://Environment Variables - Development/SonarCloud/docs' op run -- sonar-scanner -Dsonar.organization=nhcarrigan -Dsonar.projectKey=nhcarrigan_docs -Dsonar.sources=. -Dsonar.host.url=https://sonarcloud.io",
"test": "echo 'No tests yet!' && exit 0"
"test": "vitest --run"
},
"dependencies": {
"@astrojs/check": "^0.9.4",
"@astrojs/starlight": "^0.32.0",
"astro": "^5.3.0",
"astro-mermaid": "1.0.4",
"mermaid": "11.11.0",
"typescript": "^5.7.3"
"@astrojs/check": "0.9.5",
"@astrojs/starlight": "0.36.1",
"astro": "5.15.2",
"astro-mermaid": "1.1.0",
"mermaid": "11.12.1",
"typescript": "5.9.3"
},
"devDependencies": {
"cspell": "8.17.3"
"cspell": "9.2.2",
"gray-matter": "4.0.3",
"vitest": "4.0.5"
}
}
pnpm-lock.yaml
Generated
+1920 -1271
View File
File diff suppressed because it is too large Load Diff
src/components/navigation.ts
+259 -17
View File
@@ -1,6 +1,7 @@
export const navigation = [
{
label: "About Us",
collapsed: true,
items: [
{
label: "Mission Statement",
@@ -26,10 +27,11 @@ export const navigation = [
label: "Mentorship Programme Terms and Conditions",
link: "/about/mentorship",
},
],
].sort((a, b) => a.label.localeCompare(b.label)),
},
{
label: "Legal Information",
collapsed: true,
items: [
{
label: "Limitation of Liability and Indemnification Policy",
@@ -44,7 +46,7 @@ export const navigation = [
link: "/legal/privacy",
},
{
label: "Naomi's Public License",
label: "Naomi's Public Licence",
link: "/legal/license",
},
{
@@ -90,11 +92,12 @@ export const navigation = [
{
label: "Crisis and Mental Health Management Policy",
link: "/legal/crisis-mental-health",
}
],
},
].sort((a, b) => a.label.localeCompare(b.label)),
},
{
label: "Community Policies",
collapsed: true,
items: [
{
label: "Community Code of Conduct",
@@ -120,13 +123,14 @@ export const navigation = [
label: "Community Feedback and Participation Policy",
link: "/community/feedback",
},
],
].sort((a, b) => a.label.localeCompare(b.label)),
},
{
label: "Development Documentation",
collapsed: true,
items: [
{
label: "Contributing Guide",
label: "Contributing Documentation",
link: "/dev/contributing",
},
{
@@ -150,13 +154,18 @@ export const navigation = [
link: "/dev/servers",
},
{
label: "VTubing Setup",
label: "Naomi's VTubing Setup",
link: "/dev/vtubing",
},
],
{
label: "Security Hall of Fame",
link: "/dev/hall-of-fame",
}
].sort((a, b) => a.label.localeCompare(b.label)),
},
{
label: "Project Documentation",
collapsed: true,
items: [
{
label: "ESLint Config",
@@ -176,7 +185,7 @@ export const navigation = [
{
label: "Naomi's Blog",
link: "/projects/blog",
badge: { text: "v0.1.0", variant: "caution" },
badge: { text: "v1.0.0", variant: "tip" },
},
{
label: "Celestine",
@@ -219,7 +228,7 @@ export const navigation = [
badge: { text: "v0.0.0", variant: "danger" },
},
{
label: "NHCarrigan Portfolio",
label: "Portfolio",
link: "/projects/portfolio",
badge: { text: "unversioned", variant: "success" },
},
@@ -299,14 +308,245 @@ export const navigation = [
badge: { text: "v1.0.0", variant: "tip" },
},
{
label: "Documentation Site",
label: "NHCarrigan Documentation",
link: "/projects/docs",
badge: { text: "v1.0.0", variant: "tip" },
},
{
label: "Data API",
link: "/projects/data-api",
badge: { text: "v1.0.0", variant: "tip" },
},
{
label: "Nymira",
link: "/projects/nymira",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Vitalia",
link: "/projects/vitalia",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Octavia",
link: "/projects/octavia",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Maribelle",
link: "/projects/maribelle",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Verena",
link: "/projects/verena",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Thalassa",
link: "/projects/thalassa",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Aeris",
link: "/projects/aeris",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Thessalia",
link: "/projects/thessalia",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Isolda",
link: "/projects/isolda",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Meliora",
link: "/projects/meliora",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Aurelia",
link: "/projects/aurelia",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Eirene",
link: "/projects/eirene",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Amirei",
link: "/projects/amirei",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Zephra",
link: "/projects/zephra",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Oriana",
link: "/projects/oriana",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Lyra",
link: "/projects/lyra",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Selene",
link: "/projects/selene",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Sybil",
link: "/projects/sybil",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Calenelle",
link: "/projects/calenelle",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Rowena",
link: "/projects/rowena",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Alouette",
link: "/projects/alouette",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Clarion",
link: "/projects/clarion",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Elowyn",
link: "/projects/elowyn",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Evangeline",
link: "/projects/evangeline",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Theodora",
link: "/projects/theodora",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Vivienne",
link: "/projects/vivienne",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Elysium",
link: "/projects/elysium",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Elaria",
link: "/projects/elaria",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Elunara",
link: "/projects/elunara",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Aureline",
link: "/projects/aureline",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Tessara",
link: "/projects/tessara",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Hacksmiths",
link: "/projects/hacksmiths",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Meridia",
link: "/projects/meridia",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Lucinda",
link: "/projects/lucinda",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Liora",
link: "/projects/liora",
badge: { text: "1.0.0", variant: "tip" },
},
{
label: "Beccalia: Origins",
link: "/projects/beccalia-origins",
badge: { text: "v0.0.0", variant: "danger" },
},
{
label: "Beccalia: Prologue",
link: "/projects/beccalia-prologue",
badge: { text: "v1.0.1", variant: "tip" },
},
{
label: "Life of a Naomi",
link: "/projects/life-of-a-naomi",
badge: { text: "v1.0.0", variant: "tip" },
},
{
label: "Ruu's Goblin Quest",
link: "/projects/ruus-goblin-quest",
badge: { text: "v1.0.0", variant: "tip" },
},
{
label: "Naomi's Adventure I: An Isekai Story",
link: "/projects/naomis-adventure-i",
badge: { text: "unreleased", variant: "danger" },
},
{
label: "Amari",
link: "/projects/amari",
badge: { text: "v1.0.0", variant: "tip" },
},
{
label: "Artists4Palestine Bot",
link: "/projects/a4p-bot",
badge: { text: "v1.0.0", variant: "tip" },
},
{
label: "Naomi's VSCode Themes",
link: "/projects/vscode-themes",
badge: { text: "v2.2.0", variant: "tip" },
},
{
label: "Boost Monitor",
link: "/projects/boost-monitor",
badge: { text: "v1.0.1", variant: "tip" },
},
{
label: "TypeScript Config",
link: "/projects/typescript-config",
badge: { text: "v4.0.0", variant: "tip" },
}
].sort((a, b) => a.label.localeCompare(b.label)),
].sort((a, b) => a.label.localeCompare(b.label)),
},
{
label: "Staff Guidelines",
collapsed: true,
items: [
{
label: "Staff Handbook",
@@ -334,6 +574,7 @@ export const navigation = [
},
{
label: "Additional Trainings",
collapsed: true,
items: [
{
label: "Accessibility Coordination Training for Staff",
@@ -386,23 +627,24 @@ export const navigation = [
{
label: "Technical Contributor Training for Staff",
link: "/staff/training/technical-contributor",
}
]
},
].sort((a, b) => a.label.localeCompare(b.label)),
},
{
label: "Staff Policy Self-Assessment",
link: "/staff/policy-self-assessment",
}
],
},
].sort((a, b) => a.label.localeCompare(b.label)),
},
{
label: "Miscellaneous Documents",
collapsed: true,
items: [
{
label: "Managing Local Music",
link: "/misc/music",
},
],
].sort((a, b) => a.label.localeCompare(b.label)),
},
{
label: "Sitemap",
src/content/docs/community/coc.md
+1 -1
View File
@@ -616,7 +616,7 @@ Community Leaders possess both the authority and obligation to:
#### 10.3.2 Discretionary Enforcement
While this Code provides comprehensive guidance, Community Leaders retain discretion to:
- Address situations not explicitly covered by written policies
- Apply contextual judgment in complex or unusual circumstances
- Apply contextual judgement in complex or unusual circumstances
- Implement innovative solutions to emerging community challenges
- Prioritise community safety and well-being over rigid rule application
src/content/docs/dev/covenant.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
title: nhcarrigan Contributor Covenant
title: Contributor Covenant
---
Copyright (C) 2024 nhcarrigan and its contributors.
src/content/docs/dev/labels.md
+2 -2
View File
@@ -1,5 +1,5 @@
---
title: Labels
title: "Issue/PR Labels"
---
We use very specific labels to help categorise our issues. This page explains what each label means.
@@ -52,7 +52,7 @@ Staff members working on these issues must adhere to all relevant confidentialit
### 1.4 Disclaimer
Labels are assigned based on the project maintainers' best judgment but may not guarantee the exact level of difficulty or access requirements for every contributor. Contributors should use their discretion and communicate with project maintainers if they have any doubts about their ability to address an issue or comply with any associated legal requirements.
Labels are assigned based on the project maintainers' best judgement but may not guarantee the exact level of difficulty or access requirements for every contributor. Contributors should use their discretion and communicate with project maintainers if they have any doubts about their ability to address an issue or comply with any associated legal requirements.
## 2. Aspect Labels
src/content/docs/intro.mdx
+2 -14
View File
@@ -6,19 +6,7 @@ hero:
tagline:
This site contains all of the documentation related to NHCarrigan, its Policies, and its Projects.
actions:
- text: Mission Statement
- text: Let's Go!
link: /about/mission/
variant: secondary
- text: Code of Conduct
link: /community/coc/
variant: secondary
- text: Contributing Guide
link: /dev/contributing/
variant: secondary
- text: Software License
link: /legal/license/
variant: secondary
- text: Contact Us
link: /about/contact/
variant: secondary
variant: primary
---
src/content/docs/legal/community-support-policy.md
+1 -1
View File
@@ -184,7 +184,7 @@ This policy applies to all forms of support exchange within our community platfo
**What Peer Support IS:**
- Sharing personal experiences and what has worked for you
- Listening with empathy and without judgment
- Listening with empathy and without judgement
- Providing resources and information from your own knowledge
- Offering practical assistance within your capacity and expertise
- Being present and available when you can be
src/content/docs/legal/export-control.md
+1 -1
View File
@@ -426,7 +426,7 @@ Supplementing automated systems, we maintain manual review procedures including:
**(a)** **High-Risk Transactions**: Manual review of all high-risk transactions and relationships;
**(b)** **Complex Cases**: Human review of complex compliance cases requiring judgment and analysis;
**(b)** **Complex Cases**: Human review of complex compliance cases requiring judgement and analysis;
**(c)** **Exception Handling**: Manual processing of cases requiring special consideration or exceptions;
src/content/docs/misc/music.md
+1 -1
View File
@@ -1,5 +1,5 @@
---
title: Downloading and Editing Music
title: Managing Local Music
---
This serves as our documentation for how we manage our local music libraries on Linux.
src/content/docs/projects/a4p-bot.md
+892
View File
@@ -0,0 +1,892 @@
---
title: Artists4Palestine Bot
---
Artists4Palestine Bot (hereinafter the "Application") is a Discord bot designed to facilitate the Art for Palestine charity event. The Application serves as an automated bridge between Airtable, Trello, and Discord to manage art commission requests, artist assignments, delivery tracking, and support tickets for the charity event.
## 1. User Documentation
This section is for those interacting with a live instance of the Application.
### 1.1 Getting Started
The Art for Palestine Bot is available on the [Art for Palestine Discord server](https://discord.gg/kHNyb6Vyf8). Once you join the server, you will automatically be assigned the member role and can begin interacting with the bot's features.
### 1.2 Requesting Art Commissions
Art commission requests are submitted through an Airtable form (external to Discord). Once submitted, your request will automatically appear in the designated commission channel where artists can view and claim it. Your request should include:
- Your name
- Preferred contact method (Email, Discord, or Twitter)
- Your contact handle/username
- Description of the art you would like drawn
- Reference images (optional)
- Any additional notes or requirements
### 1.3 Artist Features
#### 1.3.1 Claiming Art Commissions
As an artist, you can claim art commissions by reacting to commission posts in the art commission channel (ID: `1172568787330019340`).
**Important Notes:**
- You can only claim up to 2 commissions at a time
- Claiming a commission creates a private thread for coordination
- The thread will include your mention and the requester's information
#### 1.3.2 Submitting Completed Artwork
Once you've completed the artwork:
1. Post the completed artwork as an image attachment in the private thread
2. The bot will automatically forward your submission to the distribution channel
3. Your thread will be archived
4. The commission will be removed from your active count
#### 1.3.3 Art Reminders
The bot sends automated reminders to help manage workload:
- **Unclaimed Art Reminders**: Sent Monday, Wednesday, and Friday at 9:00 AM
- **Unfinished Art Reminders**: Sent Saturday at 9:00 AM
### 1.4 Distribution Features
#### 1.4.1 Claiming Distributions
Distribution team members can claim distribution tasks by reacting to posts in the distribution channel (ID: `1173061747737903315`). Similar to art commissions:
- Maximum 2 concurrent distributions per member
- Creates a private coordination thread
- Includes recipient and artwork details
#### 1.4.2 Confirming Deliveries
To confirm a distribution:
1. Deliver the artwork to the recipient
2. Post a confirmation image in the private thread
3. The bot will close and archive the thread
#### 1.4.3 Distribution Reminders
- **Unclaimed Distribution Reminders**: Sent Monday, Wednesday, and Friday at 9:00 AM
- **Unfinished Distribution Reminders**: Sent Saturday at 9:00 AM
### 1.5 Support Ticket System
#### 1.5.1 Opening a Ticket
Users can open support tickets using the ticket button in the designated ticket channel:
1. Click the "Open Ticket" button
2. Fill out the modal form with your issue description
3. A private thread will be created for your ticket
4. Support team members will be notified
#### 1.5.2 Ticket Workflow
- **For Users**: Describe your issue in the private thread and wait for a support team member to claim it
- **For Support Team**: Click "Claim Ticket" to add your mention and take responsibility for the issue
- Conversations in the ticket thread are automatically logged
#### 1.5.3 Closing Tickets
Support team members can close tickets using the "Close Ticket" button:
- A log file of the entire conversation will be generated
- The log is sent to the ticket archive channel
- The thread is closed and archived
### 1.6 Moderation Commands
Moderation team members with the support role (ID: `1173582640843063366`) have access to these commands:
#### `!mute <user_id> <duration> <reason>`
Temporarily timeout a user.
**Parameters:**
- `user_id`: The Discord user ID to mute
- `duration`: Duration with unit (e.g., `30m`, `2h`, `1d`)
- Supported units: `s` (seconds), `m` (minutes), `h` (hours), `d` (days)
- `reason`: Explanation for the timeout
**Example:**
```
!mute 123456789012345678 1h Spam in general channel
```
#### `!unmute <user_id> <reason>`
Remove a timeout from a user.
**Parameters:**
- `user_id`: The Discord user ID to unmute
- `reason`: Explanation for removing the timeout
**Example:**
```
!unmute 123456789012345678 Appeal accepted
```
### 1.7 Palestine News Updates
The bot automatically fetches and posts news updates from Al Jazeera's Palestine live blog:
- Updates are checked every 10 minutes
- New articles are posted to the news channel
- Prevents duplicate posts using article ID tracking
### 1.8 Getting Help
If you encounter issues or have questions:
- Open a support ticket in the Discord server
- Report bugs on [GitHub Issues](https://github.com/naomi-lgbt/nodejs-typescript-template/issues)
- Contact via the [chat server](http://chat.nhcarrigan.com) or email at `contact@nhcarrigan.com`
---
## 2. Technical Documentation
This section is for those interested in running their own instance of the Application.
### 2.1 Prerequisites
Before running your own instance, ensure you have:
- **Node.js**: Version 22 (specified in `package.json`)
- **pnpm**: Version 10 (package manager)
- **Discord Bot Account**: With a bot token and appropriate permissions
- **Airtable Account**: With API access
- **Discord Webhooks**: Multiple webhooks configured for different channels
### 2.2 Required Discord Permissions
Your Discord bot requires the following Gateway Intents:
- `GuildMessages`: Access to guild message events
- `Guilds`: Access to guild/server data
- `GuildMessageReactions`: Access to message reaction events
- `MessageContent`: Privileged intent for full message content access
- `GuildMembers`: Access to member data
### 2.3 Environment Configuration
Create a `.env` file in the project root with the following variables:
```env
# Discord Bot Configuration
TOKEN=your_discord_bot_token
# Discord Webhooks
DEBUG=https://discord.com/api/webhooks/... # Debug/error logging
COMM=https://discord.com/api/webhooks/... # Commission notifications
DIST=https://discord.com/api/webhooks/... # Distribution notifications
NEWS=https://discord.com/api/webhooks/... # Palestine news updates
TICKET=https://discord.com/api/webhooks/... # Ticket logs
# Airtable Configuration
AIRTABLE_KEY=your_airtable_api_key
AIRTABLE_BASE_ID=your_base_id
AIRTABLE_TABLE_ID=your_table_name
# Server Configuration (optional)
NODE_ENV=production # Set to enable HTTPS server on port 10443
```
### 2.4 Hardcoded Configuration
Several IDs are hardcoded in the `src/config/` directory and must be updated for your server:
**File: `src/config/Tickets.ts`**
- `guildId`: Your Discord server ID
- `supportRole`: Your support team role ID
**File: `src/config/Webhooks.ts`**
- `artChannelId`: Channel for art commission posts
- `distributionChannelId`: Channel for distribution posts
**File: `src/config/Trello.ts`**
- Trello board, list, and label IDs (if using Trello integration)
### 2.5 Installation
1. Clone the repository:
```bash
git clone https://github.com/naomi-lgbt/nodejs-typescript-template.git
cd nodejs-typescript-template
```
2. Install dependencies:
```bash
pnpm install
```
3. Configure environment variables (see section 2.3)
4. Build the TypeScript code:
```bash
pnpm build
```
### 2.6 Running the Bot
Start the bot in production mode:
```bash
pnpm start
```
This will:
- Load environment variables from `.env`
- Execute the compiled JavaScript from `prod/index.js`
- Connect to Discord
- Initialize event listeners and scheduled tasks
- Start the HTTP server on port 10080 (HTTP) or 10443 (HTTPS if `NODE_ENV=production`)
### 2.7 Development Workflow
For development and testing:
**Linting:**
```bash
pnpm lint
```
Runs ESLint and Prettier to check code style and formatting.
**Testing:**
```bash
pnpm test
```
Runs Mocha test suite with TypeScript support (timeout: 10 seconds).
**Building:**
```bash
pnpm build
```
Compiles TypeScript files from `src/` to JavaScript in `prod/`.
### 2.8 Architecture Overview
#### 2.8.1 Project Structure
```
a4p-bot/
ā”œā”€ā”€ src/
ā”‚ ā”œā”€ā”€ index.ts # Main entry point, bot initialization
ā”‚ ā”œā”€ā”€ config/ # Configuration files (channels, webhooks, Trello)
ā”‚ ā”œā”€ā”€ events/ # Discord event handlers
ā”‚ ā”œā”€ā”€ modules/ # Core business logic
ā”‚ ā”‚ ā”œā”€ā”€ buttons/ # Button interaction handlers
ā”‚ ā”‚ ā”œā”€ā”€ messages/ # Message processing logic
ā”‚ ā”‚ ā”œā”€ā”€ modals/ # Modal form handlers
ā”‚ ā”‚ ā””ā”€ā”€ reminders/ # Scheduled reminder tasks
ā”‚ ā”œā”€ā”€ interface/ # TypeScript interfaces and types
ā”‚ ā”œā”€ā”€ server/ # Express HTTP server
ā”‚ ā””ā”€ā”€ utils/ # Utility functions
ā”œā”€ā”€ prod/ # Compiled JavaScript output
ā”œā”€ā”€ logs/ # Ticket conversation logs (runtime)
ā””ā”€ā”€ .env # Environment variables (not committed)
```
#### 2.8.2 Core Components
**Discord Bot (src/index.ts:1)**
- Initializes Discord.js client with required intents
- Registers event listeners for messages, reactions, interactions, and member joins
- Creates webhook clients for different notification types
- Starts HTTP server for monitoring
**Event Handlers (src/events/)**
- `onReady.ts:1`: Initializes scheduled jobs, caches messages, sends startup notification
- `onMessageCreate.ts:1`: Handles commands (!mute, !unmute) and ticket message logging
- `onInteractionCreate.ts:1`: Routes button clicks and modal submissions
- `onReactionAdd.ts:1`: Manages art commission and distribution claims
- `onMemberAdd.ts:1`: Auto-assigns member role to new joiners
**Scheduled Tasks (node-schedule)**
- Runs every 60 minutes: Check Airtable for new form submissions
- Runs every 10 minutes: Fetch and post Palestine news updates
- Monday/Wednesday/Friday 9 AM: Send unclaimed art and distribution reminders
- Saturday 9 AM: Send unfinished art and distribution reminders
**Ticket System (src/modules/)**
- `buttons/ticketOpen.ts:1`: Opens modal form for ticket creation
- `modals/handleTicketModal.ts:1`: Creates private thread and initializes log file
- `buttons/ticketClaim.ts:1`: Adds support member's mention to thread
- `buttons/ticketClose.ts:1`: Generates log file, sends to archive, closes thread
- `logTicketMessage.ts:1`: Appends messages to log file in real-time
- `generateLogs.ts:1`: Reads log file and creates Discord attachment
**Airtable Integration (src/modules/checkAirtableRecords.ts:1)**
- Polls Airtable API for new form submissions
- Tracks latest record ID to avoid duplicate processing
- Extracts form fields (name, contact info, request details, reference images)
- Posts formatted messages to commission channel via webhook
**News Feed (src/utils/getNewsFeed.ts:1)**
- Fetches latest articles from Al Jazeera Palestine live blog via GraphQL
- Tracks last posted article ID to prevent duplicates
- Sends new updates to news webhook channel
#### 2.8.3 Data Flow
```
User Action (Discord) ā†’ Event Listener ā†’ Event Handler ā†’ Module Logic
ā†“
External API / Webhook Call
ā†“
Response/Notification
ā†“
Logging (Winston + Debug Webhook)
```
```
Scheduled Task ā†’ External API (Airtable/Al Jazeera) ā†’ Parse Response
ā†“
Send to Discord Webhook
ā†“
Update Cache/State
```
### 2.9 Database
While Prisma ORM is installed as a dependency, the Application does not currently use a database. All state is managed in memory using cache objects attached to the extended Discord client:
- `bot.ticketLogs`: Maps channel IDs to log file message IDs
- `bot.lastArticle`: Tracks the most recent news article ID
Ticket conversation logs are temporarily stored as text files in the `logs/` directory and deleted after being sent to the archive channel.
### 2.10 API Integrations
#### 2.10.1 Airtable REST API
**Endpoint:** `https://api.airtable.com/v0/{BASE_ID}/{TABLE_ID}`
**Method:** GET
**Headers:**
```
Authorization: Bearer {AIRTABLE_KEY}
```
**Query Parameters:**
- `maxRecords=100`: Limit results
- `sort[0][field]=Created`: Sort by creation time
- `sort[0][direction]=desc`: Newest first
**Response Structure (src/interface/AirtableResponse.ts:1):**
```typescript
{
records: [{
id: string;
createdTime: string;
fields: {
Name: string;
"Contact Method": "Email" | "Discord" | "Twitter";
Handle: string;
"What would you like us to draw?": string;
"Anything Else?": string;
Reference?: { url: string }[];
}
}]
}
```
#### 2.10.2 Al Jazeera GraphQL API
**Endpoint:** `https://www.aljazeera.com/graphql` (inferred from code)
**Operations:**
- `SingleLiveBlogChildrensQuery`: Fetch live blog structure
- `LiveBlogUpdateQuery`: Fetch latest blog updates
The bot extracts article content and posts to the news webhook channel.
### 2.11 HTTP Server
The Application includes a minimal Express server (src/server/serve.ts:1):
**Endpoints:**
- `GET /` - Returns HTML landing page with project information
**Ports:**
- HTTP: 10080 (default)
- HTTPS: 10443 (when `NODE_ENV=production`)
Note: The server file includes a TODO comment suggesting deletion after Trello integration is complete.
### 2.12 Logging
The Application uses Winston for structured logging (src/utils/logHandler.ts:1):
**Log Levels:**
- `info`: General information (bot startup, scheduled task execution)
- `error`: Error conditions (API failures, Discord errors)
**Log Format:**
```
[TIMESTAMP] LEVEL: MESSAGE
```
**Log Destinations:**
- Console (stdout)
- Debug webhook (errors only)
### 2.13 Error Handling
All errors are caught and:
1. Logged to console via Winston
2. Sent to the debug webhook with error details
3. Presented to users with friendly messages (when applicable)
Example error flow (src/modules/checkAirtableRecords.ts):
```typescript
try {
// API call
} catch (error) {
logHandler.error("Error message", error);
debugHook.send({ content: "Error details" });
}
```
### 2.14 Performance Considerations
- **Message Caching**: Fetches messages in batches of 100 to reduce API calls
- **Duplicate Prevention**: Tracks latest Airtable record ID and news article ID
- **Rate Limiting**:
- Airtable: 60-minute polling interval
- News API: 10-minute polling interval
- **Concurrent Limits**: Artists/distributors limited to 2 active tasks each
### 2.15 Security Considerations
- **Environment Variables**: Sensitive tokens stored in `.env` (not committed)
- **Role Verification**: Commands require support role for execution (src/events/onMessageCreate.ts:1)
- **Webhook Validation**: Checks webhook existence before use (src/utils/isValidWebhook.ts:1)
- **Privileged Intents**: Requires approval from Discord for `MessageContent` intent
### 2.16 Troubleshooting
**Bot doesn't start:**
- Verify `TOKEN` is valid in `.env`
- Check Node.js version is 22
- Ensure all dependencies are installed: `pnpm install`
**Webhooks not working:**
- Verify webhook URLs are valid and accessible
- Check webhook permissions in Discord channel settings
- Use `isValidWebhook` utility for validation
**Airtable integration failing:**
- Verify `AIRTABLE_KEY`, `AIRTABLE_BASE_ID`, and `AIRTABLE_TABLE_ID`
- Check Airtable API permissions
- Review Airtable API rate limits
**Scheduled tasks not running:**
- Check server timezone matches expected cron schedule
- Review `onReady.ts` for cron expression syntax
- Check debug webhook for error messages
**Ticket logs not saving:**
- Verify write permissions for `logs/` directory
- Check disk space availability
- Review console for Winston logging errors
---
## 3. Legal Documentation
This section is for expansions to our legal policies specific to the Application.
### 3.1 Terms of Service
The Application is subject to our global Terms of Service, which can be found at:
https://docs.nhcarrigan.com/#/terms
### 3.2 Privacy Policy
The Application's privacy practices are governed by our global Privacy Policy, which can be found at:
https://docs.nhcarrigan.com/#/privacy
#### 3.2.1 Data Collection
The Application collects and temporarily stores the following data:
**Discord Data:**
- User IDs (for role assignment, moderation, and ticket management)
- Message content in ticket threads (logged to text files)
- Reaction events (for tracking commission/distribution claims)
- Member join events (for auto-role assignment)
**Airtable Data:**
- Form submission data (name, contact method, handle, art request details)
- Reference images (URLs only)
- Submission timestamps and record IDs
**Temporary Storage:**
- Ticket conversation logs (stored as text files, deleted after archival)
- In-memory cache for article IDs and ticket log mappings
**Data Retention:**
- Ticket logs: Deleted immediately after being sent to the archive channel
- Cached data: Cleared on bot restart
- Airtable record IDs: Stored in memory to prevent duplicate processing
**Third-Party Services:**
The Application integrates with:
- Discord (message delivery and bot functionality)
- Airtable (form submission retrieval)
- Al Jazeera (public news feed)
- Trello (configuration only, no active integration)
Users should review the privacy policies of these services for their data handling practices.
### 3.3 License
This software is licensed under our global software license:
https://docs.nhcarrigan.com/#/license
**Copyright:** Held by Naomi Carrigan
**License Type:** Proprietary (see link above for full terms)
### 3.4 Code of Conduct
All contributors and users must adhere to our Code of Conduct:
See: `CODE_OF_CONDUCT.md` in the repository root
### 3.5 Security Policy
Security vulnerabilities should be reported according to our Security Policy:
See: `SECURITY.md` in the repository root
For security concerns, please contact us through:
- Chat Server: http://chat.nhcarrigan.com
- Email: contact@nhcarrigan.com
### 3.6 Disclaimer
The Application is provided for the specific purpose of facilitating the Art for Palestine charity event. While we strive for reliability and accuracy, the Application is provided "as-is" without warranties of any kind.
**Moderation Actions:** The Application includes moderation features (mute/unmute). Server administrators and support team members are responsible for using these features in accordance with Discord's Terms of Service and Community Guidelines.
**External Content:** The Application fetches and displays news content from Al Jazeera. We do not control or endorse this content and are not responsible for its accuracy or appropriateness.
**Charity Event:** This Application is specifically designed for the Art for Palestine charity event. For questions about the event itself, please visit https://art4palestine.org or contact the event organizers.
---
## 4. Contributing Documentation
This section is for documentation related to contributing to the Application's codebase.
### 4.1 Contributing Guidelines
Our complete contributing guidelines can be found at:
https://docs.nhcarrigan.com/#/contributing
### 4.2 Getting Started with Development
1. **Fork the Repository**
```bash
# Visit GitHub and fork the repository to your account
```
2. **Clone Your Fork**
```bash
git clone https://github.com/YOUR_USERNAME/nodejs-typescript-template.git
cd nodejs-typescript-template
```
3. **Install Dependencies**
```bash
pnpm install
```
4. **Set Up Environment**
- Create a `.env` file (see section 2.3)
- Create a test Discord server and bot
- Configure test webhooks
5. **Create a Branch**
```bash
git checkout -b feature/your-feature-name
```
### 4.3 Code Style and Standards
The project enforces code style through automated tooling:
**ESLint Configuration:**
- Extends `@nhcarrigan/eslint-config`
- Maximum warnings allowed: 0 (all warnings treated as errors)
- Checks both `src/` and `test/` directories
**Prettier Configuration:**
- Extends `@nhcarrigan/prettier-config`
- Enforces consistent formatting
**TypeScript Configuration:**
- Extends `@nhcarrigan/typescript-config`
- Strict type checking enabled
- Root directory: `./src`
- Output directory: `./prod`
**Running Linters:**
```bash
pnpm lint
```
**Auto-Fixing Issues:**
```bash
# Fix ESLint issues
npx eslint src test --fix
# Fix Prettier issues
npx prettier src test --write
```
### 4.4 Writing Tests
The project uses Mocha and Chai for testing:
**Test Structure:**
- Test files: `test/**/*.spec.ts`
- Test style: TDD (Test-Driven Development)
- Timeout: 10 seconds per test
- Type: TypeScript (via ts-mocha)
**Running Tests:**
```bash
pnpm test
```
**Writing a Test:**
```typescript
import { expect } from "chai";
import { suite, test } from "mocha";
suite("Feature Name", () => {
test("should do something", () => {
// Arrange
const input = "test";
// Act
const result = myFunction(input);
// Assert
expect(result).to.equal("expected");
});
});
```
### 4.5 Documentation Standards
**JSDoc Comments:**
All functions, classes, and complex logic should include JSDoc comments:
```typescript
/**
* Brief description of the function.
*
* @param {Type} paramName - Parameter description
* @returns {Type} Return value description
*/
function myFunction(paramName: Type): Type {
// Implementation
}
```
**Inline Comments:**
Use inline comments for complex logic:
```typescript
// Explanation of why this approach is used
const result = complexOperation();
```
**Commit Messages:**
Follow conventional commit format:
- `feat: Add new feature`
- `fix: Resolve bug in ticket system`
- `docs: Update README`
- `chore: Update dependencies`
- `refactor: Restructure event handlers`
- `test: Add tests for webhook validation`
### 4.6 Pull Request Process
1. **Ensure All Checks Pass:**
- Run `pnpm lint` (must pass with 0 warnings)
- Run `pnpm test` (all tests must pass)
- Run `pnpm build` (must compile without errors)
2. **Create Pull Request:**
- Use a descriptive title
- Provide detailed description of changes
- Reference any related issues
- Include screenshots/videos for UI changes
3. **Code Review:**
- Address reviewer feedback
- Make requested changes
- Re-request review after updates
4. **Merge:**
- Maintainers will merge approved PRs
- Squash and merge is preferred for clean history
### 4.7 Areas for Contribution
The project welcomes contributions in these areas:
**Feature Enhancements:**
- Trello integration completion (see TODO in `src/server/serve.ts`)
- Database integration using Prisma (currently installed but unused)
- Additional moderation commands
- Enhanced reporting and analytics
**Bug Fixes:**
- Report bugs via GitHub Issues
- Include reproduction steps and environment details
- PRs to fix bugs are highly appreciated
**Documentation:**
- Improve code comments
- Expand user guides
- Add troubleshooting sections
- Create video tutorials
**Testing:**
- Increase test coverage
- Add integration tests
- Create test utilities
**Performance:**
- Optimize message caching
- Reduce webhook API calls
- Improve scheduled task efficiency
### 4.8 Development Environment Setup
**Recommended Tools:**
- **Editor:** VS Code (or any TypeScript-compatible editor)
- **Extensions:**
- ESLint
- Prettier
- TypeScript and JavaScript Language Features
- **Node Version Manager:** nvm (for managing Node.js versions)
- **Package Manager:** pnpm 10
**Discord Developer Portal Setup:**
1. Create a new application at https://discord.com/developers/applications
2. Create a bot user
3. Enable required privileged intents: `Message Content`, `Server Members`
4. Generate and save bot token
5. Invite bot to test server with required permissions
**Webhook Setup:**
1. Create test channels in your Discord server
2. Go to channel settings ā†’ Integrations ā†’ Webhooks
3. Create webhooks for: debug, comm, dist, news, ticket
4. Copy webhook URLs to `.env`
### 4.9 Debugging
**Console Logging:**
The project uses Winston for logging. To add debug logs:
```typescript
import { logHandler } from "./utils/logHandler.js";
logHandler.info("Informational message");
logHandler.error("Error message", error);
```
**Discord Debug Webhook:**
Error details are automatically sent to the debug webhook. Check this channel for runtime errors.
**VS Code Launch Configuration:**
Create `.vscode/launch.json`:
```json
{
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "launch",
"name": "Debug Bot",
"runtimeArgs": ["-r", "dotenv/config"],
"program": "${workspaceFolder}/prod/index.js",
"preLaunchTask": "npm: build",
"outFiles": ["${workspaceFolder}/prod/**/*.js"]
}
]
}
```
### 4.10 Common Development Tasks
**Adding a New Command:**
1. Add handler logic to `src/events/onMessageCreate.ts`
2. Implement command functionality in `src/modules/`
3. Update user documentation (section 1)
4. Add tests in `test/`
**Adding a New Button:**
1. Create button handler in `src/modules/buttons/`
2. Export handler in button module
3. Register handler in `src/events/onInteractionCreate.ts`
4. Update user documentation
**Adding a New Event Listener:**
1. Create event handler in `src/events/`
2. Register listener in `src/index.ts`
3. Add error handling
4. Update technical documentation
**Modifying Configuration:**
1. Update relevant file in `src/config/`
2. Document changes in section 2.4
3. Update environment variable documentation if needed
### 4.11 Release Process
(For maintainers)
1. **Version Bump:**
- Update version in `package.json`
- Follow semantic versioning (MAJOR.MINOR.PATCH)
2. **Changelog:**
- Document all changes since last release
- Include breaking changes, features, and bug fixes
3. **Testing:**
- Run full test suite
- Test in staging environment
- Verify all integrations work
4. **Deployment:**
- Build production bundle: `pnpm build`
- Deploy to production server
- Monitor logs for issues
5. **Tag Release:**
```bash
git tag -a v2.0.0 -m "Release version 2.0.0"
git push origin v2.0.0
```
### 4.12 Contact for Contributors
If you have questions about contributing:
- **GitHub Issues:** https://github.com/naomi-lgbt/nodejs-typescript-template/issues
- **Chat Server:** http://chat.nhcarrigan.com
- **Email:** contact@nhcarrigan.com
We review pull requests as soon as possible and appreciate all contributions to the project.
---
**Document Version:** 1.0.0
**Last Updated:** 2025-10-29
**Maintained By:** Naomi Carrigan
src/content/docs/projects/aeris.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Aeris
---
Aeris (hereinafter the "Application") is an authentication service featuring magic links and support for multiple social media platforms
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/projects/alouette.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Alouette
---
Alouette (hereinafter the "Application") is a web server that allows you to set up arbitrary webhooks and format them to post on Discord.
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/projects/amari.md
+441
View File
@@ -0,0 +1,441 @@
---
title: Amari
---
Amari (hereinafter the "Application") is Naomi's Virtual Personal Assistant on Discord, designed to automate community management, content aggregation, mentorship program coordination, and integration with external services such as GitHub, RetroAchievements, and Baserow.
## 1. User Documentation
This section is for those interacting with a live instance of the Application.
### 1.1 Interacting with Amari
#### 1.1.1 Direct Messages
When you send a Direct Message to Amari, the bot will automatically forward your message to Naomi and respond with an acknowledgment. This provides a direct communication channel to reach Naomi through the bot.
Implementation: `src/modules/respondToDm.ts:19`
#### 1.1.2 Mentions
Amari monitors messages in the Discord server for mentions of "Naomi" or "@NHCarrigan" (user or role). When detected, the bot forwards the message to Naomi for review, helping ensure important messages are not missed. To prevent spam, Amari will not forward mentions from channels that have been active in the last 10 minutes.
Implementation: `src/modules/respondToMention.ts:20`
### 1.2 Mentorship Program
#### 1.2.1 Joining the Program
When you receive the Mentorship role, Amari will automatically send a welcome message in the mentee chat channel with onboarding instructions, including:
- Accepting the GitHub repository invitation
- Reading the mentorship wiki
- Creating your initial goal post
Implementation: `src/modules/processMentorshipRole.ts:20`
#### 1.2.2 Forum Thread Management
Amari automatically manages thread tags in mentorship forums (Goals, Projects, Resume Reviews, and Discussions) to track whose turn it is to respond:
- When Naomi responds to your thread, the tag changes to "Waiting on Member"
- When you respond, the tag changes to "Waiting on Naomi"
Implementation: `src/modules/updateMentorshipThread.ts:43`
#### 1.2.3 Progress Reminders
Every weekday (Monday-Friday) at 9:00 AM, Amari posts progress reminders in configured channels. These reminders prompt you to share:
1. What you accomplished yesterday
2. What you're working on today
3. Any blockers or issues you need help with
Implementation: `src/modules/postProgressReminders.ts:16`
### 1.3 Content and News
#### 1.3.1 Tech News Feed
Amari automatically posts new articles from two sources every hour:
- **FreeCodeCamp News**: Articles are filtered for inappropriate content before posting
- **Hacker News**: Latest posts with comment links
Implementation: `src/modules/postNews.ts:40` and `src/modules/postNews.ts:95`
#### 1.3.2 RetroAchievements
If Naomi unlocks any RetroAchievements, Amari posts them to the gaming channel every 10 minutes. These posts include:
- Achievement title and description
- Game title and console
- Point value
- Badge images
Implementation: `src/modules/checkAchievements.ts:87`
### 1.4 Form Submissions
When you submit a form through the Baserow system, Amari posts a notification to the form submissions channel. Supported forms include:
- Sanction Appeals
- Commission Requests
- Contact Requests
- Event Requests
- Meeting Requests
- Mentorship Requests
- Staff Applications
- Testimonials
- ASCII Submissions
- Contributor Applications
- Guild Wars Officer/Leader Applications
- Product and Community Feedback
- Community Nominations
Implementation: `src/modules/processFormSubmission.ts:22` and `src/config/forms.ts:9`
## 2. Technical Documentation
This section is for those interested in running their own instance of the Application.
### 2.1 Prerequisites
- Node.js (compatible with the version specified in package.json)
- pnpm 10.15.0 or higher
- A Discord Bot Token
- GitHub App credentials (Client ID and Private Key)
- RetroAchievements API Key (optional, for achievements feature)
- Baserow webhook secret (optional, for form submissions)
### 2.2 Environment Variables
The following environment variables must be configured:
| Variable | Required | Description |
|----------|----------|-------------|
| `BOT_TOKEN` | Yes | Discord bot token |
| `GH_CLIENT_ID` | Yes | GitHub App client ID |
| `GH_PRIVATE_KEY` | Yes | GitHub App private key (with newlines as `\\n`) |
| `GH_WEBHOOK_SECRET` | No | Secret for validating GitHub webhook payloads |
| `RA_KEY` | No | RetroAchievements API key |
| `BASEROW_SECRET` | No | Secret for validating Baserow webhook payloads |
### 2.3 Installation
1. Clone the repository
2. Install dependencies:
```bash
pnpm install
```
3. Build the TypeScript code:
```bash
pnpm run build
```
4. Configure environment variables (see section 2.2)
5. Start the application:
```bash
pnpm start
```
Implementation: `src/index.ts:1`
### 2.4 Configuration
#### 2.4.1 Discord IDs
All Discord-specific IDs (channels, roles, users, guilds, tags) are configured in `src/config/ids.ts`. You will need to update these IDs to match your Discord server setup:
- **Channels**: Form submissions, gaming, general, mentee chat, forums, news
- **Roles**: Mentorship, nhcarrigan, representing
- **Users**: Amari (bot), Naomi, nhcarrigan
- **Tags**: Forum tags for tracking thread status
Implementation: `src/config/ids.ts:7`
#### 2.4.2 Form IDs
Form submission notifications are configured in `src/config/forms.ts`. Map Baserow table IDs to human-readable form names.
Implementation: `src/config/forms.ts:9`
#### 2.4.3 Progress Reminders
Progress reminder channels are configured in `src/config/progressReminders.ts`. Configure which channels should receive reminders, associated role IDs, and whether to create threads.
Implementation: `src/config/progressReminders.ts:1`
#### 2.4.4 DM Response
The automatic response sent when users DM the bot is configured in `src/config/responses.ts`.
Implementation: `src/config/responses.ts:1`
### 2.5 Architecture
#### 2.5.1 Core Components
The Application consists of several key components:
1. **Discord Bot** (`discord.js`): Handles all Discord interactions
2. **GitHub Integration** (`octokit`): Manages GitHub webhooks and API interactions
3. **Web Server** (`fastify`): Receives webhooks and serves health monitoring page
4. **Scheduled Jobs** (`node-schedule`): Executes periodic tasks (news, reminders, etc.)
5. **Analytics** (`@nhcarrigan/discord-analytics`): Tracks bot usage metrics
Main entry point: `src/index.ts:1`
#### 2.5.2 Event Handlers
The bot responds to the following Discord events:
- `ClientReady`: Initialize scheduled jobs and cache data (src/index.ts:65)
- `MessageCreate`: Handle guild messages and DMs (src/index.ts:89)
- `InteractionCreate`: Handle button interactions (src/index.ts:97)
- `UserUpdate`: Process guild tag changes (src/index.ts:117)
- `GuildMemberUpdate`: Process mentorship role assignments (src/index.ts:121)
- `GuildMemberAdd`: Log when mentees join (src/index.ts:125)
- `GuildMemberRemove`: Log when mentees leave (src/index.ts:129)
#### 2.5.3 Scheduled Tasks
The following tasks run on a schedule:
- **Hourly** (0 * * * *): Post news from FreeCodeCamp and Hacker News
- **Daily at Midnight** (0 0 * * *): Audit and cache guild tags
- **Weekdays at 9 AM** (0 9 * * 1-5): Post progress reminders
- **Every 10 minutes** (interval): Check RetroAchievements and clear recently active channels
Implementation: `src/index.ts:70-86`
#### 2.5.4 Web Server Endpoints
The Fastify web server provides the following endpoints:
- `GET /`: Health monitoring page with bot information
- `POST /github`: Webhook endpoint for GitHub events (issues, pull requests)
- `POST /form`: Webhook endpoint for Baserow form submissions
The server listens on port 7044.
Implementation: `src/server/serve.ts:61`
### 2.6 Content Filtering
FreeCodeCamp News posts are filtered for inappropriate content using a comprehensive regular expression that detects violations of the Code of Conduct. The regex is defined in `src/modules/postNews.ts:23` and checks for:
- Harassment, bullying, and discrimination
- Hate speech and slurs
- Explicit, violent, or illegal content
- Spam, scams, and fraud
- Drug-related content
- Violence and illegal activities
Posts matching these patterns are automatically rejected and not posted to Discord.
### 2.7 GitHub Integration
When GitHub webhooks are received:
1. **New Issues** (`opened` action): Amari automatically assigns Naomi to the issue
2. **New Pull Requests** (`opened` action): Amari automatically requests Naomi as a reviewer
Implementation: `src/modules/processGitHubEvent.ts:31`
### 2.8 Development
#### 2.8.1 Available Scripts
- `pnpm run build`: Compile TypeScript to JavaScript
- `pnpm start`: Start the production server (uses 1Password for environment variables)
- `pnpm run lint`: Run ESLint with zero warnings policy
- `pnpm test`: Run tests (currently placeholder)
#### 2.8.2 Code Structure
```
src/
ā”œā”€ā”€ config/ # Configuration files (IDs, forms, responses, reminders)
ā”œā”€ā”€ events/ # Discord event handlers
ā”œā”€ā”€ interfaces/ # TypeScript interfaces
ā”œā”€ā”€ modules/ # Core functionality modules
ā”œā”€ā”€ server/ # Fastify web server
ā”œā”€ā”€ utils/ # Utility functions
ā””ā”€ā”€ index.ts # Application entry point
```
#### 2.8.3 Dependencies
Key dependencies:
- `discord.js` v14.22.0: Discord API wrapper
- `fastify` v5.5.0: Web server framework
- `octokit` v5.0.3: GitHub API client
- `node-schedule` v2.1.1: Cron job scheduler
- `rss-parser` v3.13.0: RSS feed parser
- `@retroachievements/api` v2.6.0: RetroAchievements API client
- `@nhcarrigan/discord-analytics` v0.0.6: Analytics tracking
- `@nhcarrigan/logger` v1.1.1: Logging utility
## 3. Legal Documentation
This section is for expansions to our legal policies specific to the Application.
### 3.1 License
This software is licensed under Naomi's Public License. The full license text is available in the `LICENSE.md` file in the repository root.
Copyright held by Naomi Carrigan.
### 3.2 Code of Conduct
All users interacting with the Application, whether through Discord or by contributing to the codebase, must adhere to the Code of Conduct defined in `CODE_OF_CONDUCT.md`.
### 3.3 Content Filtering
The Application implements automated content filtering for RSS feeds to ensure posted content complies with the community's Code of Conduct. While this filtering attempts to catch policy violations, it may not be perfect. Users should report any inappropriate content that bypasses the filters.
### 3.4 Data Collection
The Application collects the following data for operational purposes:
- Discord user IDs and message content (forwarded to Naomi for mentions/DMs)
- GitHub usernames (for webhook processing)
- Form submission data (row IDs and table identifiers)
- Analytics metrics (event counts and associated metadata)
All data is processed in accordance with Naomi's privacy policies.
### 3.5 Third-Party Services
The Application integrates with several third-party services:
- **Discord**: Communication platform (Terms of Service apply)
- **GitHub**: Code hosting and webhook integration (Terms of Service apply)
- **RetroAchievements**: Gaming achievement tracking (Terms of Service apply)
- **Baserow**: Form submission processing (Terms of Service apply)
Users of the Application are subject to the terms of service of these platforms.
## 4. Contributing Documentation
This section is for documentation related to contributing to the Application's codebase.
### 4.1 Getting Started
Before contributing, please:
1. Read the `CONTRIBUTING.md` file for contribution guidelines
2. Review the `CODE_OF_CONDUCT.md` to understand community standards
3. Familiarize yourself with the codebase structure (see section 2.8.2)
### 4.2 Development Setup
1. Fork the repository
2. Clone your fork locally
3. Install dependencies: `pnpm install`
4. Create a feature branch: `git checkout -b feature/your-feature-name`
5. Make your changes
6. Run linting: `pnpm run lint`
7. Build the project: `pnpm run build`
8. Test your changes with a local instance
### 4.3 Code Standards
The project enforces the following standards:
- **TypeScript**: All code must be written in TypeScript
- **ESLint**: Code must pass linting with zero warnings (`@nhcarrigan/eslint-config`)
- **TypeScript Config**: Uses `@nhcarrigan/typescript-config`
- **File Headers**: All files must include copyright header with license and author information
Example header:
```typescript
/**
* @copyright NHCarrigan
* @license Naomi's Public License
* @author Naomi Carrigan
*/
```
### 4.4 Module Guidelines
When creating or modifying modules:
1. **Single Responsibility**: Each module should handle one specific feature
2. **Error Handling**: Use try-catch blocks and log errors with the logger utility
3. **Type Safety**: Define interfaces for all data structures
4. **Documentation**: Include JSDoc comments for all exported functions
5. **Testing**: Consider how your changes can be tested (when tests are implemented)
### 4.5 Adding New Features
When adding new features:
1. **Configuration**: Add any new IDs or configuration to appropriate config files
2. **Interfaces**: Define TypeScript interfaces in the `src/interfaces/` directory
3. **Modules**: Create new modules in `src/modules/` for self-contained functionality
4. **Events**: Add event handlers in `src/events/` if needed
5. **Server Routes**: Add new endpoints in `src/server/serve.ts` if needed
6. **Documentation**: Update this documentation file to reflect new features
### 4.6 Submitting Changes
1. Commit your changes with descriptive commit messages
2. Push to your fork
3. Create a Pull Request to the main repository
4. Amari will automatically request Naomi as a reviewer
5. Address any review feedback
6. Once approved, your changes will be merged
### 4.7 Key Files for Contributors
- `src/index.ts`: Main application entry point
- `src/config/ids.ts`: Discord server IDs configuration
- `src/interfaces/amari.ts`: Core application state interface
- `src/server/serve.ts`: Web server and webhook handlers
- `src/modules/`: Individual feature implementations
- `package.json`: Dependencies and scripts
### 4.8 Common Tasks
#### Adding a New Form Type
1. Add the table ID and name to `src/config/forms.ts`
2. The form notification will automatically work via `src/modules/processFormSubmission.ts`
#### Adding a New Scheduled Task
1. Add the schedule in `src/index.ts` within the `ClientReady` event handler
2. Use `node-schedule` cron syntax
3. Create a new module in `src/modules/` for the task logic
#### Adding a New Discord Event Handler
1. Create a handler module in `src/modules/` or `src/events/`
2. Register the event listener in `src/index.ts`
3. Use the `Amari` interface for accessing bot state
#### Modifying Webhook Endpoints
1. Update the route handler in `src/server/serve.ts`
2. Define interfaces for payloads in `src/interfaces/`
3. Ensure proper authentication checking with secrets
### 4.9 Support and Questions
If you have questions about contributing:
- Open a GitHub issue for bugs or feature requests
- Join the Discord server at https://chat.nhcarrigan.com for discussions
- Email contact@nhcarrigan.com for private inquiries
### 4.10 Analytics and Logging
The Application uses custom logging and analytics:
- **Logger**: Use `logger.log()`, `logger.error()`, `logger.metric()` from `src/utils/logger.ts`
- **Metrics**: Log user actions with `logger.metric()` for analytics tracking
- **Error Handling**: Always catch and log errors to help with debugging
Example:
```typescript
await logger.metric("processed_event", 1, { user: userId });
await logger.error("module name", error);
```
src/content/docs/projects/amirei.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Amirei
---
Amirei (hereinafter the "Application") is a quick social link aggregator for 'link in bio' pages.
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/projects/aurelia.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Aurelia
---
Aurelia (hereinafter the "Application") is a blogging platform with markdown editor
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/projects/aureline.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Aureline
---
Aureline (hereinafter the "Application") is a web app that allows you to create/upload digital badges and certifications and grant them to users
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/projects/beccalia-origins.md
+95
View File
@@ -0,0 +1,95 @@
---
title: "Beccalia: Origins"
---
Beccalia: Origins (hereinafter the "Game") is originally planned as the story of Becca and Rosalia growing up, this game was only released as a demo.
## 1. Player Documentation
This section is for players who are exploring or playing the Game.
### Controls
- **Keyboard / Gamepad:**
- Arrow keys / D-Pad: Move character
- Z / Enter / A: Confirm / Interact
- X / Esc / B: Cancel / Menu
- C / Space / Y: Open menu (if applicable)
- Shift / L / R: Dash (if enabled)
- **Touch UI (Mobile / Tablet):**
- Tap to move or interact
- On-screen buttons for menu and actions
### Troubleshooting
- Ensure your device meets RPG Maker MZ requirements.
- If the game crashes, try restarting the app or clearing temporary files.
- Ask us on discord if persistent issues occur.
---
## 2. Developer Documentation
This section is for those interested in running, modifying, or extending the Game.
### Engine & Dependencies
- **Engine:** RPG Maker MZ
- **Plugins Used:** none
- **Assets:** All original
### Setup Instructions
1. Open RPG Maker MZ.
2. Load the project folder `beccalia-origins`.
3. Use the "Playtest" button to run the Game locally.
4. To export, use the "Deployment" feature for target platforms.
### Directory Structure
- `data/` ā€” database files (maps, events, actors, items, skills, etc.)
- `img/` ā€” graphics (characters, tilesets, animations, pictures, etc.)
- `audio/` ā€” music and sound effects
- `js/` ā€” plugins and core scripts
- `www/` ā€” exported HTML5 build (if deployed for web)
---
## 3. Legal Documentation
This section expands on legal or licensing information specific to the Game.
### Licensing
This Game is created using RPG Maker MZ. The game code and original content are the property of NHCarrigan. RPG Maker MZ runtime assets are licensed under the terms provided by KADOKAWA Corporation. All original graphics, music, and story content belong to NHCarrigan and are protected by copyright.
### Third-Party Notices
- Any third-party assets, music, or plugins included are credited in game.
## 4. Contributing Documentation
This section is for contributors or collaborators on the Game.
### How to Contribute
- Fork or copy the project folder.
- Submit patches or mods via Git.
- Include a changelog and clear notes on modifications.
### Coding Standards
- Plugins in `js/plugins/` should follow standard JS conventions.
- Comment custom scripts clearly for readability.
### Art & Audio Guidelines
- Maintain original resolutions where possible (48x48 tiles, etc.).
- Use consistent naming for files in `img/` and `audio/`.
### Contact
- For collaboration or questions, ask us on discord.
src/content/docs/projects/beccalia-prologue.md
+95
View File
@@ -0,0 +1,95 @@
---
title: "Beccalia: Prologue"
---
Beccalia: Prologue (hereinafter the "Game") is an introductory story that sets the stage for the Beccalia universe, featuring Becca and Rosalia.
## 1. Player Documentation
This section is for players who are exploring or playing the Game.
### Controls
- **Keyboard / Gamepad:**
- Arrow keys / D-Pad: Move character
- Z / Enter / A: Confirm / Interact
- X / Esc / B: Cancel / Menu
- C / Space / Y: Open menu (if applicable)
- Shift / L / R: Dash (if enabled)
- **Touch UI (Mobile / Tablet):**
- Tap to move or interact
- On-screen buttons for menu and actions
### Troubleshooting
- Ensure your device meets RPG Maker MZ requirements.
- If the game crashes, try restarting the app or clearing temporary files.
- Ask us on discord if persistent issues occur.
---
## 2. Developer Documentation
This section is for those interested in running, modifying, or extending the Game.
### Engine & Dependencies
- **Engine:** RPG Maker MZ
- **Plugins Used:** none
- **Assets:** All original
### Setup Instructions
1. Open RPG Maker MZ.
2. Load the project folder `beccalia-prologue`.
3. Use the "Playtest" button to run the Game locally.
4. To export, use the "Deployment" feature for target platforms.
### Directory Structure
- `data/` ā€” database files (maps, events, actors, items, skills, etc.)
- `img/` ā€” graphics (characters, tilesets, animations, pictures, etc.)
- `audio/` ā€” music and sound effects
- `js/` ā€” plugins and core scripts
- `www/` ā€” exported HTML5 build (if deployed for web)
---
## 3. Legal Documentation
This section expands on legal or licensing information specific to the Game.
### Licensing
This Game is created using RPG Maker MZ. The game code and original content are the property of NHCarrigan. RPG Maker MZ runtime assets are licensed under the terms provided by KADOKAWA Corporation. All original graphics, music, and story content belong to NHCarrigan and are protected by copyright.
### Third-Party Notices
- Any third-party assets, music, or plugins included are credited in game.
## 4. Contributing Documentation
This section is for contributors or collaborators on the Game.
### How to Contribute
- Fork or copy the project folder.
- Submit patches or mods via Git.
- Include a changelog and clear notes on modifications.
### Coding Standards
- Plugins in `js/plugins/` should follow standard JS conventions.
- Comment custom scripts clearly for readability.
### Art & Audio Guidelines
- Maintain original resolutions where possible (48x48 tiles, etc.).
- Use consistent naming for files in `img/` and `audio/`.
### Contact
- For collaboration or questions, ask us on discord.
src/content/docs/projects/boost-monitor.md
+293
View File
@@ -0,0 +1,293 @@
---
title: Boost Monitor
---
Boost Monitor (hereinafter the "Application") is a Discord bot that automatically manages special roles for server boosters. The Application monitors server members and removes booster-exclusive roles (such as custom color roles) when a member stops boosting the server.
## 1. User Documentation
This section is for those interacting with a live instance of the Application.
### Overview
The Discord Boost Monitor operates automatically in the background of your Discord server. It requires no direct user interaction once configured by server administrators.
### How It Works
1. **Automatic Monitoring**: The bot monitors all member updates in the Discord server
2. **Boost Detection**: When a member's boost status changes, the bot checks if they still have the server booster role
3. **Role Management**: If a member no longer has the booster role, the bot automatically removes any configured booster-exclusive roles (such as custom color roles)
### Key Features
- **Automated Role Removal**: No manual intervention needed when members stop boosting
- **Configurable Roles**: Server-specific booster and color role IDs can be configured
- **Status Monitoring**: Health check endpoint available at the bot's web interface
- **Debug Webhooks**: Sends status updates and error reports to configured Discord webhooks
### Accessing the Bot
The bot runs as a background service and does not have traditional user-facing commands. Server administrators can monitor its status through:
- **Web Interface**: HTTPS endpoint showing bot status and information
- **Debug Webhook**: Real-time updates sent to configured Discord webhook
- **Server Logs**: Winston-based logging for troubleshooting
## 2. Technical Documentation
This section is for those interested in running their own instance of the Application.
### Prerequisites
- **Node.js**: Version 22 or higher
- **pnpm**: Version 9 or higher
- **Discord Bot Token**: From the Discord Developer Portal
- **SSL Certificates**: For HTTPS server (Let's Encrypt or similar)
- **Sentry Account** (optional): For error tracking
### Installation
1. Clone the repository:
```bash
git clone https://github.com/nhcarrigan/oogie-woogie-boostie-woostie.git
cd oogie-woogie-boostie-woostie
```
2. Install dependencies:
```bash
pnpm install
```
3. Configure environment variables by creating a `.env` file:
```bash
cp sample.env .env
```
4. Edit `.env` with your configuration:
```env
DISCORD_TOKEN="your-discord-bot-token"
SENTRY_DSN="your-sentry-dsn"
DEBUG_HOOK="your-discord-webhook-url"
```
### Configuration
#### Role Configuration
Edit `src/config/roles.ts` to configure your server-specific role IDs:
- **colourRoles**: Array of role IDs that should be removed when a member stops boosting (src/config/roles.ts:1-10)
- **boosterRole**: The ID of your server's booster role (src/config/roles.ts:12)
Example:
```typescript
export const colourRoles = [
"883281643098484736", // Red role
"883283836887261204", // Blue role
// Add your color role IDs here
];
export const boosterRole = "712431541531181177"; // Your booster role ID
```
#### SSL Certificates
The bot expects SSL certificates at the following locations:
- Certificate: `/etc/letsencrypt/live/oogie.nhcarrigan.com/cert.pem`
- Private Key: `/etc/letsencrypt/live/oogie.nhcarrigan.com/privkey.pem`
Update the paths in `src/server/serve.ts:18-22` if your certificates are located elsewhere.
### Building and Running
1. Build the TypeScript code:
```bash
pnpm build
```
2. Start the bot:
```bash
pnpm start
```
3. For development with linting:
```bash
pnpm lint
```
### Architecture
#### Core Components
- **Main Entry Point** (`src/index.ts`): Initializes the Discord client, sets up event listeners, and starts the web server
- **Role Manager** (`src/modules/manageRoles.ts`): Core logic for detecting boost status and removing roles
- **Web Server** (`src/server/serve.ts`): Fastify-based HTTPS server for health monitoring
- **Error Handler** (`src/utils/errorHandler.ts`): Centralized error handling with Sentry integration and Discord webhook notifications
- **Log Handler** (`src/utils/logHandler.ts`): Winston-based logging with timestamps and color coding
#### Bot Intents
The bot requires the following Discord gateway intents (src/index.ts:22):
- `Guilds`: Access to guild information
- `GuildMembers`: Access to member updates (privileged intent)
Note: The `GuildMembers` intent must be enabled in your bot's Discord Developer Portal settings.
#### Event Flow
1. Bot connects to Discord and fetches guild members (src/index.ts:25-39)
2. Bot listens for `guildMemberUpdate` events (src/index.ts:42-44)
3. On member update, `manageRoles` function checks boost status (src/modules/manageRoles.ts:13-26)
4. If member is not boosting, configured color roles are removed
5. Errors are logged and sent to Sentry and debug webhook
#### Web Server
The Fastify server runs on port 3443 with HTTPS and provides:
- Health check endpoint at `/` (src/server/serve.ts:27-66)
- Simple HTML page with bot information and links
- Status notifications sent to debug webhook on startup
### Monitoring and Debugging
#### Sentry Integration
All errors are automatically captured and sent to Sentry (src/index.ts:9-17), providing:
- Stack trace rewriting for better debugging
- Full error context and stack traces
- 100% transaction sampling rate
#### Discord Webhooks
Debug webhooks are used for:
- Bot startup confirmation (src/index.ts:26-31)
- Member count logging (src/index.ts:35-39)
- Server startup notification (src/server/serve.ts:73-80)
- Error notifications with embeds (src/utils/errorHandler.ts:22-38)
#### Logging
Winston logger provides console output with:
- Timestamps in `YYYY-MM-DD HH:mm:ss` format
- Color-coded log levels
- NPM-style log levels (silly, verbose, info, warn, error)
### Deployment Considerations
1. **Privileged Intents**: Ensure `GuildMembers` intent is enabled in Discord Developer Portal
2. **SSL Certificates**: Keep certificates up-to-date (consider using certbot for Let's Encrypt)
3. **Environment Variables**: Secure your `.env` file and never commit it to version control
4. **Port Access**: Ensure port 3443 is accessible for health monitoring
5. **Process Management**: Consider using PM2 or systemd for process management
6. **Single Guild**: Bot is designed for single-guild operation (src/index.ts:33)
## 3. Legal Documentation
This section is for expansions to our legal policies specific to the Application.
### Software License
This Application is licensed under the global software license maintained by Naomi Carrigan. Full license details can be found at: https://docs.nhcarrigan.com/#/license
Copyright is held by Naomi Carrigan.
### Privacy Considerations
The Application processes the following Discord data:
- **Guild member information**: Required for detecting boost status changes
- **Role information**: Required for managing booster-exclusive roles
- **Member update events**: Monitored to detect boost status changes
This data is processed in real-time and is not permanently stored by the Application outside of:
- Error logs sent to Sentry
- Debug messages sent to Discord webhooks
- Console logs from Winston logger
For full privacy policy details, see: PRIVACY.md
### Terms of Service
The Application operates as an automated moderation tool for Discord servers. Server administrators are responsible for:
- Configuring appropriate role IDs
- Informing server members about automated role management
- Ensuring compliance with Discord's Terms of Service
For full terms of service, see: TERMS.md
### Security Policy
Security vulnerabilities should be reported according to the guidelines in: SECURITY.md
## 4. Contributing Documentation
This section is for documentation related to contributing to the Application's codebase.
### Getting Started
Full contributing guidelines are available at: https://docs.nhcarrigan.com/#/contributing
### Development Setup
1. Fork and clone the repository
2. Install dependencies with `pnpm install`
3. Create a `.env` file from `sample.env`
4. Make your changes in a feature branch
5. Run linting with `pnpm lint` before committing
6. Build the project with `pnpm build` to ensure TypeScript compiles
### Code Style
The project uses:
- **ESLint**: `@nhcarrigan/eslint-config` (max 0 warnings)
- **Prettier**: `@nhcarrigan/prettier-config`
- **TypeScript**: `@nhcarrigan/typescript-config`
Run `pnpm lint` to check code style before submitting PRs.
### Project Structure
```
src/
ā”œā”€ā”€ index.ts # Main entry point
ā”œā”€ā”€ config/
ā”‚ ā””ā”€ā”€ roles.ts # Role ID configuration
ā”œā”€ā”€ modules/
ā”‚ ā””ā”€ā”€ manageRoles.ts # Core role management logic
ā”œā”€ā”€ server/
ā”‚ ā””ā”€ā”€ serve.ts # Fastify web server
ā””ā”€ā”€ utils/
ā”œā”€ā”€ errorHandler.ts # Centralized error handling
ā””ā”€ā”€ logHandler.ts # Winston logging configuration
```
### Testing
Currently, the project does not have automated tests (package.json:11). When contributing new features, consider:
- Manual testing with a test Discord server
- Verifying role removal works correctly
- Testing error handling paths
- Checking webhook notifications
### Submitting Changes
1. Ensure code passes linting: `pnpm lint`
2. Build successfully: `pnpm build`
3. Review the Code of Conduct: CODE_OF_CONDUCT.md
4. Submit a Pull Request with:
- Clear description of changes
- Rationale for the changes
- Any testing performed
### Code of Conduct
All contributors must adhere to the Code of Conduct outlined in: CODE_OF_CONDUCT.md
### Reporting Issues
Bug reports and feature requests can be submitted at: https://github.com/nhcarrigan/oogie-woogie-boostie-woostie/issues
### Contact
For questions or support:
- **Chat Server**: http://chat.nhcarrigan.com
- **Email**: contact@nhcarrigan.com
src/content/docs/projects/calenelle.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Calenelle
---
Calenelle (hereinafter the "Application") is a group coordination app with event scheduling and such.
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/projects/clarion.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Clarion
---
Clarion (hereinafter the "Application") is a Discord bot with dashboard that allows server mangers to post and edit announcements, rules, and similar.
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/projects/data-api.md
+662
View File
@@ -0,0 +1,662 @@
---
title: Data API
---
Data API (hereinafter the "Application") is a lightweight web API server designed to host and serve personal and professional data for the NHCarrigan ecosystem. The Application acts as a centralized headless CMS, providing structured data in both YAML and JSON formats to power multiple websites, applications, and Discord bots.
## 1. User Documentation
This section is for those interacting with a live instance of the Application.
### 1.1 API Overview
The Data Server provides a RESTful API that serves various categories of data through simple HTTP GET requests. All endpoints support both YAML and JSON formats.
**Base URL**: The server runs on `https://data.nhcarrigan.com'.
**Root Endpoint**:
- `GET /` - Returns a welcome message: "Welcome to the NHCarrigan Data API!"
### 1.2 Available Endpoints
All data endpoints are available in two formats by changing the file extension:
#### Projects Data
- `GET /projects.json` - Returns project portfolio data in JSON format
- `GET /projects.yml` - Returns project portfolio data in YAML format
Contains information about development projects including:
- Project names and descriptions
- Project URLs and repository links
- Project categories (websites, community tools, Discord bots, etc.)
- Avatar images
- Status indicators (premium, work-in-progress)
#### Resume Data
- `GET /resume.json` - Returns resume data in JSON format
- `GET /resume.yml` - Returns resume data in YAML format
Contains comprehensive professional information:
- Employment history (current and prior positions)
- Volunteer experience
- Education credentials
- Professional certifications
- Notable projects
- Publications and articles
#### Testimonials
- `GET /testimonials.json` - Returns testimonials in JSON format
- `GET /testimonials.yml` - Returns testimonials in YAML format
Contains professional testimonials and recommendations with:
- Testimonial author names
- Testimonial content
- Date information
#### Donation Information
- `GET /donate.json` - Returns donation platform data in JSON format
- `GET /donate.yml` - Returns donation platform data in YAML format
Contains details about donation platforms:
- Platform names and URLs
- Icon references
- Color schemes
- Platform descriptions
#### Funding Information
- `GET /funding.json` - Returns comprehensive funding data in JSON format
- `GET /funding.yml` - Returns comprehensive funding data in YAML format
Contains detailed funding information:
- Entity details
- Project listings with unique identifiers
- Funding channel information
- Subscription plan details
- Financial history and records
### 1.3 CORS Support
The Application has CORS enabled for all origins, allowing consumption from any domain without cross-origin restrictions.
### 1.4 Content Types
The Application automatically sets appropriate Content-Type headers:
- JSON endpoints: `application/json`
- YAML endpoints: `text/yaml` or `application/x-yaml`
### 1.5 Rate Limiting
Currently, the Application does not implement rate limiting. Users should be respectful of the server resources and avoid excessive requests.
### 1.6 Data Freshness
Data is compiled from YAML source files during the build process. To receive updated data, the server must be rebuilt and restarted when source data changes.
## 2. Technical Documentation
This section is for those interested in running their own instance of the Application.
### 2.1 Prerequisites
Before running the Application, ensure you have the following installed:
- **Node.js**: Latest LTS version recommended
- **pnpm**: Version 10.17.0 (specified in package.json as packageManager)
- **1Password CLI** (optional): For secure environment variable management in production
### 2.2 Technology Stack
- **Runtime**: Node.js with ES modules
- **Language**: TypeScript 5.9.2
- **Web Framework**: Fastify 5.6.1
- **Data Format**: YAML (source) ā†’ JSON (runtime)
- **Testing**: Vitest 3.2.4
- **Linting**: ESLint 9.36.0
- **Package Manager**: pnpm 10.17.0
### 2.3 Installation
1. Clone the repository:
```bash
git clone <repository-url>
cd data
```
2. Install dependencies using pnpm:
```bash
pnpm install
```
### 2.4 Project Structure
```
/data/
ā”œā”€ā”€ src/ # TypeScript source code
ā”‚ ā”œā”€ā”€ index.ts # Main entry point - Fastify server
ā”‚ ā”œā”€ā”€ modules/
ā”‚ ā”‚ ā””ā”€ā”€ buildRoutes.ts # Dynamic route builder
ā”‚ ā”œā”€ā”€ interfaces/ # TypeScript type definitions
ā”‚ ā”‚ ā”œā”€ā”€ projects.ts
ā”‚ ā”‚ ā”œā”€ā”€ resume.ts
ā”‚ ā”‚ ā”œā”€ā”€ testimonials.ts
ā”‚ ā”‚ ā”œā”€ā”€ donate.ts
ā”‚ ā”‚ ā””ā”€ā”€ funding.ts
ā”‚ ā””ā”€ā”€ utils/
ā”‚ ā””ā”€ā”€ logger.ts # Logger configuration
ā”œā”€ā”€ data/ # Data directory (YAML sources and JSON builds)
ā”‚ ā”œā”€ā”€ projects.yml / .json
ā”‚ ā”œā”€ā”€ resume.yml / .json
ā”‚ ā”œā”€ā”€ testimonials.yml / .json
ā”‚ ā”œā”€ā”€ donate.yml / .json
ā”‚ ā””ā”€ā”€ funding.yml / .json
ā”œā”€ā”€ test/
ā”‚ ā””ā”€ā”€ yaml.spec.ts # Comprehensive validation tests
ā”œā”€ā”€ prod/ # Compiled JavaScript output
ā”œā”€ā”€ build.js # YAML to JSON build script
ā”œā”€ā”€ tsconfig.json # TypeScript configuration
ā””ā”€ā”€ package.json # Project metadata and scripts
```
### 2.5 Configuration
The Application uses the following configuration points:
#### Server Port
- Default: Port 9999
- Location: `src/index.ts:34`
- Can be modified by editing the port number in the source code
#### Data Directory
- Location: `./data`
- Contains both source YAML files and built JSON files
- Referenced in: `src/modules/buildRoutes.ts`
#### CORS Settings
- Currently configured to allow all origins
- Location: `src/index.ts:30`
- Can be restricted by modifying the Fastify CORS configuration
### 2.6 Data Management
#### Adding New Data Endpoints
1. Create a new YAML file in the `/data` directory:
```bash
touch data/newdata.yml
```
2. Create a corresponding TypeScript interface in `src/interfaces/`:
```typescript
// src/interfaces/newdata.ts
export interface NewData {
// Define your data structure
}
```
3. The Application will automatically:
- Generate routes for `/newdata.yml` and `/newdata.json`
- Serve the content when the server restarts
#### Editing Existing Data
1. Edit the YAML files in the `/data` directory
2. Run the build command to convert YAML to JSON
3. Restart the server to serve updated data
The YAML files are the source of truth. Always edit YAML files, not JSON files, as JSON files are auto-generated.
### 2.7 Build Process
The build process consists of two steps:
1. **YAML to JSON Conversion**: `node build.js`
- Reads all YAML files from the data directory
- Generates corresponding JSON files
- Preserves the human-readable YAML as the source of truth
2. **TypeScript Compilation**: `tsc`
- Compiles TypeScript source code to JavaScript
- Outputs to the `/prod` directory
- Uses configuration from `tsconfig.json` (extends @nhcarrigan/typescript-config)
To run the complete build:
```bash
pnpm run build
```
### 2.8 Available Scripts
```bash
# Build (YAML ā†’ JSON + TypeScript compilation)
pnpm run build
# Start production server (with 1Password environment variables)
pnpm run start
# Run test suite
pnpm test
# Linting
pnpm run lint # Run all linters
pnpm run lint:ts # ESLint only
pnpm run lint:spelling # Spell check YAML files
pnpm run lint:yaml # YAML validation
```
### 2.9 Testing
The Application includes comprehensive test coverage using Vitest.
**Test File**: `test/yaml.spec.ts`
**What is tested**:
- Data structure validation against TypeScript interfaces
- URL reachability for all external links (with retry logic)
- Date format validation
- Required field presence
- Data type correctness
**Running tests**:
```bash
pnpm test
```
Tests have a 120-second timeout to accommodate URL validation checks, which may be rate-limited.
### 2.10 Development Workflow
1. **Make changes to data**:
- Edit YAML files in `/data` directory
- Use your preferred text editor
2. **Validate your changes**:
```bash
pnpm run lint:yaml # Validate YAML syntax
pnpm run lint:spelling # Check spelling
pnpm test # Run full test suite
```
3. **Build the application**:
```bash
pnpm run build
```
4. **Start the server locally**:
```bash
node ./prod/index.js
```
Or with 1Password environment variables:
```bash
pnpm run start
```
5. **Test endpoints**:
```bash
curl http://localhost:9999/projects.json
```
### 2.11 Deployment
#### Environment Variables
The production start script uses 1Password CLI for secure environment variable management:
```bash
op run --env-file ./prod.env -- node ./prod/index.js
```
Create a `prod.env` file with 1Password references for any required environment variables.
#### Production Considerations
1. **Reverse Proxy**: Consider running the Application behind a reverse proxy (nginx, Apache) for:
- SSL/TLS termination
- Rate limiting
- Caching
- Load balancing
2. **Process Management**: Use a process manager to ensure uptime:
- PM2
- systemd
- Docker with restart policies
3. **Monitoring**: Implement monitoring for:
- Server health
- Response times
- Error rates
4. **Backups**: Regularly backup the `/data` directory, as it contains the source YAML files.
### 2.12 Troubleshooting
#### Server won't start
- Verify port 9999 is not in use
- Check that dependencies are installed (`pnpm install`)
- Ensure the build completed successfully (`pnpm run build`)
#### Data not updating
- Verify you edited the YAML files, not JSON files
- Run `pnpm run build` to regenerate JSON
- Restart the server
#### Test failures
- **URL validation failures**: May be due to rate limiting; tests include retry logic
- **Data structure failures**: Ensure YAML structure matches TypeScript interfaces
- **Spelling failures**: Add custom words to cspell configuration if needed
## 3. Legal Documentation
This section is for expansions to our legal policies specific to the Application.
### 3.1 Data Usage and Privacy
#### Data Served by the Application
The Application serves public, non-sensitive data intended for public consumption. The data categories include:
- **Projects**: Public information about open-source projects and portfolio work
- **Resume**: Professional experience, education, and certifications
- **Testimonials**: Public testimonials and recommendations
- **Donation Information**: Public donation platform links
- **Funding Information**: Public funding channel and subscription information
#### No Personal User Data Collection
The Application itself does not collect, store, or process any personal data from users accessing the API. The server:
- Does not require authentication
- Does not track user requests
- Does not use cookies or similar tracking technologies
- Does not log IP addresses or personally identifiable information
#### CORS and Third-Party Access
By enabling CORS for all origins, the Application explicitly permits third-party websites and applications to access the served data. This is intentional and by design, as the data is meant for public consumption.
### 3.2 Data Accuracy and Updates
The data served by the Application is maintained on a best-effort basis. While efforts are made to ensure accuracy:
- Data may become outdated between updates
- URLs and external links may become invalid over time
- No guarantee of real-time data freshness is provided
Users consuming this data should:
- Implement appropriate error handling for unavailable resources
- Cache responses responsibly
- Not rely on the Application for time-sensitive or critical decisions
### 3.3 Service Availability
The Application is provided "as-is" without guarantees of:
- Continuous availability
- Specific uptime percentages
- Response time performance
- Data freshness
Users should not build critical systems that depend on the Application's availability without implementing appropriate fallbacks and error handling.
### 3.4 Intellectual Property
#### Data Content
The data served by the Application contains information about projects, professional experience, and other content that may be subject to intellectual property rights:
- Project names, descriptions, and logos may be trademarks
- Code and software referenced may be under various open-source licenses
- Testimonial content remains the intellectual property of the original authors
Users consuming this data should:
- Respect intellectual property rights
- Provide proper attribution when displaying data
- Review specific licenses for any referenced projects or software
#### Application Code
The Application's source code is licensed under the terms specified in the LICENSE.md file. Copyright is held by Naomi Carrigan.
### 3.5 Terms of Service
The general Terms of Service can be found at: https://docs.nhcarrigan.com/#/terms
#### Application-Specific Terms
Users of the Application agree to:
- Use the API in good faith and not for malicious purposes
- Not attempt to overwhelm the server with excessive requests
- Not attempt to exploit vulnerabilities or security weaknesses
- Respect the intended public use of the data
### 3.6 Privacy Policy
The general Privacy Policy can be found at: https://docs.nhcarrigan.com/#/privacy
#### Application-Specific Privacy Notes
As noted in section 3.1, the Application does not collect user data. The privacy policy primarily applies to:
- Contributors to the codebase (governed by GitHub's privacy policy)
- Data maintainers with access to the data repository
## 4. Contributing Documentation
This section is for documentation related to contributing to the Application's codebase.
### 4.1 General Contributing Guidelines
General contributing guidelines can be found at: https://docs.nhcarrigan.com/#/contributing
Please review these guidelines before contributing to the Application.
### 4.2 Code of Conduct
Before interacting with the project or community, please read the [Code of Conduct](CODE_OF_CONDUCT.md).
### 4.3 Ways to Contribute
#### 4.3.1 Data Contributions
If you have corrections or updates to the data served by the Application:
1. **Data corrections**: If you notice incorrect information, please open an issue
2. **Testimonials**: If you'd like to add a testimonial, please contact through the official channels
3. **Project updates**: For updates to project information, verify you have permission to modify the data
#### 4.3.2 Code Contributions
Contributors can help improve the Application in several ways:
**Features**:
- Enhanced API endpoints
- New data validation rules
- Performance optimizations
- Additional data format support
- API documentation improvements
**Bug Fixes**:
- Server stability issues
- Route handling bugs
- Build process errors
- Test failures
**Quality Improvements**:
- Code refactoring
- Test coverage expansion
- Documentation enhancements
- Type safety improvements
### 4.4 Development Setup
1. **Fork and clone** the repository
2. **Install dependencies**: `pnpm install`
3. **Create a branch** for your changes: `git checkout -b feature/your-feature-name`
4. **Make your changes** following the guidelines below
5. **Test your changes**: `pnpm test`
6. **Lint your code**: `pnpm run lint`
7. **Build the project**: `pnpm run build`
8. **Commit and push** your changes
9. **Open a Pull Request**
### 4.5 Code Style Guidelines
#### TypeScript
- Follow the ESLint configuration (`@nhcarrigan/eslint-config`)
- Use explicit type annotations for function parameters and return values
- Prefer interfaces over type aliases for object shapes
- Use ES modules (`import`/`export`) syntax
- Maintain strict type safety (no `any` types unless absolutely necessary)
**Example**:
```typescript
// Good
export const processData = (input: string): ProcessedData => {
// implementation
};
// Avoid
export const processData = (input) => {
// implementation
};
```
#### File Organization
- Place interfaces in `src/interfaces/`
- Place utility functions in `src/utils/`
- Place core logic in `src/modules/`
- Keep the main entry point (`src/index.ts`) minimal
#### Error Handling
- Use the custom logger from `@nhcarrigan/logger`
- Provide meaningful error messages
- Handle errors gracefully without crashing the server
### 4.6 Testing Guidelines
All contributions should maintain or improve test coverage.
#### Writing Tests
- Use Vitest test framework
- Place tests in the `/test` directory
- Use descriptive test names
**Example test structure**:
```typescript
describe("Feature Name", () => {
it("should do something specific", () => {
// Arrange
const input = setupTestData();
// Act
const result = performAction(input);
// Assert
expect(result).toBe(expectedValue);
});
});
```
#### Running Tests
Before submitting a PR:
```bash
pnpm test # Run all tests
```
### 4.7 Documentation Guidelines
When contributing documentation:
- Use clear, concise language
- Include code examples where helpful
- Update relevant sections when changing functionality
- Check spelling with `pnpm run lint:spelling`
### 4.8 Pull Request Process
1. **Ensure all checks pass**:
- All tests pass (`pnpm test`)
- Code lints without warnings (`pnpm run lint`)
- Build succeeds (`pnpm run build`)
2. **Write a clear PR description**:
- Describe what changes were made
- Explain why the changes were necessary
- Reference any related issues
3. **Respond to feedback**:
- Address review comments promptly
- Be open to suggestions and improvements
- Update the PR as requested
4. **Squash commits** if requested to maintain a clean git history
### 4.9 Adding New Data Categories
To add a new data category to the Application:
1. **Create the TypeScript interface**:
```typescript
// src/interfaces/newcategory.ts
export interface NewCategory {
id: string;
name: string;
// other fields
}
```
2. **Create the YAML data file**:
```yaml
# data/newcategory.yml
- id: example
name: Example Item
```
3. **Add tests**:
```typescript
// test/yaml.spec.ts
describe("New Category Data", () => {
it("should have valid structure", () => {
// validation tests
});
});
```
4. **Update documentation**:
- Add endpoint documentation to section 1.2
- Update project structure in section 2.4
5. **Test the changes**:
```bash
pnpm run build
node ./prod/index.js
curl http://localhost:9999/newcategory.json
```
### 4.10 Security Considerations
When contributing, keep security in mind:
- Never commit sensitive data (API keys, passwords, personal information)
- Validate all input data in tests
- Follow secure coding practices
- Report security vulnerabilities privately before opening public issues
### 4.11 Getting Help
If you need help contributing:
- Open a GitHub issue with your question
- Join the [Chat Server](http://chat.nhcarrigan.com)
- Email: `contact@nhcarrigan.com`
### 4.12 Recognition
All contributors will be recognized for their contributions. Significant contributions may be highlighted in release notes and project documentation.
---
**Last Updated**: 2025-10-29
**Application Version**: 1.0.0
**Maintained by**: NHCarrigan
src/content/docs/projects/docs.md
+2 -2
View File
@@ -1,8 +1,8 @@
---
title: NHCarrigan Documentation Site
title: NHCarrigan Documentation
---
NHCarrigan Documentation Site (hereinafter the "Application") is a comprehensive documentation website built with Astro and Starlight that serves as the central hub for all documentation related to NHCarrigan's projects, policies, and services. The site provides organized access to technical documentation, legal policies, community guidelines, and project-specific information across multiple categories including Discord bots, web applications, libraries, and development tools. The Application features a custom-themed interface with accessibility considerations, analytics integration, and environmental sustainability features.
NHCarrigan Documentation (hereinafter the "Application") is a comprehensive documentation website built with Astro and Starlight that serves as the central hub for all documentation related to NHCarrigan's projects, policies, and services. The site provides organized access to technical documentation, legal policies, community guidelines, and project-specific information across multiple categories including Discord bots, web applications, libraries, and development tools. The Application features a custom-themed interface with accessibility considerations, analytics integration, and environmental sustainability features.
## 1. User Documentation
src/content/docs/projects/eirene.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Eirene
---
Eirene (hereinafter the "Application") is a website and Discord activity that allows you to participate in code challenges competitively or collaboratively
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/projects/elaria.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Elaria
---
Elaria (hereinafter the "Application") is a meeting schedule coordination tool.
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/projects/elowyn.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Elowyn
---
Elowyn (hereinafter the "Application") is a quick website that helps you format text.
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/projects/elunara.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Elunara
---
Elunara (hereinafter the "Application") is a Discord bot that allows users to proxy messages so they correctly appear as composed by an alter.
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/projects/elysium.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Elysium
---
Elysium (hereinafter the "Application") is an idle RPG in the browser.
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/projects/evangeline.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Evangeline
---
Evangeline (hereinafter the "Application") is a Discord bot that allows you to configure canned replies, retrieve them anywhere on discord, and easily copy + paste them into chat.
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/projects/hacksmiths.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Hacksmiths
---
Hacksmiths (hereinafter the "Application") is an online programming-themed party game.
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/projects/isolda.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Isolda
---
Isolda (hereinafter the "Application") is a modern, sleek email client for the web or desktop
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/projects/life-of-a-naomi.md
+95
View File
@@ -0,0 +1,95 @@
---
title: Life of a Naomi
---
Life of a Naomi (hereinafter the "Game") is a quick game that introduces who Naomi is, and provides a glimpse into her life.
## 1. Player Documentation
This section is for players who are exploring or playing the Game.
### Controls
- **Keyboard / Gamepad:**
- Arrow keys / D-Pad: Move character
- Z / Enter / A: Confirm / Interact
- X / Esc / B: Cancel / Menu
- C / Space / Y: Open menu (if applicable)
- Shift / L / R: Dash (if enabled)
- **Touch UI (Mobile / Tablet):**
- Tap to move or interact
- On-screen buttons for menu and actions
### Troubleshooting
- Ensure your device meets RPG Maker MZ requirements.
- If the game crashes, try restarting the app or clearing temporary files.
- Ask us on discord if persistent issues occur.
---
## 2. Developer Documentation
This section is for those interested in running, modifying, or extending the Game.
### Engine & Dependencies
- **Engine:** RPG Maker MZ
- **Plugins Used:** none
- **Assets:** All original
### Setup Instructions
1. Open RPG Maker MZ.
2. Load the project folder `life-of-a-naomi`.
3. Use the "Playtest" button to run the Game locally.
4. To export, use the "Deployment" feature for target platforms.
### Directory Structure
- `data/` ā€” database files (maps, events, actors, items, skills, etc.)
- `img/` ā€” graphics (characters, tilesets, animations, pictures, etc.)
- `audio/` ā€” music and sound effects
- `js/` ā€” plugins and core scripts
- `www/` ā€” exported HTML5 build (if deployed for web)
---
## 3. Legal Documentation
This section expands on legal or licensing information specific to the Game.
### Licensing
This Game is created using RPG Maker MZ. The game code and original content are the property of NHCarrigan. RPG Maker MZ runtime assets are licensed under the terms provided by KADOKAWA Corporation. All original graphics, music, and story content belong to NHCarrigan and are protected by copyright.
### Third-Party Notices
- Any third-party assets, music, or plugins included are credited in game.
## 4. Contributing Documentation
This section is for contributors or collaborators on the Game.
### How to Contribute
- Fork or copy the project folder.
- Submit patches or mods via Git.
- Include a changelog and clear notes on modifications.
### Coding Standards
- Plugins in `js/plugins/` should follow standard JS conventions.
- Comment custom scripts clearly for readability.
### Art & Audio Guidelines
- Maintain original resolutions where possible (48x48 tiles, etc.).
- Use consistent naming for files in `img/` and `audio/`.
### Contact
- For collaboration or questions, ask us on discord.
src/content/docs/projects/liora.md
+624
View File
@@ -0,0 +1,624 @@
---
title: Liora
---
Liora (hereinafter the "Application") is a Discord bot that provides a "highlight words" notification system for Discord servers. The Application monitors messages in Discord servers and sends direct messages (DMs) to users when specific words or phrases they've configured are mentioned, bringing IRC-style highlight/ping functionality to Discord.
## 1. User Documentation
This section is for those interacting with a live instance of the Application.
### 1.1 Getting Started
To use Liora in your Discord server, you'll need to:
1. **Add the bot to your server**: Visit the [invite link](https://discord.com/oauth2/authorize?client_id=1391492296222179459)
2. **Subscribe to premium**: A server administrator must purchase a server subscription from the Discord store, unless your server is whitelisted
3. **Enable DMs**: Ensure you have direct messages enabled from server members to receive notifications
### 1.2 Available Commands
The Application provides the following slash commands:
#### `/about`
Displays information about Liora, including what it does and how to get help.
#### `/add <word>`
Adds a word or phrase to your highlight list for the current server.
- **Parameters**:
- `word` (required): The word or phrase to monitor
- **Limitations**: Maximum of 10 highlights per user per server
- **Behaviour**: Case-insensitive matching
**Example**: `/add typescript` will notify you whenever someone mentions "TypeScript", "typescript", or "TYPESCRIPT"
#### `/remove <word>`
Removes a word or phrase from your highlight list for the current server.
- **Parameters**:
- `word` (required): The word or phrase to remove from monitoring
**Example**: `/remove typescript`
#### `/list`
Displays all your configured highlight words for the current server.
#### `/dm`
Tests whether the bot can send you direct messages. Use this command if you're not receiving notifications to verify your DM settings are correct.
### 1.3 Notification Format
When a message contains one of your highlight words, you'll receive a DM containing:
- Which word(s) were matched
- The server name where the message was sent
- The display name of the user who sent the message
- A direct link to the original message
- Action buttons:
- **Jump to Message**: Opens the message in Discord
- **Discord Server**: Links to the support server
- **Forum**: Links to the support forum
### 1.4 Important Notes
- You will **not** receive notifications for messages you send yourself
- Highlight matching is **case-insensitive** (e.g., "discord" matches "Discord", "DISCORD", etc.)
- Highlights are **server-specific** - each server has its own separate list
- The bot requires the ability to send you DMs - check your privacy settings if notifications aren't working
### 1.5 Support and Feedback
If you need assistance or want to report a bug:
- **Discord Server**: [chat.nhcarrigan.com](https://chat.nhcarrigan.com)
- **Forum**: [forum.nhcarrigan.com](https://forum.nhcarrigan.com)
- **Email**: contact@nhcarrigan.com
- **GitHub Issues**: Open an issue on the repository
### 1.6 Subscription Information
The Application uses Discord's premium subscription system. Server administrators can purchase a subscription to enable the bot for all members. Two servers are currently whitelisted for free access (Naomi's server and FreeCodeCamp).
**Premium SKU ID**: 1396962587471515769
## 2. Technical Documentation
This section is for those interested in running their own instance of the Application.
### 2.1 System Requirements
- **Node.js**: v22 or higher
- **Package Manager**: pnpm 10.13.1 or higher
- **Database**: MongoDB instance
- **Discord**: Bot token from Discord Developer Portal
- **1Password CLI** (optional): For secure environment variable management
### 2.2 Technology Stack
#### Core Technologies
- **Runtime**: Node.js v22
- **Language**: TypeScript 5.8.3
- **Package Manager**: pnpm 10.13.1
#### Main Dependencies
- **discord.js** (v14.21.0): Discord API interaction and bot framework
- **@prisma/client** (v6.12.0): Database ORM for MongoDB
- **fastify** (v5.4.0): Lightweight HTTP server for health monitoring
- **@nhcarrigan/discord-analytics** (v0.0.6): Analytics tracking
- **@nhcarrigan/logger** (v1.1.1): Logging utility
#### Development Tools
- **ESLint** (v9.31.0): Code linting with @nhcarrigan/eslint-config
- **Prisma** (v6.12.0): Database schema management
- **TypeScript**: Type safety and compilation
### 2.3 Architecture Overview
The Application follows an event-driven architecture:
```
src/
ā”œā”€ā”€ index.ts # Application entry point
ā”œā”€ā”€ commands/ # Slash command handlers
ā”‚ ā”œā”€ā”€ about.ts
ā”‚ ā”œā”€ā”€ add.ts
ā”‚ ā”œā”€ā”€ remove.ts
ā”‚ ā”œā”€ā”€ list.ts
ā”‚ ā””ā”€ā”€ dm.ts
ā”œā”€ā”€ events/ # Discord event handlers
ā”‚ ā”œā”€ā”€ interactionCreate.ts # Command routing
ā”‚ ā””ā”€ā”€ messageCreate.ts # Message monitoring (core logic)
ā”œā”€ā”€ interfaces/ # TypeScript type definitions
ā”‚ ā”œā”€ā”€ liora.ts # Main bot interface
ā”‚ ā””ā”€ā”€ command.ts # Command type definition
ā”œā”€ā”€ utils/ # Utility functions
ā”‚ ā”œā”€ā”€ checkEntitlement.ts # Subscription validation
ā”‚ ā”œā”€ā”€ errorHandler.ts # Error logging with UUIDs
ā”‚ ā””ā”€ā”€ logger.ts # Logger configuration
ā”œā”€ā”€ modules/ # Business logic
ā”‚ ā””ā”€ā”€ sendUnentitledResponse.ts
ā”œā”€ā”€ config/ # Configuration
ā”‚ ā””ā”€ā”€ entitlements.ts # Whitelisted guild IDs
ā””ā”€ā”€ server/ # HTTP server
ā””ā”€ā”€ serve.ts # Health monitoring endpoint
```
#### Key Components
**Entry Point** (`src/index.ts`):
- Initializes Prisma database client
- Creates Discord bot with required intents (Guilds, GuildMessages, MessageContent)
- Sets up event listeners
- Starts analytics cron job
- Launches Fastify web server on port 5022
**Message Processing** (`src/events/messageCreate.ts`):
- Validates guild entitlement/subscription
- Queries database for all highlights in the server
- Performs case-insensitive matching against message content
- Sends DM notifications with formatted components
- Logs metrics for analytics
**Command Handlers**:
All commands use Discord's Components V2 API with ContainerBuilder and TextDisplayBuilder for rich formatting.
### 2.4 Database Schema
The Application uses MongoDB with Prisma ORM:
```prisma
model Highlights {
id String @id @default(auto()) @map("_id") @db.ObjectId
serverId String # Discord guild ID
userId String # Discord user ID
words String[] # Array of highlight words
@@unique([serverId, userId])
@@index([serverId])
}
```
- Each user can have one document per server
- The unique constraint ensures no duplicate user-server combinations
- The server ID is indexed for efficient queries when processing messages
### 2.5 Installation and Setup
#### Step 1: Clone the Repository
```bash
git clone https://git.nhcarrigan.com/nhcarrigan/liora.git
cd liora
```
#### Step 2: Install Dependencies
```bash
pnpm install
```
#### Step 3: Configure Environment Variables
Create a `prod.env` file with the following variables:
```env
DISCORD_TOKEN=your_discord_bot_token
MONGO_URI=your_mongodb_connection_string
LOG_TOKEN=your_logging_service_token
```
**Discord Bot Setup**:
1. Visit [Discord Developer Portal](https://discord.com/developers/applications)
2. Create a new application
3. Navigate to the "Bot" section and create a bot
4. Enable these Privileged Gateway Intents:
- Server Members Intent (GUILDS)
- Message Content Intent (MESSAGE_CONTENT)
5. Copy the bot token to your environment file
**MongoDB Setup**:
- Provide a MongoDB connection URI in the format: `mongodb://user:password@host:port/database`
- Alternatively, use MongoDB Atlas for a cloud-hosted solution
#### Step 4: Generate Prisma Client
```bash
pnpm run build
```
This command runs `prisma generate && tsc`, which:
- Generates the Prisma client from the schema
- Compiles TypeScript to the `./prod` directory
#### Step 5: Register Discord Commands
Use the `commandJson.js` file to register slash commands with Discord:
```bash
node commandJson.js
```
Then use the output to register commands via Discord's API or developer portal.
#### Step 6: Start the Application
**With 1Password CLI**:
```bash
pnpm run start
```
**Without 1Password CLI**:
```bash
node ./prod/index.js
```
The Application will:
- Connect to MongoDB
- Log in to Discord
- Start the web server on port 5022
- Begin monitoring messages
### 2.6 Development Workflow
#### Linting
```bash
pnpm run lint
```
Uses ESLint with @nhcarrigan/eslint-config.
#### Building
```bash
pnpm run build
```
Generates Prisma client and compiles TypeScript.
#### Running Tests
```bash
pnpm test
```
Currently returns a placeholder. Test implementation is pending.
### 2.7 Continuous Integration
The repository includes a Gitea Actions workflow (`.gitea/workflows/ci.yml`) that:
- Runs on push and pull requests to the main branch
- Executes linting with ESLint
- Verifies TypeScript compilation
- Runs tests
### 2.8 Configuration
#### Whitelisted Guilds
Two Discord servers have free access without subscriptions, configured in `src/config/entitlements.ts`. To modify:
1. Edit `src/config/entitlements.ts`
2. Add guild IDs to the whitelist array
3. Rebuild the application
#### Subscription SKU
The premium subscription SKU is defined in `src/utils/checkEntitlement.ts`. To use your own subscription:
1. Create a subscription in Discord's Developer Portal
2. Update the SKU ID in the entitlement check logic
3. Rebuild the application
### 2.9 Deployment
#### Web Server
The Application includes a Fastify web server that:
- Listens on port 5022
- Serves a landing page at `/`
- Provides information about the bot
- Includes an "Add to Discord" button
- Useful for health checks and monitoring
#### Production Deployment Checklist
1. Ensure all environment variables are configured
2. Build the application with `pnpm run build`
3. Set up process management (PM2, systemd, Docker, etc.)
4. Configure reverse proxy if exposing the web server
5. Set up MongoDB backups
6. Monitor logs via the configured logging service
7. Register Discord commands before starting the bot
#### Health Monitoring
The web server on port 5022 can be used for health checks. A simple GET request to `/` will return the landing page HTML if the service is running.
### 2.10 Analytics
The Application integrates with a custom analytics service (@nhcarrigan/discord-analytics):
- **Tracked Metrics**:
- `highlight_triggered`: Logged when a highlight word is matched
- Gateway events (connection, ready, etc.)
- **Metadata**: Includes server ID, user ID, and matched words
- **Authentication**: Requires LOG_TOKEN environment variable
### 2.11 API Endpoints
The Fastify web server exposes:
- `GET /`: Landing page with bot information and "Add to Discord" link
### 2.12 Security Considerations
- **Message Content Intent**: The bot requires access to read all message content in subscribed guilds. This is a privileged intent and should be handled responsibly.
- **Environment Variables**: Use secure methods to manage secrets (1Password CLI, environment variable management services, etc.)
- **DM Privacy**: The bot only sends DMs when highlights are triggered; it does not store message content
- **Entitlement Validation**: All commands and message processing verify subscription status to prevent unauthorized usage
### 2.13 Troubleshooting
#### Bot Not Responding to Commands
- Verify the bot has appropriate permissions in the server
- Check that commands are registered with Discord's API
- Ensure the bot is online and connected
#### DMs Not Being Sent
- Verify users have DMs enabled from server members
- Check that the bot has permission to send DMs
- Use the `/dm` command to test DM functionality
#### Database Connection Issues
- Verify MongoDB connection string format
- Ensure MongoDB instance is accessible from the application
- Check Prisma client is generated (`pnpm run build`)
#### Analytics Not Working
- Verify LOG_TOKEN is correctly configured
- Check analytics service is reachable
- Review application logs for errors
## 3. Legal Documentation
This section is for expansions to our legal policies specific to the Application.
### 3.1 License
This software is licensed under [Naomi's Public License](https://docs.nhcarrigan.com/#/license).
Copyright held by Naomi Carrigan.
### 3.2 Data Collection and Privacy
The Application collects and stores the following data:
- **Discord User IDs**: To identify which users should receive notifications
- **Discord Server IDs**: To associate highlights with specific servers
- **Highlight Words**: The words/phrases users choose to monitor
- **Analytics Metrics**: Anonymous usage statistics (highlight triggers, command usage)
**Data Usage**:
- User data is used solely to provide the highlight notification functionality
- Analytics data is used to improve the Application
- No message content is stored permanently
- Data is stored in a MongoDB database
**Data Retention**:
- Highlight data is retained until manually removed by users via the `/remove` command
- Users can view all their stored data via the `/list` command
**Third-Party Services**:
- Discord API: Required for bot functionality
- MongoDB: Database hosting
- Custom Analytics Service: Usage metrics tracking
### 3.3 Terms of Service
By using the Application, you agree to:
- Use the Application in accordance with Discord's Terms of Service
- Not abuse the highlight system to spam or harass other users
- Accept that the service is provided "as is" without warranties
- Understand that subscription fees are non-refundable per Discord's policies
### 3.4 Acceptable Use
Users must not:
- Use the Application to harass or spam other users
- Attempt to circumvent subscription requirements
- Exploit bugs or vulnerabilities in the Application
- Use the Application for any illegal purposes
### 3.5 Subscription Terms
- Subscriptions are managed through Discord's subscription system
- Pricing and billing are handled by Discord
- Subscriptions are server-specific (per-guild)
- Two servers are currently whitelisted for free access
- Subscription status is validated before processing commands and notifications
### 3.6 Liability
The Application maintainers are not liable for:
- Missed notifications due to Discord API issues or user configuration
- Data loss due to database failures or user error
- Service interruptions or downtime
- Actions taken by users based on notifications received
### 3.7 Contact for Legal Inquiries
For legal questions or concerns:
- **Email**: contact@nhcarrigan.com
- **Discord**: [chat.nhcarrigan.com](https://chat.nhcarrigan.com)
## 4. Contributing Documentation
This section is for documentation related to contributing to the Application's codebase.
### 4.1 Contributing Guidelines
Our comprehensive contributing guidelines can be found at: [https://docs.nhcarrigan.com/#/contributing](https://docs.nhcarrigan.com/#/contributing)
### 4.2 Code of Conduct
Before interacting with our community, please review our Code of Conduct: [https://docs.nhcarrigan.com/#/coc](https://docs.nhcarrigan.com/#/coc)
### 4.3 How to Contribute
#### Reporting Bugs
If you encounter a bug:
1. Check existing GitHub issues to avoid duplicates
2. Create a new issue with:
- Clear description of the bug
- Steps to reproduce
- Expected vs. actual behavior
- Environment details (Node.js version, OS, etc.)
- Error logs or screenshots if applicable
#### Suggesting Features
For feature requests:
1. Open a GitHub issue with the "feature request" label
2. Describe the feature and its use case
3. Explain why it would benefit users
4. Be open to discussion and feedback
#### Submitting Pull Requests
To contribute code:
1. **Fork the repository** on Gitea or GitHub
2. **Create a feature branch**: `git checkout -b feature/your-feature-name`
3. **Make your changes**:
- Follow the existing code style
- Add comments for complex logic
- Update documentation if needed
4. **Test your changes**:
- Ensure the application builds: `pnpm run build`
- Run linting: `pnpm run lint`
- Test functionality locally
5. **Commit your changes**:
- Use clear, descriptive commit messages
- Reference related issues if applicable
6. **Push to your fork**: `git push origin feature/your-feature-name`
7. **Open a Pull Request**:
- Describe what changes were made and why
- Link to related issues
- Wait for review and address feedback
### 4.4 Development Setup
Follow the steps in Section 2.5 (Installation and Setup) to set up your development environment.
**Additional Development Tips**:
- Use TypeScript strict mode for type safety
- Follow the ESLint configuration for consistent code style
- Test commands in a development Discord server before submitting
- Use meaningful variable and function names
- Add JSDoc comments for public functions and interfaces
### 4.5 Code Style Guidelines
The Application uses:
- **@nhcarrigan/eslint-config**: ESLint configuration for consistent style
- **@nhcarrigan/typescript-config**: TypeScript configuration
- **Prettier-compatible formatting**: Enforced via ESLint
Key conventions:
- **File naming**: camelCase for TypeScript files
- **Function naming**: camelCase for functions, PascalCase for classes/interfaces
- **Indentation**: 2 spaces
- **Quotes**: Double quotes for strings
- **Semicolons**: Required
- **Max line length**: Enforced by ESLint (exceptions allowed for long strings)
### 4.6 Project Structure Guidelines
When adding new features:
- **Commands**: Add to `src/commands/` directory
- **Events**: Add to `src/events/` directory
- **Utilities**: Add to `src/utils/` directory
- **Business Logic**: Add to `src/modules/` directory
- **Type Definitions**: Add to `src/interfaces/` directory
### 4.7 Testing Guidelines
Currently, the Application does not have automated tests. Contributions to add testing infrastructure are welcome!
**Manual Testing Checklist**:
- Test all commands in a Discord server
- Verify highlight matching works correctly
- Test edge cases (max highlights, special characters, etc.)
- Verify DM notifications are sent properly
- Test subscription validation
- Check error handling
### 4.8 Documentation Contributions
Documentation improvements are highly valued! You can contribute by:
- Fixing typos or unclear explanations
- Adding examples or use cases
- Improving setup instructions
- Translating documentation (if applicable)
- Adding diagrams or visual aids
### 4.9 Community Involvement
Join our community:
- **Discord Server**: [chat.nhcarrigan.com](https://chat.nhcarrigan.com) - Ask questions, discuss features
- **Forum**: [forum.nhcarrigan.com](https://forum.nhcarrigan.com) - Long-form discussions and support
- **GitHub Issues**: Track bugs and feature requests
### 4.10 Recognition
Contributors will be recognized in:
- Git commit history
- Release notes for significant contributions
- The community Discord server
### 4.11 Getting Help
If you need help while contributing:
- Ask in the Discord server (#development or #support channels)
- Post on the forum for detailed questions
- Comment on the relevant GitHub issue or pull request
- Email: contact@nhcarrigan.com
### 4.12 Release Process
The Application follows semantic versioning (SemVer):
- **Major versions** (X.0.0): Breaking changes
- **Minor versions** (0.X.0): New features, backward compatible
- **Patch versions** (0.0.X): Bug fixes, backward compatible
**Current Version**: v1.0.0 (as of latest commit: ba5987e)
Releases are managed by the maintainers. Contributors should focus on feature branches and pull requests rather than version bumping.
---
**Additional Resources**:
- **Live Bot**: [Add to Discord](https://discord.com/oauth2/authorize?client_id=1391492296222179459)
- **Source Code**: [Gitea Repository](https://git.nhcarrigan.com/nhcarrigan/liora)
- **Documentation Hub**: [docs.nhcarrigan.com](https://docs.nhcarrigan.com)
- **Support Server**: [chat.nhcarrigan.com](https://chat.nhcarrigan.com)
- **Support Forum**: [forum.nhcarrigan.com](https://forum.nhcarrigan.com)
- **Contact Email**: contact@nhcarrigan.com
src/content/docs/projects/logger.md
+2 -2
View File
@@ -1,8 +1,8 @@
---
title: "@nhcarrigan/logger"
title: "Logger"
---
@nhcarrigan/logger (hereinafter the "Application") is a custom logging utility that provides a wrapper around a custom alert monitoring server, enabling applications to pipe errors and log messages to a centralized alerting system.
Logger (hereinafter the "Application") is a custom logging utility that provides a wrapper around a custom alert monitoring server, enabling applications to pipe errors and log messages to a centralized alerting system.
## 1. User Documentation
src/content/docs/projects/lucinda.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Lucinda
---
Lucinda (hereinafter the "Application") is a kanban-style task management site.
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/projects/lyra.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Lyra
---
Lyra (hereinafter the "Application") is a web-based API mocking tool, allowing you to create temporary endpoints for a front-end to hit, test webhook payloads, and more!
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/projects/maribelle.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Maribelle
---
Maribelle (hereinafter the "Application") is a Discord bot that allows you to configure daily progress huddle reminders for your server members.
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/projects/meliora.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Meliora
---
Meliora (hereinafter the "Application") is an embeddable chat widget, comment section, and full support flow utility.
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/projects/meridia.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Meridia
---
Meridia (hereinafter the "Application") is our custom metrics and analytics server.
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/projects/naomis-adventure-i.md
+38
View File
@@ -0,0 +1,38 @@
---
title: "Naomi's Adventure I: An Isekai Story"
---
Naomi's Adventure I: An Isekai Story (hereinafter the "Application") is an Isekai story, and our first paid game.
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/projects/nymira.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Nymira
---
Nymira (hereinafter the "Application") is a service that allows you to claim a custom <username>.naomi.party username for Bluesky.
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/projects/octavia.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Octavia
---
Octavia (hereinafter the "Application") is a Linux-native music player application with a focus on handling large libraries with minimal memory.
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/projects/oriana.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Oriana
---
Oriana (hereinafter the "Application") is an uptime monitoring tool with status pages
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/projects/portfolio.md
+2 -19
View File
@@ -1,15 +1,10 @@
---
title: NHCarrigan Portfolio
title: Portfolio
---
NHCarrigan Portfolio (hereinafter the "Application") is a static HTML landing page that serves as the primary web presence for NHCarrigan, a software engineering and community management consulting firm. The Application provides information about the organization's services, contact methods, past clients, and founder, while serving as a gateway to the broader NHCarrigan ecosystem of tools and communities.
Portfolio (hereinafter the "Application") is a static HTML landing page that serves as the primary web presence for NHCarrigan, a software engineering and community management consulting firm. The Application provides information about the organization's services, contact methods, past clients, and founder, while serving as a gateway to the broader NHCarrigan ecosystem of tools and communities.
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
### Current Live Instance
@@ -32,10 +27,6 @@ The Application is currently deployed and accessible at [nhcarrigan.com](https:/
## 2. Technical Documentation
:::note
This section is coming soon!
:::
This section is for those interested in running their own instance of the Application.
### Architecture
@@ -58,10 +49,6 @@ The Application is built as a simple static HTML website consisting of:
## 3. Legal Documentation
:::note
This section is coming soon!
:::
This section is for expansions to our legal policies specific to the Application.
### Current Legal Framework
@@ -75,10 +62,6 @@ The Application operates under NHCarrigan's standard legal documentation:
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
### Current Contributing Guidelines
src/content/docs/projects/resume.md
+2 -2
View File
@@ -1,8 +1,8 @@
---
title: Naomi's Resume
title: Resume
---
Naomi's Resume (hereinafter the "Application") is a static site generator that transforms a YAML or JSON resume source into a styled HTML resume website, along with downloadable formats. It is designed for easy customization and deployment, using TypeScript for parsing and rendering, and outputs a ready-to-host static site.
Resume (hereinafter the "Application") is a static site generator that transforms a YAML or JSON resume source into a styled HTML resume website, along with downloadable formats. It is designed for easy customization and deployment, using TypeScript for parsing and rendering, and outputs a ready-to-host static site.
## 1. User Documentation
src/content/docs/projects/rowena.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Rowena
---
Rowena (hereinafter the "Application") is a web app that allows you to create and share forms, and track responses in a user friendly table.
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/projects/ruus-goblin-quest.md
+95
View File
@@ -0,0 +1,95 @@
---
title: Ruu's Goblin Quest
---
Ruu's Goblin Quest (hereinafter the "Game") is a game developed for our friend Ruu's game jam.
## 1. Player Documentation
This section is for players who are exploring or playing the Game.
### Controls
- **Keyboard / Gamepad:**
- Arrow keys / D-Pad: Move character
- Z / Enter / A: Confirm / Interact
- X / Esc / B: Cancel / Menu
- C / Space / Y: Open menu (if applicable)
- Shift / L / R: Dash (if enabled)
- **Touch UI (Mobile / Tablet):**
- Tap to move or interact
- On-screen buttons for menu and actions
### Troubleshooting
- Ensure your device meets RPG Maker MZ requirements.
- If the game crashes, try restarting the app or clearing temporary files.
- Ask us on discord if persistent issues occur.
---
## 2. Developer Documentation
This section is for those interested in running, modifying, or extending the Game.
### Engine & Dependencies
- **Engine:** RPG Maker MZ
- **Plugins Used:** none
- **Assets:** All original
### Setup Instructions
1. Open RPG Maker MZ.
2. Load the project folder `ruus-goblin-quest`.
3. Use the "Playtest" button to run the Game locally.
4. To export, use the "Deployment" feature for target platforms.
### Directory Structure
- `data/` ā€” database files (maps, events, actors, items, skills, etc.)
- `img/` ā€” graphics (characters, tilesets, animations, pictures, etc.)
- `audio/` ā€” music and sound effects
- `js/` ā€” plugins and core scripts
- `www/` ā€” exported HTML5 build (if deployed for web)
---
## 3. Legal Documentation
This section expands on legal or licensing information specific to the Game.
### Licensing
This Game is created using RPG Maker MZ. The game code and original content are the property of NHCarrigan. RPG Maker MZ runtime assets are licensed under the terms provided by KADOKAWA Corporation. All original graphics, music, and story content belong to NHCarrigan and are protected by copyright.
### Third-Party Notices
- Any third-party assets, music, or plugins included are credited in game.
## 4. Contributing Documentation
This section is for contributors or collaborators on the Game.
### How to Contribute
- Fork or copy the project folder.
- Submit patches or mods via Git.
- Include a changelog and clear notes on modifications.
### Coding Standards
- Plugins in `js/plugins/` should follow standard JS conventions.
- Comment custom scripts clearly for readability.
### Art & Audio Guidelines
- Maintain original resolutions where possible (48x48 tiles, etc.).
- Use consistent naming for files in `img/` and `audio/`.
### Contact
- For collaboration or questions, ask us on discord.
src/content/docs/projects/selene.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Selene
---
Selene (hereinafter the "Application") is a local-only privacy-focused REST API client.
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/projects/static-pages.md
+619 -218
View File
@@ -2,254 +2,655 @@
title: Static Pages
---
Static Pages (hereinafter the "Application") is a collection of static HTML pages and related data/scripts for various small web utilities and content sections. The application provides interactive explorers for books and music libraries, product directories, games, chat services, testimonials, and other utility pages. It is designed to be easily synchronized to a production server using shell scripts and requires no backend or dynamic server-side logic.
Static Pages (hereinafter the "Application") is a collection of static HTML pages that serve as the foundation for various web-based services and informational resources offered by Naomi Carrigan. The Application provides a lightweight, accessible platform for showcasing personal content, accepting donations, displaying testimonials, cataloguing personal collections, and managing product information.
## 1. User Documentation
The Application provides several interactive web utilities:
### Book Library
Visit at https://books.nhcarrigan.com
An interactive explorer for Naomi's book collection. Users can browse and search through the library of books with filtering capabilities by author. The interface displays book titles and authors extracted from digital book files.
### Music Library
Visit at https://music.nhcarrigan.com
An interactive explorer for Naomi's music collection. Similar to the book library, users can browse and search through songs with filtering by artist. The interface displays song titles and artists extracted from audio file metadata.
### Games
Visit at https://games.nhcarrigan.com
A landing page showcasing various games developed by NHCarrigan, including links to the Beccalia Series and other game projects.
### BlueSky Handle Generator
Visit at https://naomi.party
A service page for provisioning custom Bluesky handles under the naomi.party domain. Currently requires manual processing through the Discord support server.
### Testimonials
Visit at https://testimonials.nhcarrigan.com
A showcase page displaying testimonials from past clients about NHCarrigan's work and services.
### Link Redirector
Visit at https://nhcarrigan.link
A utility page that serves as a fallback for improperly configured subdomain redirects, providing users with support contact information.
This section is for those interacting with a live instance of the Application.
### User Manual
### 1.1 Available Pages
Visit at https://manual.nhcarrigan.com
The Application consists of several distinct pages, each serving a specific purpose:
A brief description of what it is like to work with Naomi, and how to cultivate an environment where she can thrive.
#### 1.1.1 Donation Page (`/donate`)
The donation page provides multiple avenues for supporting Naomi Carrigan's work, including:
- **OpenCollective**: Main financial ledger tracking all income and expenses
- **Patreon**: Monthly membership support
- **Ko-Fi**: Coffee donations and one-time contributions
- **PayPal**: Direct donation processing
- **CashApp**: Direct monetary transfers
- **GitHub Sponsors**: Platform-integrated sponsorship
- **Stripe**: Monthly recurring donations
- **Twitch**: Stream subscriptions
- **Throne**: Gift suggestion and purchase platform
- **Discord**: Community hub access
#### 1.1.2 Book Library (`/books`)
An interactive explorer displaying books that Naomi has read. Features include:
- Searchable database by author and title
- Filterable results with dynamic count display
- Alphabetically sorted table view
- JSON-backed data storage (`books.json`)
- Currently displays over 1,000 books
#### 1.1.3 Music Library (`/music`)
An interactive explorer for music that Naomi listens to. Features include:
- Search functionality for artists and titles
- Dynamic filtering with live count updates
- Tabular display with alternating row colors
- JSON-backed data storage (`songs.json`)
#### 1.1.4 Testimonials (`/testimonials`)
A comprehensive showcase of professional feedback and recommendations from:
- Past clients
- Colleagues
- Community members
- Internal team feedback (anonymized for privacy)
Features include:
- Print-optimized styling
- Chronologically organized testimonials
- Web form integration for new submissions
- Over 50 professional testimonials spanning multiple years (2023-2025)
#### 1.1.5 Link Redirector (`/link-redirector`)
A fallback page for improperly configured subdomain redirects, providing users with support contact information.
#### 1.1.6 Additional Pages
- **Chat** (`/chat`): Community communication hub
- **Mail** (`/mail`): Email-related services
- **Games** (`/games`): Gaming-related content
- **Manual** (`/manual`): User manuals and guides
- **Sitemap** (`/sitemap`): Site navigation structure
- **Bluesky** (`/bsky`): Bluesky social platform integration
### 1.2 Common Features
All pages share common functionality through a global header system:
- Consistent styling via CSS custom properties (variables)
- Responsive design for mobile and desktop
- Global navigation (loaded from `cdn.nhcarrigan.com/headers/index.js`)
- Consistent theming with foreground/background color variables
- Custom cursor styles
### 1.3 Accessibility
The Application is designed with accessibility in mind:
- Semantic HTML5 structure
- Proper heading hierarchy
- Descriptive page titles and meta descriptions
- Responsive viewport scaling
- UTF-8 character encoding
## 2. Technical Documentation
### System Requirements
- Unix-like operating system (Linux/macOS)
- Bash shell
- `rsync` for deployment
- `exiftool` for extracting book metadata
- `mid3v2` for extracting music metadata
- `jq` for JSON processing
- Access to Gitea API (for products functionality)
- Web server capable of serving static files
### Project Structure
```
ā”œā”€ā”€ books/ # Book library interface
ā”‚ ā”œā”€ā”€ index.html # Main book explorer page
ā”‚ ā””ā”€ā”€ books.json # Generated book data
ā”œā”€ā”€ music/ # Music library interface
ā”‚ ā”œā”€ā”€ index.html # Main music explorer page
ā”‚ ā””ā”€ā”€ songs.json # Generated music data
ā”œā”€ā”€ products/ # Product directory
ā”‚ ā”œā”€ā”€ index.html # Product listing page
ā”‚ ā””ā”€ā”€ data.json # Generated product data
ā”œā”€ā”€ games/ # Games showcase
ā”œā”€ā”€ bsky/ # BlueSky handle service
ā”œā”€ā”€ testimonials/ # Client testimonials
ā”œā”€ā”€ link-redirector/ # Redirect fallback
ā”œā”€ā”€ mail/ # Mail service (manual sync)
ā”œā”€ā”€ manual/ # Manual/documentation
ā”œā”€ā”€ sitemap/ # Site navigation
ā”œā”€ā”€ books.sh # Book data generator script
ā”œā”€ā”€ songs.sh # Music data generator script
ā”œā”€ā”€ products.sh # Product data generator script
ā””ā”€ā”€ sync.sh # Deployment script
```
### Data Generation Scripts
**Book Library (`books.sh`)**
- Scans `/home/naomi/cloud/Books` directory for book files
- Extracts title and author metadata using `exiftool`
- Generates `books/books.json` with book data
- Handles files without metadata by using filenames
**Music Library (`songs.sh`)**
- Scans `/home/naomi/music` directory for audio files
- Extracts title and artist metadata using `mid3v2`
- Generates `music/songs.json` with song data
- Falls back to filename parsing for missing metadata
**Product Directory (`products.sh`)**
- Fetches repository data from Gitea API
- Organizes projects by category (public, games, private, archived)
- Generates `products/data.json` with project information
- Requires `GITEA_TOKEN` environment variable
### Deployment
The deployment process uses `sync.sh` which:
1. Syncs all directories to production server using `rsync`
2. Targets `prod:/home/nhcarrigan` for most content
3. Requires manual sync for `mail/index.html` to `mail:/home/user-data/www/default`
**Deployment Command:**
```bash
./sync.sh
```
### Running Your Own Instance
1. **Clone the repository**
2. **Install dependencies:**
```bash
# Ubuntu/Debian
sudo apt install exiftool python3-mutagen jq rsync
# macOS
brew install exiftool jq rsync
pip3 install mutagen
```
3. **Configure data sources:**
- Update paths in `books.sh` for your book collection
- Update paths in `songs.sh` for your music collection
- Set `GITEA_TOKEN` environment variable for products functionality
- Modify `products.sh` with your Gitea instance URL and organizations
4. **Generate data:**
```bash
./books.sh # Generate book library data
./songs.sh # Generate music library data
./products.sh # Generate product directory data
```
5. **Serve static files:**
```bash
# Simple Python server for testing
python3 -m http.server 8000
```
6. **Deploy to production:**
- Modify `sync.sh` with your server details
- Ensure SSH key authentication is configured
- Run `./sync.sh`
This section is for those interested in running their own instance of the Application.
### 2.1 Architecture
The Application is a pure static website with no backend dependencies:
- **Technology Stack**: HTML5, CSS3, Vanilla JavaScript
- **Data Storage**: JSON files for dynamic content
- **Styling**: Custom CSS with CSS custom properties
- **Scripts**: Vanilla JavaScript (no frameworks)
- **CDN Dependencies**: Global header/navigation system from `cdn.nhcarrigan.com`
### 2.2 File Structure
```
static-pages/
ā”œā”€ā”€ books/
ā”‚ ā”œā”€ā”€ index.html
ā”‚ ā””ā”€ā”€ books.json
ā”œā”€ā”€ music/
ā”‚ ā”œā”€ā”€ index.html
ā”‚ ā””ā”€ā”€ songs.json
ā”œā”€ā”€ testimonials/
ā”‚ ā””ā”€ā”€ index.html
ā”œā”€ā”€ donate/
ā”‚ ā””ā”€ā”€ index.html
ā”œā”€ā”€ products/
ā”‚ ā”œā”€ā”€ index.html
ā”‚ ā””ā”€ā”€ data.json
ā”œā”€ā”€ link-redirector/
ā”‚ ā””ā”€ā”€ index.html
ā”œā”€ā”€ bsky/
ā”œā”€ā”€ chat/
ā”œā”€ā”€ games/
ā”œā”€ā”€ mail/
ā”œā”€ā”€ manual/
ā”œā”€ā”€ sitemap/
ā”œā”€ā”€ README.md
ā”œā”€ā”€ CONTRIBUTING.md
ā”œā”€ā”€ LICENSE.md
ā”œā”€ā”€ PRIVACY.md
ā”œā”€ā”€ TERMS.md
ā”œā”€ā”€ SECURITY.md
ā””ā”€ā”€ CODE_OF_CONDUCT.md
```
### 2.3 Dependencies
#### 2.3.1 External Dependencies
- **Global Header System**: `https://cdn.nhcarrigan.com/headers/index.js`
- Provides consistent navigation and styling across all pages
- Loaded asynchronously with defer attribute
- **Font Awesome**: Icon library (loaded via global header)
- **Custom Cursors**: `https://cdn.nhcarrigan.com/cursors/pointer.cur`
#### 2.3.2 Internal Dependencies
- JSON data files for dynamic content (books.json, songs.json, data.json)
### 2.4 Deployment
The Application can be deployed to any static web host:
#### 2.4.1 Prerequisites
- Web server capable of serving static files (Nginx, Apache, etc.)
- No server-side processing required
- No database required
#### 2.4.2 Installation Steps
1. Clone the repository:
```bash
git clone <repository-url>
cd static-pages
```
2. Configure your web server to serve the directory:
- Set document root to the static-pages directory
- Configure directory indexing if needed
- Ensure proper MIME types are set for .html, .json, .css files
3. (Optional) Update the global header CDN URL if hosting independently:
- Replace `cdn.nhcarrigan.com/headers/index.js` with your own header script
- Update custom cursor URLs if needed
#### 2.4.3 Web Server Configuration
**Nginx Example:**
```nginx
server {
listen 80;
server_name your-domain.com;
root /path/to/static-pages;
index index.html;
location / {
try_files $uri $uri/ =404;
}
location ~* \.(json)$ {
add_header Content-Type application/json;
}
}
```
**Apache Example (.htaccess):**
```apache
DirectoryIndex index.html
Options -Indexes
<Files ~ "\\.json$">
Header set Content-Type "application/json"
</Files>
```
### 2.5 Data Management
#### 2.5.1 Books Library
Run `./books.sh` to update the book data. You may need to change the filepath the script reads from.
#### 2.5.2 Music Library
Run `./songs.sh` to update the music data. You may need to change the filepath the script reads from.
#### 2.5.3 Testimonials List
Run `./testimonials.sh` to update the testimonial data from our API.
### 2.6 Customization
#### 2.6.1 Styling
Each page uses CSS custom properties that can be overridden:
- `--foreground`: Primary foreground color
- `--background`: Primary background color
Global styles are loaded from the CDN header system. To customize:
1. Fork and host your own version of the header script
2. Update the script src in each HTML file
3. Modify CSS custom properties in your hosted version
#### 2.6.2 Adding New Pages
1. Create a new directory in the root
2. Add an `index.html` file
3. Include the global header script:
```html
<script
src="https://cdn.nhcarrigan.com/headers/index.js"
async
defer
></script>
```
4. Follow the existing HTML structure for consistency
### 2.7 System Requirements
**Client-Side:**
- Modern web browser with JavaScript enabled
- Support for ES6+ JavaScript features
- Support for CSS custom properties
**Server-Side:**
- Any static file web server (Nginx, Apache, Caddy, etc.)
- No specific server-side language requirements
- No database requirements
### 2.8 Version Control
The Application is managed using Git:
- Repository hosted on Gitea (https://git.nhcarrigan.com)
- GitHub integration available
- Standard Git workflows supported
### 2.9 Continuous Integration
CI/CD configuration files are located in `.gitea/workflows/`:
- `sonar.yml`: SonarQube code quality analysis
## 3. Legal Documentation
The Application operates under NHCarrigan's standard legal framework:
### License
This software is licensed under the [global software license](https://docs.nhcarrigan.com/#/license). Copyright is held by Naomi Carrigan.
### Privacy Policy
Privacy considerations for the Application are covered under the [global privacy policy](PRIVACY.md).
### Terms of Service
Terms of service for the Application are outlined in [TERMS.md](TERMS.md).
### Code of Conduct
All interactions with the Application's community and codebase are governed by the [Code of Conduct](https://docs.nhcarrigan.com/#/coc), referenced in [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
### Security Policy
Security reporting and handling procedures are documented in [SECURITY.md](SECURITY.md).
### Data Handling
- **Book Library**: Processes local book file metadata only
- **Music Library**: Processes local music file metadata only
- **Product Directory**: Fetches public repository information from Gitea API
- **BlueSky Service**: Collects handle requests through Discord (manual process)
- **No personal data**: The Application does not collect or store personal user data directly
This section is for expansions to our legal policies specific to the Application.
### 3.1 License
The Application is licensed under the global software license maintained by Naomi Carrigan. Full license details are available at:
- **URL**: https://docs.nhcarrigan.com/#/license
- **Copyright**: All rights reserved by Naomi Carrigan
- **Reference**: See `LICENSE.md` in the repository root
### 3.2 Privacy Policy
User privacy is governed by the global privacy policy:
- **URL**: https://docs.nhcarrigan.com/#/privacy
- **Reference**: See `PRIVACY.md` in the repository root
- **Data Collection**: The Application itself does not collect user data; however, external links may have their own privacy policies
### 3.3 Terms of Service
Usage of the Application is subject to the global terms of service:
- **URL**: https://docs.nhcarrigan.com/#/terms
- **Reference**: See `TERMS.md` in the repository root
### 3.4 Security Policy
Security-related information and vulnerability reporting:
- **Reference**: See `SECURITY.md` in the repository root
- **Contact**: For security concerns, contact via the official channels listed in the security policy
### 3.5 Third-Party Services
The Application integrates with several third-party services:
#### 3.5.1 Donation Platforms
- OpenCollective
- Patreon
- Ko-Fi
- PayPal
- CashApp
- GitHub Sponsors
- Stripe
- Twitch
- Throne
- Discord
Each platform has its own terms of service and privacy policy that users should review before proceeding with transactions.
#### 3.5.2 Content Delivery Network (CDN)
- **Service**: cdn.nhcarrigan.com
- **Purpose**: Global header, navigation, and styling
- **Data Handling**: Standard CDN caching and delivery
### 3.6 User Responsibilities
Users of the Application agree to:
- Use the Application for lawful purposes only
- Respect intellectual property rights
- Not attempt to exploit, hack, or compromise the Application's security
- Follow the Code of Conduct when interacting with the community
### 3.7 Data Portability
All user-facing data in the Application is stored in JSON format and can be easily exported or migrated:
- Books data: `books/books.json`
- Music data: `music/songs.json`
- Products data: `products/data.json`
## 4. Contributing Documentation
### Getting Started
Contributors should review the [global contributing guidelines](https://docs.nhcarrigan.com/#/contributing) referenced in [CONTRIBUTING.md](CONTRIBUTING.md).
This section is for documentation related to contributing to the Application's codebase.
### Development Workflow
### 4.1 Getting Started
To contribute to the Application:
1. **Read the Contributing Guidelines**:
- Full guidelines: https://docs.nhcarrigan.com/#/contributing
- Repository reference: See `CONTRIBUTING.md`
2. **Review the Code of Conduct**:
- See `CODE_OF_CONDUCT.md` in the repository root
- Violations can be reported through official channels
3. **Set Up Development Environment**:
1. **Fork and Clone**
```bash
git clone https://github.com/your-username/Static Pages.git
cd Static Pages
# Clone the repository
git clone <repository-url>
cd static-pages
# No build tools required - edit HTML files directly
# Use any text editor or IDE
```
2. **Set Up Development Environment**
- Install required dependencies (see Technical Documentation)
- Configure data source paths for testing
- Set up environment variables if working with products functionality
### 4.2 Contribution Workflow
3. **Making Changes**
- **HTML Pages**: Edit individual `index.html` files in respective directories
- **Data Scripts**: Modify `*.sh` scripts for data generation logic
- **Deployment**: Update `sync.sh` for deployment configuration changes
1. **Fork the Repository**:
- Fork on Gitea or GitHub
- Clone your fork locally
2. **Create a Feature Branch**:
4. **Testing Changes**
```bash
# Test data generation
./books.sh
./songs.sh
./products.sh
# Test locally
python3 -m http.server 8000
git checkout -b feature/your-feature-name
```
5. **Submitting Changes**
- Create feature branch: `git checkout -b feature/your-feature`
- Commit changes with descriptive messages
- Push to your fork and create a Pull Request
- Ensure all data generation scripts work correctly
3. **Make Your Changes**:
### Code Style Guidelines
- **HTML**: Use semantic HTML5 elements, include proper meta tags
- **Shell Scripts**: Follow bash best practices, include error handling
- **JSON Data**: Ensure proper formatting and validation
- **Documentation**: Update relevant documentation for new features
- Edit HTML, CSS, or JSON files as needed
- Test locally by opening HTML files in a browser
- Ensure consistent styling and structure
### Areas for Contribution
- **UI/UX Improvements**: Enhance styling and user experience of static pages
- **Data Processing**: Improve metadata extraction and data generation scripts
- **New Features**: Add new utility pages or improve existing functionality
- **Documentation**: Expand user guides and technical documentation
- **Testing**: Add validation and testing for data generation processes
- **Accessibility**: Improve accessibility compliance across all pages
4. **Commit Your Changes**:
### Communication
- **Issues**: Report bugs and request features through GitHub Issues
- **Support**: Join the [chat server](https://chat.nhcarrigan.com) for discussion
- **Contact**: Reach out via email at `contact@nhcarrigan.com`
```bash
git add .
git commit -m "feat: description of your changes"
```
### Review Process
All Pull Requests are reviewed for:
- Code quality and adherence to project standards
- Functionality and testing
5. **Push to Your Fork**:
```bash
git push origin feature/your-feature-name
```
6. **Open a Pull Request**:
- Navigate to the original repository
- Click "New Pull Request"
- Fill out the pull request template in `.gitea/pull_request_template.yml`
### 4.3 Coding Standards
#### 4.3.1 HTML Standards
- Use HTML5 semantic elements
- Include proper DOCTYPE declaration
- Set UTF-8 charset
- Include viewport meta tag for responsive design
- Use descriptive page titles and meta descriptions
#### 4.3.2 CSS Standards
- Use CSS custom properties for theming
- Maintain responsive design principles
- Use consistent class naming conventions
- Include print styles where appropriate
- Test cross-browser compatibility
#### 4.3.3 JavaScript Standards
- Use vanilla JavaScript (no frameworks)
- Follow ES6+ standards
- Use const/let instead of var
- Include error handling where appropriate
- Keep functions small and focused
- Comment complex logic
#### 4.3.4 JSON Data Standards
- Maintain consistent schema within each data file
- Use proper JSON formatting (validated)
- Include all required fields
- Use descriptive keys
### 4.4 Testing
Before submitting a pull request:
1. **Manual Testing**:
- Open each modified HTML file in multiple browsers
- Test on both desktop and mobile viewports
- Verify all links work correctly
- Ensure JSON data loads properly
2. **Validation**:
- Validate HTML using W3C validator
- Validate JSON syntax using a JSON validator
- Check CSS for syntax errors
3. **Cross-Browser Testing**:
- Test in Chrome/Chromium
- Test in Firefox
- Test in Safari (if available)
- Test in Edge
### 4.5 Issue Reporting
Use the issue templates in `.gitea/issue_template/`:
#### 4.5.1 Bug Reports
- Template: `bug_report.yaml`
- Include reproduction steps
- Provide browser and OS information
- Include screenshots if applicable
#### 4.5.2 Feature Proposals
- Template: `feature_proposal.yml`
- Describe the feature clearly
- Explain the use case
- Consider implementation impact
#### 4.5.3 Other Issues
- Template: `other.yml`
- For general inquiries or discussions
### 4.6 Pull Request Guidelines
- Fill out the pull request template completely
- Reference related issues using `#issue-number`
- Keep changes focused on a single feature or fix
- Update documentation if needed
- Respond to review feedback promptly
- Ensure CI checks pass (if applicable)
### 4.7 Communication Channels
- **GitHub Issues**: For bug reports and feature requests
- **Chat Server**: http://chat.nhcarrigan.com
- **Email**: contact@nhcarrigan.com
- **Pull Request Discussions**: For code-specific conversations
### 4.8 Areas for Contribution
#### 4.8.1 High Priority
- Accessibility improvements
- Cross-browser compatibility fixes
- Performance optimizations
- Documentation updates
- Security considerations
- Compatibility with existing deployment process
#### 4.8.2 Medium Priority
- New page additions
- Enhanced filtering/search features
- Visual design improvements
- Mobile experience enhancements
#### 4.8.3 Low Priority
- Additional data entries (books, music, etc.)
- Minor styling tweaks
- Code refactoring
### 4.9 Recognition
Contributors are recognized through:
- Git commit history
- Pull request acknowledgments
- Potential testimonial features for significant contributions
### 4.10 Development Tools
Recommended tools for contributing:
- **Editors**: VS Code, Sublime Text, Atom, or any text editor
- **Browser DevTools**: Chrome DevTools, Firefox Developer Tools
- **Validators**: W3C HTML Validator, JSONLint
- **Version Control**: Git (command line or GUI)
### 4.11 Local Development
To run locally:
1. **Simple HTTP Server (Python)**:
```bash
python -m http.server 8000
# Visit http://localhost:8000
```
2. **Simple HTTP Server (Node.js)**:
```bash
npx http-server -p 8000
# Visit http://localhost:8000
```
3. **VS Code Live Server Extension**:
- Install Live Server extension
- Right-click HTML file ā†’ "Open with Live Server"
### 4.12 Commit Message Guidelines
Follow conventional commit format:
- `feat:` New features
- `fix:` Bug fixes
- `docs:` Documentation changes
- `style:` Code formatting (no logic changes)
- `refactor:` Code refactoring
- `test:` Test additions or updates
- `chore:` Build process or tooling changes
Example:
```
feat: add search functionality to testimonials page
- Implement client-side search filtering
- Add search input with clear button
- Update styling for search controls
```
---
## Appendix A: Page-Specific Technical Details
### Books Page
- **Data Source**: `books/books.json`
- **JavaScript Functions**:
- `loadBooks(books)`: Initializes the book list
- `filterBooks(author, title)`: Filters books by author and/or title
- `updateTable(books)`: Renders the book table
- **Current Count**: 1,210 books
### Music Page
- **Data Source**: `music/songs.json`
- **JavaScript Functions**:
- `loadSongs(songs)`: Initializes the song list
- `filterSongs(artist, title)`: Filters songs by artist and/or title
- `updateTable(songs)`: Renders the song table
### Products Page
- **Data Source**: `products/data.json`
- **JavaScript Functions**:
- `loadProducts(products)`: Processes and displays products by category
- `titleCase(name)`: Converts kebab-case to Title Case
- **Categories**: public, private, games, archived
- **Current Count**: ~50 products
### Testimonials Page
- **Data Format**: Static HTML cards generated from source
- **Styling Features**:
- Screen-optimized and print-optimized views
- Responsive card layout
- Chronological ordering
- **Submission**: Via web form at `https://forms.nhcarrigan.com/form/M_GrmqASymmO744axMOmu2LaMAaT5F0LmdVcU2c8-gQ`
---
**Document Version**: 1.0
**Last Updated**: 2025-10-29
**Maintained By**: Naomi Carrigan
**Contact**: contact@nhcarrigan.com
src/content/docs/projects/sybil.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Sybil
---
Sybil (hereinafter the "Application") is a Discord bot that syndicates forum threads to an indexable website and generates help articles based on resolved conversations.
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/projects/tessara.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Tessara
---
Tessara (hereinafter the "Application") is a Discord bot that allows you to collect and use trading cards that are actually conversation starters.
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/projects/thalassa.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Thalassa
---
Thalassa (hereinafter the "Application") is a rich presence application for Linux.
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/projects/theodora.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Theodora
---
Theodora (hereinafter the "Application") is a Discord bot that generates 100 days of code reminders.
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/projects/thessalia.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Thessalia
---
Thessalia (hereinafter the "Application") is an RPG game on Discord
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/projects/typescript-config.md
+313
View File
@@ -0,0 +1,313 @@
---
title: TypeScript Config
---
TypeScript Config (hereinafter the "Application") is a shareable TypeScript compiler configuration package designed to enforce strict type checking and consistent coding standards across multiple TypeScript projects. The Application provides a pre-configured `tsconfig.json` that can be extended by other projects to maintain code quality and catch potential errors during development.
## 1. User Documentation
This section is for those interacting with a live instance of the Application.
### 1.1 Overview
The Application is a published npm package (`@nhcarrigan/typescript-config`) that provides a standardized TypeScript configuration. It enforces strict typing rules and modern ECMAScript standards to improve code quality and maintainability.
### 1.2 Installation
To install the Application in your project, use the following command:
```bash
npm i @nhcarrigan/typescript-config typescript
```
Or with pnpm:
```bash
pnpm add @nhcarrigan/typescript-config typescript
```
### 1.3 Usage
After installation, extend the Application's configuration in your project's `tsconfig.json` file:
```json
{
"extends": "@nhcarrigan/typescript-config",
"compilerOptions": {
"rootDir": "./src",
"outDir": "./prod"
}
}
```
**Important Notes:**
- You must specify `rootDir` and `outDir` in your project's `tsconfig.json` as these are not set by default in version 4.0.0 and above
- Set these directories to match your project's structure
- The Application is compatible with TypeScript 5 and above
### 1.4 Configuration Features
The Application provides the following compiler options:
#### Target and Module System
- **Target**: ES2022 - Compiles code to ECMAScript 2022 standard
- **Module**: ES2022 - Uses ES2022 module system
- **Module Resolution**: Node - Uses Node.js module resolution strategy
#### Type Safety
- **Strict Mode**: Enabled - Enforces all strict type-checking options
- **Exact Optional Property Types**: Enabled - Distinguishes between `undefined` and absent properties
- **No Unchecked Indexed Access**: Enabled - Adds `undefined` to index signature results
- **No Implicit Returns**: Enabled - Ensures functions return values consistently
#### Code Quality
- **No Unreachable Code**: Disallowed - Prevents dead code
- **No Unused Labels**: Disallowed - Prevents unused labels
- **No Fallthrough Cases in Switch**: Enabled - Requires explicit fallthrough in switch statements
- **No Implicit Override**: Enabled - Requires explicit `override` keyword
- **No Unused Locals**: Enabled - Reports unused local variables
- **No Unused Parameters**: Enabled - Reports unused function parameters
#### Interoperability
- **ES Module Interop**: Enabled - Improves compatibility with CommonJS modules
- **Skip Lib Check**: Enabled - Skips type checking of declaration files
- **Force Consistent Casing in Filenames**: Enabled - Ensures case-sensitive file imports
### 1.5 Package Information
- **Version**: 4.0.0
- **NPM Package**: [@nhcarrigan/typescript-config](https://www.npmjs.com/package/@nhcarrigan/typescript-config)
- **Author**: Naomi Carrigan
- **License**: [Global Software License](https://docs.nhcarrigan.com/#/license)
### 1.6 Support and Feedback
- **Issues**: Report bugs at [Codeberg Issues](https://codeberg.org/naomi-lgbt/typescript-config/issues)
- **Contact**: Available via [Chat Server](http://chat.nhcarrigan.com) or email at `contact@nhcarrigan.com`
## 2. Technical Documentation
This section is for those interested in running their own instance of the Application.
### 2.1 Project Structure
The Application has a minimal structure focused on distributing a TypeScript configuration:
```
typescript-config/
ā”œā”€ā”€ src/
ā”‚ ā””ā”€ā”€ index.ts # Test file for validating configuration
ā”œā”€ā”€ tsconfig.json # The main configuration file
ā”œā”€ā”€ package.json # Package metadata and dependencies
ā””ā”€ā”€ [documentation files] # README, LICENSE, CONTRIBUTING, etc.
```
### 2.2 Source Code
#### Configuration File (tsconfig.json:1)
The main configuration file exports the following compiler options:
```json
{
"compilerOptions": {
"target": "ES2022",
"module": "ES2022",
"moduleResolution": "Node",
"allowUnreachableCode": false,
"allowUnusedLabels": false,
"exactOptionalPropertyTypes": true,
"noFallthroughCasesInSwitch": true,
"noImplicitOverride": true,
"noImplicitReturns": true,
"noUncheckedIndexedAccess": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
}
}
```
#### Test File (src/index.ts:1)
The source directory contains a minimal test file used to validate that the configuration compiles correctly:
```typescript
(async () => {
console.log("just testing!");
})();
```
This file serves as a smoke test to ensure the TypeScript configuration is valid.
### 2.3 Development Setup
#### Prerequisites
- Node.js version 20
- pnpm version 9
- TypeScript >= 5.5.2 (peer dependency)
#### Local Development
1. Clone the repository:
```bash
git clone git@codeberg.org:naomi-lgbt/typescript-config.git
cd typescript-config
```
2. Install dependencies:
```bash
pnpm install
```
3. Run tests:
```bash
pnpm test
```
The test script runs the TypeScript compiler with specific `rootDir` and `outDir` settings to validate the configuration.
### 2.4 Build and Test Process
The Application uses a simple test script defined in package.json:6:
```bash
tsc --rootDir './src' --outDir './prod' && echo 'build appears valid!'
```
This command:
1. Compiles TypeScript files from the `src` directory
2. Outputs compiled JavaScript to the `prod` directory
3. Confirms successful compilation with a success message
### 2.5 Publishing
The Application is published to npm under the package name `@nhcarrigan/typescript-config`. The main entry point is the `tsconfig.json` file itself (as specified in package.json:5).
### 2.6 Version History
The current version is 4.0.0, which introduced breaking changes:
- Removed default `rootDir` and `outDir` settings
- Users must now explicitly set these in their project's `tsconfig.json`
- This change resolves incompatibilities with certain package managers
### 2.7 Design Decisions
The configuration emphasizes:
1. **Strict Type Checking**: All strict options are enabled to catch potential errors at compile time
2. **Modern JavaScript**: Targets ES2022 for modern language features
3. **Code Quality**: Enforces best practices like no unused variables, no unreachable code
4. **Flexibility**: Allows projects to specify their own directory structure (rootDir/outDir)
## 3. Legal Documentation
This section is for expansions to our legal policies specific to the Application.
### 3.1 License
The Application is licensed under the [Global Software License](https://docs.nhcarrigan.com/#/license). Copyright is held by Naomi Carrigan.
See LICENSE.md for full license details.
### 3.2 Terms of Service
Users of the Application are subject to the global Terms of Service available at [https://docs.nhcarrigan.com/#/terms](https://docs.nhcarrigan.com/#/terms).
See TERMS.md for reference.
### 3.3 Privacy Policy
The Application does not collect or transmit any user data. For general privacy policies, refer to [https://docs.nhcarrigan.com/#/privacy](https://docs.nhcarrigan.com/#/privacy).
See PRIVACY.md for reference.
### 3.4 Security Policy
Security vulnerabilities should be reported according to the guidelines at [https://docs.nhcarrigan.com/#/security](https://docs.nhcarrigan.com/#/security).
See SECURITY.md for reference.
### 3.5 Intellectual Property
The Application's configuration is an original work created by Naomi Carrigan. The specific combination of TypeScript compiler options represents curated decisions for code quality and safety.
## 4. Contributing Documentation
This section is for documentation related to contributing to the Application's codebase.
### 4.1 Contributing Guidelines
Comprehensive contributing guidelines are available at [https://docs.nhcarrigan.com/#/contributing](https://docs.nhcarrigan.com/#/contributing).
See CONTRIBUTING.md for reference.
### 4.2 Code of Conduct
Before interacting with the community, please review the Code of Conduct available in CODE_OF_CONDUCT.md.
### 4.3 How to Contribute
#### Reporting Issues
If you encounter bugs or have feature requests:
1. Check existing issues at [Codeberg Issues](https://codeberg.org/naomi-lgbt/typescript-config/issues)
2. Create a new issue with a clear description
3. Include TypeScript version and package manager information
#### Submitting Changes
1. Fork the repository
2. Create a feature branch
3. Make your changes to the configuration
4. Test that the configuration compiles correctly (`pnpm test`)
5. Submit a Pull Request with a clear description of changes
6. Await review from maintainers
#### Configuration Changes
When proposing changes to the TypeScript configuration:
- Explain the rationale for the change
- Document any breaking changes
- Consider backward compatibility
- Test with various TypeScript projects to ensure compatibility
### 4.4 Development Workflow
1. Clone the repository
2. Create a branch for your changes
3. Modify `tsconfig.json` as needed
4. Run `pnpm test` to validate changes
5. Update documentation if necessary
6. Commit with clear, descriptive messages
7. Submit a Pull Request
### 4.5 Testing Changes
To test configuration changes:
1. Make modifications to `tsconfig.json`
2. Run the test script: `pnpm test`
3. Test in a real project by linking locally:
```bash
# In this package directory
pnpm link
# In your test project
pnpm link @nhcarrigan/typescript-config
```
4. Verify the configuration works as expected
### 4.6 Repository Information
- **Repository**: [https://codeberg.org/naomi-lgbt/typescript-config](https://codeberg.org/naomi-lgbt/typescript-config)
- **Issue Tracker**: [https://codeberg.org/naomi-lgbt/typescript-config/issues](https://codeberg.org/naomi-lgbt/typescript-config/issues)
- **Git URL**: `git@codeberg.org:naomi-lgbt/typescript-config.git`
### 4.7 Contact
For questions about contributing:
- Join the [Chat Server](http://chat.nhcarrigan.com)
- Email: `contact@nhcarrigan.com`
src/content/docs/projects/verena.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Verena
---
Verena (hereinafter the "Application") is a Discord bot that allows identity and age verification.
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/projects/vitalia.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Vitalia
---
Vitalia (hereinafter the "Application") is a full-featured nutrition tracker with community-driven nutrient data.
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/projects/vivienne.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Vivienne
---
Vivienne (hereinafter the "Application") is an RSS feed reader/management site.
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/projects/vscode-themes.md
+330
View File
@@ -0,0 +1,330 @@
---
title: Naomi's VSCode Themes
---
Naomi's VSCode Themes (hereinafter the "Application") is a Visual Studio Code extension that provides a curated collection of custom color themes designed to enhance the coding experience with aesthetically pleasing color schemes. The Application currently offers four distinct themes: Ocean Breeze, Sakura Dreams, Sakura Dreams (Dark), and Trans Pride.
## 1. User Documentation
This section is for those interacting with a live instance of the Application.
### 1.1 Overview
Naomi's Themes is a VSCode extension that provides custom color themes for your code editor. Each theme has been carefully crafted with specific color palettes to create visually appealing and comfortable coding environments.
### 1.2 Available Themes
The Application includes the following themes:
- **Ocean Breeze**: A dark theme featuring soothing teal and cyan colors reminiscent of ocean waves, designed for extended coding sessions with reduced eye strain
- **Sakura Dreams**: A light theme inspired by cherry blossoms with soft, pastel colors
- **Sakura Dreams (Dark)**: A dark variant of the Sakura Dreams theme, maintaining the cherry blossom aesthetic while providing a darker background
- **Trans Pride**: A light theme celebrating trans pride with a carefully selected color palette
### 1.3 Installation
1. Open Visual Studio Code
2. Navigate to the Extensions view (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for "Naomi's Themes" by nhcarrigan
4. Click "Install"
### 1.4 Activating a Theme
After installation:
1. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
2. Type "Preferences: Color Theme"
3. Select your desired theme from the list:
- Ocean Breeze
- Sakura Dreams
- Sakura Dreams (Dark)
- Trans Pride
### 1.5 Requirements
- Visual Studio Code version 1.96.4 or higher
### 1.6 Support and Feedback
If you encounter any issues or have feedback:
- Open an issue at: https://git.nhcarrigan.com/nhcarrigan/vscode-themes/issues
- Contact via Chat Server: http://chat.nhcarrigan.com
- Email: contact@nhcarrigan.com
## 2. Technical Documentation
This section is for those interested in running their own instance of the Application.
### 2.1 Architecture
The Application is structured as a standard VSCode extension with the following components:
- **Theme Definitions**: JSON files located in the `themes/` directory, each defining color schemes for UI elements and syntax highlighting
- **Extension Manifest**: `package.json` containing metadata and theme contributions
- **Assets**: `icon.png` for the extension icon
### 2.2 Project Structure
```
vscode-themes/
ā”œā”€ā”€ themes/
ā”‚ ā”œā”€ā”€ ocean-breeze.json
ā”‚ ā”œā”€ā”€ sakura-dreams.json
ā”‚ ā”œā”€ā”€ sakura-dreams-dark.json
ā”‚ ā””ā”€ā”€ trans-pride.json
ā”œā”€ā”€ package.json
ā”œā”€ā”€ icon.png
ā”œā”€ā”€ README.md
ā”œā”€ā”€ LICENSE.md
ā”œā”€ā”€ CONTRIBUTING.md
ā”œā”€ā”€ CODE_OF_CONDUCT.md
ā”œā”€ā”€ PRIVACY.md
ā”œā”€ā”€ TERMS.md
ā””ā”€ā”€ SECURITY.md
```
### 2.3 Local Development Setup
#### Prerequisites
- Node.js and npm installed
- Visual Studio Code installed
- vsce (Visual Studio Code Extension Manager) installed globally
#### Setup Steps
1. Clone the repository:
```bash
git clone https://git.nhcarrigan.com/nhcarrigan/vscode-themes.git
cd vscode-themes
```
2. Install vsce if not already installed:
```bash
npm install -g @vscode/vsce
```
3. Package the extension:
```bash
npm run package
```
4. Install the packaged extension in VSCode:
- Open VSCode
- Go to Extensions view
- Click the "..." menu
- Select "Install from VSIX..."
- Choose the generated `.vsix` file
### 2.4 Creating a Theme
Each theme is defined in a JSON file with the following structure:
```json
{
"name": "Theme Name",
"type": "dark" or "light",
"colors": {
// UI element colors
},
"tokenColors": [
// Syntax highlighting rules
]
}
```
Key sections:
- **colors**: Defines colors for editor UI elements (background, foreground, sidebar, statusbar, etc.)
- **tokenColors**: Array of rules defining syntax highlighting colors based on TextMate scopes
For example, see `themes/ocean-breeze.json` at lines 1-373.
### 2.5 Building and Packaging
The package script is configured in `package.json` at lines 38-39:
```bash
npm run package
```
This command:
- Packages the extension into a `.vsix` file
- Sets the base content and images URLs to the repository
### 2.6 Publishing
The extension is published by nhcarrigan to the VSCode Marketplace. The publisher configuration is defined in `package.json` at line 10.
### 2.7 Version Management
Current version: 2.2.0 (as defined in `package.json` at line 5)
Version history (from git commits):
- 2.2.0: Current release
- 2.1.0: Added dark mode and updated source links
- 2.0.0: Major version update
## 3. Legal Documentation
This section is for expansions to our legal policies specific to the Application.
### 3.1 License
The Application is licensed under Naomi Carrigan's global software license, available at: https://docs.nhcarrigan.com/#/license
Copyright is held by Naomi Carrigan.
Reference: `LICENSE.md` at lines 1-5
### 3.2 Privacy Policy
The Application adheres to the privacy policy documented at: https://docs.nhcarrigan.com/#/privacy
As a VSCode theme extension, the Application:
- Does not collect any user data
- Does not transmit any information externally
- Operates entirely locally within VSCode
Reference: `PRIVACY.md` at lines 1-3
### 3.3 Terms of Service
The Application is governed by the Terms of Service available at: https://docs.nhcarrigan.com/#/terms
Reference: `TERMS.md` at lines 1-3
### 3.4 Security Policy
Security policies and vulnerability reporting procedures are documented in `SECURITY.md`.
### 3.5 Intellectual Property
All themes, color schemes, and design elements are copyright of Naomi Carrigan. The theme names "Ocean Breeze," "Sakura Dreams," and "Trans Pride" are part of this intellectual property.
## 4. Contributing Documentation
This section is for documentation related to contributing to the Application's codebase.
### 4.1 Contributing Guidelines
Complete contributing guidelines are available at: https://docs.nhcarrigan.com/#/contributing
Reference: `CONTRIBUTING.md` at lines 1-3
### 4.2 Code of Conduct
Before participating in the project, please review the Code of Conduct at: https://git.nhcarrigan.com/nhcarrigan/vscode-themes/src/branch/main/CODE_OF_CONDUCT.md
The project maintains a welcoming and inclusive environment for all contributors.
Reference: `README.md` at lines 13-15
### 4.3 How to Contribute
#### Reporting Issues
1. Check existing issues at: https://git.nhcarrigan.com/nhcarrigan/vscode-themes/issues
2. Create a new issue with:
- Clear description of the problem or suggestion
- Steps to reproduce (for bugs)
- Expected vs. actual behavior
- VSCode version and operating system
#### Submitting Pull Requests
1. Fork the repository
2. Create a feature branch from `main`
3. Make your changes:
- For new themes: Add a new JSON file in `themes/` directory
- For theme modifications: Edit the respective JSON file
- Update `package.json` if adding a new theme
4. Test your changes locally by packaging and installing the extension
5. Commit your changes with clear, descriptive commit messages
6. Submit a pull request to the `main` branch
7. Await review from the maintainers
#### Theme Contribution Guidelines
When contributing a new theme:
1. Ensure the theme has a unique name and aesthetic
2. Define both `colors` and `tokenColors` sections comprehensively
3. Test the theme with multiple programming languages
4. Ensure sufficient contrast for accessibility
5. Add the theme entry to `package.json` under `contributes.themes`
6. Specify the correct `uiTheme` base ("vs" for light, "vs-dark" for dark)
Example theme entry in `package.json`:
```json
{
"label": "Your Theme Name",
"uiTheme": "vs-dark",
"path": "./themes/your-theme-name.json"
}
```
Reference: `package.json` at lines 14-36
### 4.4 Development Standards
#### File Naming Conventions
- Theme files: Use kebab-case (e.g., `ocean-breeze.json`, `sakura-dreams-dark.json`)
- Theme files should be placed in the `themes/` directory
#### JSON Formatting
- Use 2-space indentation
- Ensure valid JSON syntax
- Include all required theme properties
#### Color Guidelines
- Use hex color codes (e.g., `#012a22`)
- Consider accessibility and contrast ratios
- Test colors in both day and night lighting conditions
- Document color inspiration or theme concept if applicable
### 4.5 Testing
Before submitting:
1. Package the extension locally using `npm run package`
2. Install the VSIX file in a clean VSCode instance
3. Test the theme with multiple file types:
- JavaScript/TypeScript
- Python
- Rust
- HTML/CSS
- Markdown
4. Verify UI elements (sidebar, statusbar, tabs, etc.) are properly styled
5. Check for color contrast issues
### 4.6 Release Process
Releases are managed by the project maintainer (Naomi Carrigan). The typical release process:
1. Update version in `package.json`
2. Commit version changes
3. Create a git tag for the version
4. Run `npm run package` to generate the VSIX file
5. Publish to VSCode Marketplace (maintainer only)
Recent release pattern (from git history):
- Version bumps follow semantic versioning
- Releases are tagged in git
- Each release includes descriptive commit messages
### 4.7 Community and Communication
- Issues and discussions: https://git.nhcarrigan.com/nhcarrigan/vscode-themes/issues
- Chat Server: http://chat.nhcarrigan.com
- Email: contact@nhcarrigan.com
- Homepage: https://nhcarrigan.com
### 4.8 Recognition
Contributors are valued members of the project. Significant contributions may be recognized in release notes or project documentation.
src/content/docs/projects/zephra.md
+38
View File
@@ -0,0 +1,38 @@
---
title: Zephra
---
Zephra (hereinafter the "Application") is a micro-blogging social media platform.
## 1. User Documentation
:::note
This section is coming soon!
:::
This section is for those interacting with a live instance of the Application.
## 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.
## 4. Contributing Documentation
:::note
This section is coming soon!
:::
This section is for documentation related to contributing to the Application's codebase.
src/content/docs/staff/policy-self-assessment.md
+1 -1
View File
@@ -744,7 +744,7 @@ This self-assessment tool is designed to help you evaluate your understanding an
---
**Question 103:** How do you balance individual staff judgment with consistent policy application across the team?
**Question 103:** How do you balance individual staff judgement with consistent policy application across the team?
*Your Answer:*
src/content/docs/staff/training/crisis-response.md
+1 -1
View File
@@ -234,7 +234,7 @@ Taking care of your mental health is really important. Have you considered reach
**DO:**
- Stay calm and professional
- Listen without judgment
- Listen without judgement
- Acknowledge their feelings
- Provide concrete resources
- Encourage professional help
src/content/docs/staff/training/guild-wars-2-leadership.md
+1 -1
View File
@@ -265,7 +265,7 @@ This training provides comprehensive guidance for staff members responsible for
#### 5.1.1 Unique Gaming Leadership Challenges
**Real-Time Decision Making:**
- **Quick Judgment**: Making quick decisions during dynamic game situations
- **Quick judgement**: Making quick decisions during dynamic game situations
- **Stress Management**: Managing stress during competitive or challenging activities
- **Multi-Tasking**: Coordinating multiple aspects of events or activities simultaneously
- **Adaptive Leadership**: Adjusting leadership style based on activity type and participants
test/nav.spec.ts
+79
View File
@@ -0,0 +1,79 @@
/**
* @copyright NHCarrigan
* @license Naomi's Public License
* @author Naomi Carrigan
*/
import { readFile } from "node:fs/promises";
import { readdir } from "node:fs/promises";
import { join } from "node:path";
import { describe, expect, it } from "vitest";
import { navigation } from "../src/components/navigation.ts";
import matter from "gray-matter";
type Navigation = typeof navigation;
type NavigationItem = Array<{
label: string
link: string
items?: Array<{
label: string
link: string
}>
}>
const excludedFiles = ["intro.mdx", "projects/_template.md"];
// this should recursively walk the specified directory and return a list of all files, prefixing them with nested paths.
// For example, calling walkDirectory() should return "/about/contact.md", "/about/mission.md", "/about/sustainability.md", etc.
const walkDirectory = async (directory = join(__dirname, "..", "src", "content", "docs"), prefix = ""): Promise<Array<string>> => {
const filesAndDirectories = await readdir(directory, { withFileTypes: true });
const pages = [];
for (const fileOrDirectory of filesAndDirectories) {
if (fileOrDirectory.isDirectory()) {
pages.push(...(await walkDirectory(join(directory, fileOrDirectory.name), join(prefix, fileOrDirectory.name))));
} else {
pages.push(join(prefix, fileOrDirectory.name));
}
}
return pages;
}
const flattenNavigation = (navigation: Navigation | NavigationItem): Array<{ label: string; link: string }> => {
const items: Array<{ label: string; link: string }> = [];
for (const item of navigation) {
if ("items" in item && item.items) {
items.push(...flattenNavigation(item.items as NavigationItem));
} else {
items.push({ label: item.label, link: item.link });
}
}
return items;
}
describe("navigation", () => {
it("should include all pages", async () => {
expect.hasAssertions();
let pages = await walkDirectory();
pages = pages.filter((page) => !excludedFiles.includes(page));
const flattenedNavigation = flattenNavigation(navigation);
for (const page of pages) {
const pageName = page.split(".")[0];
const navItem = flattenedNavigation.find((item) => item.link === `/${pageName}`);
expect(navItem, `Navigation item not found for page ${page}`).toBeDefined();
}
});
it("should use page titles as navigation item labels", async () => {
expect.hasAssertions();
let pages = await walkDirectory();
pages = pages.filter((page) => !excludedFiles.includes(page));
const flattenedNavigation = flattenNavigation(navigation);
for (const page of pages) {
const pageName = page.split(".")[0];
const navItem = flattenedNavigation.find((item) => item.link === `/${pageName}`);
const pageContent = await readFile(join(__dirname, "..", "src", "content", "docs", page), "utf-8");
const { data } = matter(pageContent);
expect(navItem?.label, `Navigation item label for ${pageName} is not correct`).toBe(data.title);
}
});
});
test/projects.spec.ts
+71
View File
@@ -0,0 +1,71 @@
/**
* @copyright NHCarrigan
* @license Naomi's Public License
* @author Naomi Carrigan
*/
import { readFile } from "node:fs/promises";
import { readdir } from "node:fs/promises";
import { join } from "node:path";
import { describe, expect, it } from "vitest";
import matter from "gray-matter";
interface Project {
avatar?: string;
category: string;
description: string;
name: string;
premium: boolean;
url?: string;
wip: boolean;
}
const getProjects = async(): Promise<Array<Project>> => {
const request = await fetch("https://data.nhcarrigan.com/projects.json");
const data = await request.json();
return data as Array<Project>;
};
const projectNameMap: Record<string, string> = {
"Naomi's Blog": "blog",
"NHCarrigan Documentation": "docs",
"Naomi's VSCode Themes": "vscode-themes",
"Artists4Palestine Bot": "a4p-bot",
"ESLint Config": "eslint-config",
"Naomi's Adventure I: An Isekai Story": "naomis-adventure-i",
};
const excludedProjects = new Set<string>([
"Translation Service",
"Gitea"
]);
const convertTitleCaseToKebabCase = (string_: string): string => {
return string_.toLowerCase().replace(/\s+/g, "-").replaceAll(/[:']/g, "");
};
describe("projects documentation", () => {
it("should include all public projects", async() => {
expect.hasAssertions();
const projects = await getProjects();
const docs = await readdir(join(__dirname, "..", "src", "content", "docs", "projects"));
for (const project of projects) {
if (excludedProjects.has(project.name)) {
continue;
}
const page = docs.find((d) => {
return project.name in projectNameMap
? d.split(".")[0] === projectNameMap[project.name]
: d.split(".")[0] === convertTitleCaseToKebabCase(project.name);
});
expect(page, `Page not found for project ${project.name}`).toBeDefined();
const content = await readFile(join(__dirname, "..", "src", "content", "docs", "projects", page!), "utf-8");
const { data } = matter(content);
expect(data.title, `Title not found for project ${project.name}`).toBeDefined();
expect(data.title, `Title for project ${project.name} is not correct`).toBe(project.name);
if (project.wip) {
continue;
}
expect(content).not.toMatch(/:::note\nThis section is coming soon!\n:::/);
}
});
});