Make @forge/utils

[DVidal1205]

We have a ton of different utils.ts files scattered all over the place and many repeat/redundant copy pasted functions.

Extract all of these into a forge utils package and separated by scope. This will make maintenance easier. Work with some llms to find a deterministic way to scan the codebase for identical functions declared in multiple places - there will be quite a few.

[coderabbitai]

Coding Plan

Summary

• Create a new @forge/utils package following existing monorepo conventions with modules organized by domain (date, permissions)
• Consolidate duplicated functions (getPermsAsList, date formatters) into single canonical implementations
• Leverage existing cn() in @forge/ui rather than creating another copy, removing duplicates from guild and gemiknights apps
• Maintain backwards compatibility in @forge/api by re-exporting migrated functions

Design Choices

Design Choice 1: Where should `getPermsAsList()` live?

Options Considered:

1. Keep in @forge/api and have apps import from there
2. Move to @forge/utils as a pure utility function

Chosen Option: 2

Rationale: Move to @forge/utils because it's a pure function with no API dependencies, and its duplication in an app indicates broader usage needs.

Design Choice 2: How to handle the two different `formatDateRange()` implementations?

Options Considered:

1. Keep both with same name but different signatures, letting TypeScript differentiate
2. Rename to distinct function names that clarify their purpose

Chosen Option: 2

Rationale: Rename to formatDateSpan() (blade's version) and formatTimeRange() (club's version) for clarity and to prevent confusion.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Create @forge/utils Package Structure

Establish the new package with proper configuration files following existing monorepo conventions, and define the organizational structure for utility modules.

Task 1: Initialize Package Configuration

Set up the foundational package files following established patterns from existing packages like @forge/ui and @forge/consts.

