nhcarrigan/ephemere
9
0
Fork 0
generated from nhcarrigan/template
Code Issues Pull Requests Actions Releases Activity

docs: add data file documentation and fix data path resolution

Browse Source 
All Python cohort scripts now use DATA_DIR = Path(__file__).parent.parent.parent / "data"
to correctly resolve the repo-root data/ directory regardless of the working directory
set by run.sh. All TypeScript scripts have expanded JSDoc headers documenting data file
requirements and environment variables.
This commit is contained in:
Naomi Carrigan
2026-02-23 15:42:03 -08:00
parent 4fdb5d06f1
commit a40188413a
39 changed files with 424 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files
typescript/src/crowdin/clearHiddenTranslations.ts
+11
View File
@@ -1,4 +1,15 @@
/**
* @file Delete hidden/outdated translations from a Crowdin project.
* Reads a list of string IDs from data/crowdin-strings.json, checks which
* have already been processed via the log file, and deletes translations
* for unprocessed strings across all active languages in parallel.
* Data files (place in data/):
* - crowdin-strings.json String IDs to clear (from crowdin/writeData.ts)
* - crowdin-strings-hidden.txt Log of already-processed string IDs
* Env vars:
* CROWDIN_PROJECT_ID - Crowdin project numeric ID
* CROWDIN_API_URL - Base URL of the Crowdin API
* CROWDIN_TOKEN - Crowdin personal access token.
* @copyright NHCarrigan
* @license Naomi's Public License
* @author Naomi Carrigan
typescript/src/crowdin/reapplyTranslations.ts
+8
View File
@@ -1,4 +1,12 @@
/**
* @file Trigger a pre-translation run on a Crowdin project and wait for completion.
* Fetches all active languages and files, submits a pre-translation request,
* and polls for progress every 5 seconds until it reaches 100%%.
* Data files: None
* Env vars:
* CROWDIN_PROJECT_ID - Crowdin project numeric ID
* CROWDIN_API_URL - Base URL of the Crowdin API
* CROWDIN_TOKEN - Crowdin personal access token.
* @copyright NHCarrigan
* @license Naomi's Public License
* @author Naomi Carrigan
typescript/src/discord/cycThreads.ts
+6
View File
@@ -1,4 +1,10 @@
/**
* @file Create discussion threads for CYC talk submissions in a Discord channel.
* Iterates over a hardcoded list of talk titles and speakers and creates a
* Discord forum thread for each one. Update the data array and CHANNEL_ID before running.
* Data files: None (talk data is hardcoded in the script)
* Env vars:
* DISCORD_TOKEN - Bot token for the Discord API.
* @copyright NHCarrigan
* @license Naomi's Public License
* @author Naomi Carrigan
typescript/src/discord/guildCount.ts
+10
View File
@@ -1,4 +1,14 @@
/**
* @file Count and categorise all Discord servers a user belongs to.
* Uses the Discord OAuth2 PKCE flow with a local callback server to authenticate,
* then fetches and categorises all guilds (owned, admin, moderated, partnered,
* verified, community, discoverable) and serves an HTML dashboard on localhost.
* Data files: None
* Env vars:
* DISCORD_CLIENT_ID - OAuth2 application client ID
* DISCORD_CLIENT_SECRET - OAuth2 application client secret (optional)
* DISCORD_REDIRECT_URI - OAuth2 redirect URI (default: http://127.0.0.1:8721/callback)
* DISCORD_SCOPES - OAuth2 scopes (default: identify guilds).
* @copyright NHCarrigan
* @license Naomi's Public License
* @author Naomi Carrigan
typescript/src/discourse/bulkUpdateCategories.ts
+8
View File
@@ -1,4 +1,12 @@
/**
* @file Set auto-close settings on all Discourse forum categories.
* Fetches all categories and subcategories and enables auto-close based on
* last post (672 hours / 28 days) for each one.
* Data files: None
* Env vars:
* DISCOURSE_URL - Base URL of the Discourse instance
* DISCOURSE_API_KEY - Discourse API key
* DISCOURSE_API_USERNAME - Discourse API username.
* @copyright NHCarrigan
* @license Naomi's Public License
* @author Naomi Carrigan
typescript/src/discourse/closeOldTopics.ts
+7
View File
@@ -1,4 +1,11 @@
/**
* @file Close inactive Discourse topics that have had no activity for 28+ days.
* Skips topics older than 6 months (already archived) and any that are already closed.
* Data files: None
* Env vars:
* DISCOURSE_URL - Base URL of the Discourse instance
* DISCOURSE_API_KEY - Discourse API key
* DISCOURSE_API_USERNAME - Discourse API username.
* @copyright NHCarrigan
* @license Naomi's Public License
* @author Naomi Carrigan
typescript/src/gitea/deleteFromAllRepos.ts
+6
View File
@@ -1,4 +1,10 @@
/**
* @file Delete a file from every repository across all nhcarrigan Gitea orgs.
* Prompts for the file path to delete, then removes it from every repo
* across nhcarrigan, nhcarrigan-private, and nhcarrigan-games.
* Data files: None
* Env vars:
* GITEA_TOKEN - Gitea personal access token with repo write permissions.
* @copyright NHCarrigan
* @license Naomi's Public License
* @author Naomi Carrigan
typescript/src/gitea/uploadToAllRepos.ts
+7
View File
@@ -1,4 +1,11 @@
/**
* @file Upload a file from data/ to every repository across all nhcarrigan Gitea orgs.
* Prompts for the local filename and destination path, then creates or updates
* the file in every repo across nhcarrigan, nhcarrigan-private, and nhcarrigan-games.
* Data files (place in data/):
* - Any file to upload (prompted interactively)
* Env vars:
* GITEA_TOKEN - Gitea personal access token with repo write permissions.
* @copyright NHCarrigan
* @license Naomi's Public License
* @author Naomi Carrigan
typescript/src/gitea/uploadToReposConditionally.ts
+7
View File
@@ -1,4 +1,11 @@
/**
* @file Conditionally upload a file to Gitea repos based on whether another file exists.
* Prompts for the file to upload, a condition file path, and whether to upload
* when the condition file exists or does not exist.
* Data files (place in data/):
* - Any file to upload (prompted interactively)
* Env vars:
* GITEA_TOKEN - Gitea personal access token with repo write permissions.
* @copyright NHCarrigan
* @license Naomi's Public License
* @author Naomi Carrigan
typescript/src/github/auditNpmPackages.ts
+8
View File
@@ -1,4 +1,12 @@
/**
* @file Audit npm packages across a GitHub organisation for known vulnerabilities.
* Lists all repositories in the target org, fetches each package.json, and checks
* for usage of packages in the hardcoded vulnerable package list.
* Update the vulnerable package list and orgName constant before running.
* Outputs (written to data/):
* - npm-vulnerabilities.txt Repos and packages with vulnerability findings
* Env vars:
* GITHUB_TOKEN - GitHub personal access token with org read permissions.
* @copyright NHCarrigan
* @license Naomi's Public License
* @author Naomi Carrigan
typescript/src/github/onboardMentee.ts
+8
View File
@@ -1,4 +1,12 @@
/**
* @file Onboard a new mentee to the nhcarrigan-mentorship GitHub organisation.
* Prompts for the mentee's Discord ID, full name, and GitHub username, creates
* a personal repository in the org, adds the mentee as a collaborator with
* maintain permissions, and posts a welcome message to the Discord channel.
* Data files: None
* Env vars:
* GITHUB_TOKEN - GitHub personal access token with org and repo permissions
* DISCORD_TOKEN - Bot token for the Discord API.
* @copyright NHCarrigan
* @license Naomi's Public License
* @author Naomi Carrigan
typescript/src/github/postUserStories.ts
+7
View File
@@ -1,4 +1,11 @@
/**
* @file Post user story markdown files as GitHub issue descriptions.
* Reads all markdown files from data/stories/ and updates the corresponding
* GitHub issue with that content. Filename format: {repo-name}-{issue-number}.md.
* Data files (place in data/stories/):
* - {repo-name}-{issue-number}.md User story content for each issue
* Env vars:
* GITHUB_TOKEN - GitHub personal access token with repo write permissions.
* @copyright NHCarrigan
* @license Naomi's Public License
* @author Naomi Carrigan
typescript/src/music/id3v2.ts
+6
View File
@@ -1,4 +1,10 @@
/**
* @file Tag MP3 files with ID3v2 metadata and album art for Neuro-sama tracks.
* Reads all MP3 files from the download directory, extracts the title from
* the filename, sets the artist to "Neuro-sama", and applies the cover image.
* Update the directory and cover constants before running.
* Data files: None (reads from a local directory path defined in the script)
* Env vars: None (uses eyeD3 and id3v2 CLI tools).
* @copyright NHCarrigan
* @license Naomi's Public License
* @author Naomi Carrigan
typescript/src/s3/bulkUpload.ts
+9
View File
@@ -1,4 +1,13 @@
/**
* @file Upload all files in the data/ directory to an S3-compatible bucket.
* Displays a tree of files to upload, prompts for confirmation, then uploads
* with a progress bar showing per-file status.
* Data files (place in data/):
* - All files to upload are read from the data/ directory recursively
* Env vars:
* AWS_ACCESS_KEY_ID - S3 access key
* AWS_SECRET_ACCESS_KEY - S3 secret key
* S3_ENDPOINT - S3-compatible endpoint URL.
* @copyright NHCarrigan
* @license Naomi's Public License
* @author Naomi Carrigan
typescript/src/s3/correctContentType.ts
+8
View File
@@ -1,4 +1,12 @@
/**
* @file Fix incorrect Content-Type metadata on objects in an S3-compatible bucket.
* Lists all objects, detects MIME type from extension, and re-uploads metadata
* for any file whose stored Content-Type does not match the expected type.
* Data files: None
* Env vars:
* AWS_ACCESS_KEY_ID - S3 access key
* AWS_SECRET_ACCESS_KEY - S3 secret key
* S3_ENDPOINT - S3-compatible endpoint URL.
* @copyright NHCarrigan
* @license Naomi's Public License
* @author Naomi Carrigan
typescript/src/s3/deleteContents.ts
+8
View File
@@ -1,4 +1,12 @@
/**
* @file Delete all objects from an S3-compatible bucket.
* Prompts for the bucket name, requires double confirmation (type name + yes/no),
* then lists and deletes all objects in batches with a progress bar.
* Data files: None
* Env vars:
* AWS_ACCESS_KEY_ID - S3 access key
* AWS_SECRET_ACCESS_KEY - S3 secret key
* S3_ENDPOINT - S3-compatible endpoint URL.
* @copyright NHCarrigan
* @license Naomi's Public License
* @author Naomi Carrigan
typescript/src/s3/upload.ts
+8
View File
@@ -1,4 +1,12 @@
/**
* @file Upload a single file from the data/ directory to an S3-compatible bucket.
* Prompts for the local filename and the destination path in the bucket.
* Data files (place in data/):
* - Any file to upload (prompted interactively)
* Env vars:
* AWS_ACCESS_KEY_ID - S3 access key
* AWS_SECRET_ACCESS_KEY - S3 secret key
* S3_ENDPOINT - S3-compatible endpoint URL.
* @copyright NHCarrigan
* @license Naomi's Public License
* @author Naomi Carrigan
typescript/src/security/generateReport.ts
+7
View File
@@ -1,5 +1,12 @@
/* eslint-disable max-lines -- Necessary for all of the HTML templating. */
/**
* @file Generate a public HTML security report from DefectDojo findings.
* Fetches all active, verified findings from DefectDojo and produces a styled
* HTML dashboard grouped by project with severity counts.
* Outputs (written to data/):
* - public_security_report.html HTML security report
* Env vars:
* DOJO_TOKEN - DefectDojo API token.
* @copyright NHCarrigan
* @license Naomi's Public License
* @author Naomi Carrigan