• Create packages/utils/package.json with @forge/utils name, standard scripts, and exports supporting both root imports and wildcard submodule imports (. and ./* patterns)
• Create packages/utils/tsconfig.json extending from @forge/tsconfig/internal-package.json
• Create packages/utils/eslint.config.js extending from @forge/eslint-config/base
• Add @forge/utils as a workspace dependency in the root package.json or turbo.json if needed

Task 2: Create Date/Time Utility Module

Consolidate all date and time formatting utilities into a single module.

• Create packages/utils/src/date.ts containing consolidated date/time utilities
• Migrate formatDateTime() from apps/blade/src/lib/utils.ts
• Migrate getFormattedDate() from apps/blade/src/lib/utils.ts
• Migrate blade's formatDateRange() as formatDateSpan() from apps/blade/src/lib/utils.ts
• Migrate formatHourTime() from apps/club/src/lib/utils.ts
• Migrate club's formatDateRange() as formatTimeRange() from apps/club/src/lib/utils.ts

Task 3: Create Permissions Utility Module

Establish a dedicated module for permission-related utilities.

• Create packages/utils/src/permissions.ts with permission transformation utilities
• Migrate getPermsAsList() function, using the implementation from packages/api/src/utils.ts as the canonical source
• Import PERMISSIONS constant from @forge/consts/knight-hacks for the permission mappings

Task 4: Create Package Entry Point

Set up the main index file to provide convenient access to all utilities.

• Create packages/utils/src/index.ts with barrel exports from all utility modules
• Re-export all functions from date.ts and permissions.ts
• Ensure both import patterns work: @forge/utils (all) and @forge/utils/date (specific module)

🤖 Prompt for AI agents

Set up the new `@forge/utils` package with proper configuration and utility
modules organized by domain.

**Package Configuration:**
- Create `packages/utils/package.json` with `@forge/utils` name, following
patterns from existing `@forge` packages like `@forge/ui` and `@forge/consts`
- Configure exports to support both root imports (`.`) and wildcard submodule
imports (`./*` patterns)
- Create `packages/utils/tsconfig.json` extending from
`@forge/tsconfig/internal-package.json`
- Create `packages/utils/eslint.config.js` extending from
`@forge/eslint-config/base`
- Add `@forge/utils` as a workspace dependency in the root package.json or
turbo.json if needed

**Date/Time Utility Module (`packages/utils/src/date.ts`):**
- Migrate `formatDateTime()` from `apps/blade/src/lib/utils.ts`
- Migrate `getFormattedDate()` from `apps/blade/src/lib/utils.ts`
- Migrate blade's `formatDateRange()` function as `formatDateSpan()` from
`apps/blade/src/lib/utils.ts`
- Migrate `formatHourTime()` from `apps/club/src/lib/utils.ts`
- Migrate club's `formatDateRange()` function as `formatTimeRange()` from
`apps/club/src/lib/utils.ts`

**Permissions Utility Module (`packages/utils/src/permissions.ts`):**
- Migrate `getPermsAsList()` function using the implementation from
`packages/api/src/utils.ts` as the canonical source
- Import PERMISSIONS constant from `@forge/consts/knight-hacks` for the
permission mappings

**Package Entry Point (`packages/utils/src/index.ts`):**
- Create barrel exports re-exporting all functions from date.ts and
permissions.ts
- Ensure both import patterns work: `@forge/utils` (all utilities) and
`@forge/utils/date` (specific module)

Phase 2: Migrate Consumers and Remove Duplicates

Update all applications and packages to use the new consolidated utilities and remove redundant code.

Task 1: Update Blade App Imports

Migrate the blade app from local utilities to @forge/utils.

• Add @forge/utils as a dependency in apps/blade/package.json
• Update imports in blade components to use @forge/utils for date formatting functions
• Update imports to use @forge/utils for getPermsAsList()
• Remove migrated functions from apps/blade/src/lib/utils.ts (keep app-specific functions like getTagColor, getClassTeam, extractProcedures)

Task 2: Update Club App Imports

Migrate the club app from local utilities to @forge/utils.

• Add @forge/utils as a dependency in apps/club/package.json
• Update imports to use formatHourTime and formatTimeRange from @forge/utils
• Delete apps/club/src/lib/utils.ts entirely (all functions will be migrated)

Task 3: Remove cn() Duplicates

Eliminate redundant cn() implementations by using the existing @forge/ui export.

• Update apps/gemiknights/src/lib/utils.ts to re-export cn from @forge/ui or delete the file if cn() is the only export
• Update apps/guild/src/app/lib/util.ts to re-export cn from @forge/ui or delete the file if cn() is the only export
• Verify @forge/ui is listed as a dependency in both apps' package.json files
• Search for and update any imports of cn from local paths to use @forge/ui

Task 4: Update API Package

Remove the duplicate getPermsAsList() from the API package and import from @forge/utils.

• Add @forge/utils as a dependency in packages/api/package.json
• Update packages/api/src/utils.ts to import and re-export getPermsAsList from @forge/utils (maintains backwards compatibility for existing consumers)
• Remove the local implementation of getPermsAsList() from packages/api/src/utils.ts

🤖 Prompt for AI agents

Update all consuming apps and packages to use the new `@forge/utils` package and
remove duplicate implementations.

**Blade App Migration:**
- Add `@forge/utils` as a dependency in `apps/blade/package.json`
- Update imports in blade components to use date formatting functions
(`formatDateTime`, `getFormattedDate`, `formatDateSpan`) from `@forge/utils`
- Update imports to use `getPermsAsList()` from `@forge/utils`
- Remove migrated functions from `apps/blade/src/lib/utils.ts`, but keep
app-specific functions like `getTagColor`, `getClassTeam`, `extractProcedures`

**Club App Migration:**
- Add `@forge/utils` as a dependency in `apps/club/package.json`
- Update imports to use `formatHourTime` and `formatTimeRange` from
`@forge/utils`
- Delete `apps/club/src/lib/utils.ts` entirely (all functions are being
migrated)

**Remove cn() Duplicates:**
- In `apps/gemiknights/src/lib/utils.ts`, either re-export `cn` from `@forge/ui`
or delete the file if `cn()` is the only export
- In `apps/guild/src/app/lib/util.ts`, either re-export `cn` from `@forge/ui` or
delete the file if `cn()` is the only export
- Verify `@forge/ui` is listed as a dependency in both gemiknights and guild apps'
package.json files
- Search for and update any imports of `cn` from local paths to use `@forge/ui`

**API Package Migration:**
- Add `@forge/utils` as a dependency in `packages/api/package.json`
- Update `packages/api/src/utils.ts` to import and re-export `getPermsAsList`
from `@forge/utils` (maintains backwards compatibility)
- Remove the local implementation of `getPermsAsList()` from
`packages/api/src/utils.ts`

Phase 3: Verification and Cleanup

Ensure all migrations are complete and the codebase builds successfully.

Task 1: Verify Build and Type Checking

Confirm the entire monorepo compiles without errors.

• Run pnpm typecheck from the repository root to verify no broken imports
• Run pnpm build to ensure all packages build correctly
• Run pnpm lint to check for any import/export issues

Task 2: Document Utility Inventory

Add documentation to help developers discover available utilities.

• Add JSDoc comments to all exported functions in @forge/utils describing their purpose and usage
• Create a brief README.md in packages/utils/ listing available utility categories and common import patterns

🤖 Prompt for AI agents

Verify the migration is complete and add documentation for the new `@forge/utils`
package.

**Build and Type Verification:**
- Run `pnpm typecheck` from the repository root to verify no broken imports
- Run `pnpm build` to ensure all packages build correctly
- Run `pnpm lint` to check for any import/export issues
- Fix any errors that arise from the migration

**Documentation:**
- Add JSDoc comments to all exported functions in `@forge/utils` (in
`packages/utils/src/date.ts`, `packages/utils/src/permissions.ts`) describing
their purpose and usage
- Create a README.md in `packages/utils/` listing:
  - Available utility categories (date, permissions)
- Common import patterns (e.g., `@forge/utils` for all utilities,
`@forge/utils/date` for specific modules)
  - Brief description of key functions

Research

The monorepo contains 6 utility files totaling 759 lines and 34 exports spread across apps (blade, club, gemiknights, guild) and packages (api). Key duplications exist: cn() appears in 3 locations (though already canonically exists in @forge/ui), getPermsAsList() is duplicated between blade and api, and formatDateRange() exists with different implementations in blade and club. The existing package structure follows a consistent pattern with @forge scoping, TypeScript configs extending from shared tooling, and exports supporting both direct source imports and generated type declarations.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Set up the new `@forge/utils` package with proper configuration and utility
modules organized by domain.

**Package Configuration:**
- Create `packages/utils/package.json` with `@forge/utils` name, following
patterns from existing `@forge` packages like `@forge/ui` and `@forge/consts`
- Configure exports to support both root imports (`.`) and wildcard submodule
imports (`./*` patterns)
- Create `packages/utils/tsconfig.json` extending from
`@forge/tsconfig/internal-package.json`
- Create `packages/utils/eslint.config.js` extending from
`@forge/eslint-config/base`
- Add `@forge/utils` as a workspace dependency in the root package.json or
turbo.json if needed

**Date/Time Utility Module (`packages/utils/src/date.ts`):**
- Migrate `formatDateTime()` from `apps/blade/src/lib/utils.ts`
- Migrate `getFormattedDate()` from `apps/blade/src/lib/utils.ts`
- Migrate blade's `formatDateRange()` function as `formatDateSpan()` from
`apps/blade/src/lib/utils.ts`
- Migrate `formatHourTime()` from `apps/club/src/lib/utils.ts`
- Migrate club's `formatDateRange()` function as `formatTimeRange()` from
`apps/club/src/lib/utils.ts`

**Permissions Utility Module (`packages/utils/src/permissions.ts`):**
- Migrate `getPermsAsList()` function using the implementation from
`packages/api/src/utils.ts` as the canonical source
- Import PERMISSIONS constant from `@forge/consts/knight-hacks` for the
permission mappings

**Package Entry Point (`packages/utils/src/index.ts`):**
- Create barrel exports re-exporting all functions from date.ts and
permissions.ts
- Ensure both import patterns work: `@forge/utils` (all utilities) and
`@forge/utils/date` (specific module)
===============================================================================

Task: 2

Update all consuming apps and packages to use the new `@forge/utils` package and
remove duplicate implementations.

**Blade App Migration:**
- Add `@forge/utils` as a dependency in `apps/blade/package.json`
- Update imports in blade components to use date formatting functions
(`formatDateTime`, `getFormattedDate`, `formatDateSpan`) from `@forge/utils`
- Update imports to use `getPermsAsList()` from `@forge/utils`
- Remove migrated functions from `apps/blade/src/lib/utils.ts`, but keep
app-specific functions like `getTagColor`, `getClassTeam`, `extractProcedures`

**Club App Migration:**
- Add `@forge/utils` as a dependency in `apps/club/package.json`
- Update imports to use `formatHourTime` and `formatTimeRange` from
`@forge/utils`
- Delete `apps/club/src/lib/utils.ts` entirely (all functions are being
migrated)

**Remove cn() Duplicates:**
- In `apps/gemiknights/src/lib/utils.ts`, either re-export `cn` from `@forge/ui`
or delete the file if `cn()` is the only export
- In `apps/guild/src/app/lib/util.ts`, either re-export `cn` from `@forge/ui` or
delete the file if `cn()` is the only export
- Verify `@forge/ui` is listed as a dependency in both gemiknights and guild apps'
package.json files
- Search for and update any imports of `cn` from local paths to use `@forge/ui`

**API Package Migration:**
- Add `@forge/utils` as a dependency in `packages/api/package.json`
- Update `packages/api/src/utils.ts` to import and re-export `getPermsAsList`
from `@forge/utils` (maintains backwards compatibility)
- Remove the local implementation of `getPermsAsList()` from
`packages/api/src/utils.ts`
===============================================================================

Task: 3

Verify the migration is complete and add documentation for the new `@forge/utils`
package.

**Build and Type Verification:**
- Run `pnpm typecheck` from the repository root to verify no broken imports
- Run `pnpm build` to ensure all packages build correctly
- Run `pnpm lint` to check for any import/export issues
- Fix any errors that arise from the migration

**Documentation:**
- Add JSDoc comments to all exported functions in `@forge/utils` (in
`packages/utils/src/date.ts`, `packages/utils/src/permissions.ts`) describing
their purpose and usage
- Create a README.md in `packages/utils/` listing:
  - Available utility categories (date, permissions)
- Common import patterns (e.g., `@forge/utils` for all utilities,
`@forge/utils/date` for specific modules)
  - Brief description of key functions

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!