Skip to content

Commit 26d1b36

Browse files
muneebhashonemuneebhashone
committed
feat(tbk): add CLI tool and publishing workflows for @tbk/cli
- Introduced a new CLI tool for the TypeScript Backend Toolkit, enabling module, plugin, middleware, and seeder generation. - Created GitHub Actions workflows for publishing the CLI package to npm, including version bumping and tagging. - Added comprehensive documentation for installation, usage, and command options in the README. - Implemented necessary configurations and scripts for building and publishing the package.
1 parent 417ee23 commit 26d1b36

File tree

14 files changed

+1469
-0
lines changed

14 files changed

+1469
-0
lines changed

‎.github/workflows/publish-package.yml‎ renamed to ‎.github/workflows/publish-create-tbk-app.yml‎

File renamed without changes.

‎.github/workflows/publish-tbk-cli.yml‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# GitHub Actions workflow for publishing @tbk/cli to npm
2+
#
3+
# SETUP INSTRUCTIONS:
4+
# 1. Go to your repository Settings > Secrets and variables > Actions
5+
# 2. Click "New repository secret"
6+
# 3. Name: NPM_TOKEN
7+
# 4. Value: Your npm access token (create at https://www.npmjs.com/settings/{username}/tokens)
8+
# 5. Select "Automation" token type for CI/CD use
9+
# 6. Save the secret
10+
#
11+
# For more info: https://docs.github.com/en/actions/security-guides/encrypted-secrets
12+
13+
name: Publish @tbk/cli to npm
14+
15+
on:
16+
workflow_dispatch:
17+
inputs:
18+
version_type:
19+
description: 'Version bump type'
20+
required: true
21+
type: choice
22+
options:
23+
- patch
24+
- minor
25+
- major
26+
27+
jobs:
28+
publish:
29+
runs-on: ubuntu-latest
30+
permissions:
31+
contents: write
32+
id-token: write
33+
34+
steps:
35+
- name: Checkout repository
36+
uses: actions/checkout@v4
37+
with:
38+
fetch-depth: 0
39+
40+
- name: Setup Node.js
41+
uses: actions/setup-node@v4
42+
with:
43+
node-version: '18'
44+
45+
- name: Setup pnpm
46+
uses: pnpm/action-setup@v4
47+
48+
- name: Configure Git
49+
run: |
50+
git config --global user.name "github-actions[bot]"
51+
git config --global user.email "github-actions[bot]@users.noreply.github.com"
52+
53+
- name: Install dependencies
54+
run: pnpm install --frozen-lockfile
55+
56+
- name: Bump version in package.json
57+
id: bump-version
58+
working-directory: packages/tbk
59+
run: |
60+
# Get current version
61+
CURRENT_VERSION=$(node -p "require('./package.json').version")
62+
echo "Current version: $CURRENT_VERSION"
63+
64+
# Bump version based on input
65+
npm version ${{ inputs.version_type }} --no-git-tag-version
66+
67+
# Get new version
68+
NEW_VERSION=$(node -p "require('./package.json').version")
69+
echo "New version: $NEW_VERSION"
70+
71+
# Set output for subsequent steps
72+
echo "version=$NEW_VERSION" >> $GITHUB_OUTPUT
73+
echo "tag=tbk-cli-v$NEW_VERSION" >> $GITHUB_OUTPUT
74+
75+
- name: Get branch name
76+
id: branch
77+
run: |
78+
# Get the actual branch name from git (works for workflow_dispatch)
79+
BRANCH_NAME=$(git rev-parse --abbrev-ref HEAD)
80+
echo "branch=$BRANCH_NAME" >> $GITHUB_OUTPUT
81+
echo "Current branch: $BRANCH_NAME"
82+
83+
- name: Commit version bump
84+
run: |
85+
git add packages/tbk/package.json
86+
git commit -m "chore(@tbk/cli): bump version to ${{ steps.bump-version.outputs.version }}"
87+
git push origin ${{ steps.branch.outputs.branch }}
88+
89+
- name: Build package
90+
working-directory: packages/tbk
91+
run: pnpm build
92+
93+
- name: Publish to npm
94+
working-directory: packages/tbk
95+
env:
96+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
97+
run: |
98+
echo "//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}" > .npmrc
99+
pnpm publish --access public --no-git-checks
100+
rm .npmrc
101+
102+
- name: Create git tag
103+
run: |
104+
git tag ${{ steps.bump-version.outputs.tag }}
105+
git push origin ${{ steps.bump-version.outputs.tag }}
106+
107+
- name: Summary
108+
run: |
109+
echo "✅ Successfully published @tbk/cli@${{ steps.bump-version.outputs.version }} to npm"
110+
echo "📦 Tagged as ${{ steps.bump-version.outputs.tag }}"
111+
echo "🔗 Package: https://www.npmjs.com/package/@tbk/cli"
112+

‎packages/tbk/README.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
# @tbk/cli
2+
3+
CLI tool for TypeScript Backend Toolkit projects. Generate modules, plugins, middleware, seeders, and factories with a single command.
4+
5+
## Installation
6+
7+
This package is typically installed as a dev dependency in TypeScript Backend Toolkit projects:
8+
9+
```bash
10+
pnpm add -D @tbk/cli
11+
```
12+
13+
Or via npm:
14+
15+
```bash
16+
npm install -D @tbk/cli
17+
```
18+
19+
## Usage
20+
21+
After installation, use the `tbk` command:
22+
23+
```bash
24+
# Generate a complete module
25+
pnpm tbk generate:module <name> [--path /api/v1]
26+
27+
# Generate a plugin
28+
pnpm tbk generate:plugin <name>
29+
30+
# Generate middleware
31+
pnpm tbk generate:middleware <name>
32+
33+
# Run database seeders
34+
pnpm tbk seed [--group dev] [--only SeederName] [--fresh]
35+
36+
# Create a seeder for a module
37+
pnpm tbk make:seeder <module>/<name> [--count 5] [--unique field]
38+
39+
# Create a factory for a module
40+
pnpm tbk make:factory <module>/<name> [--model ExportName]
41+
```
42+
43+
## Commands
44+
45+
### generate:module
46+
47+
Generate a complete module with all files (dto, model, schema, services, controller, router).
48+
49+
```bash
50+
pnpm tbk generate:module user
51+
pnpm tbk generate:module product --path /api/v1
52+
```
53+
54+
**Options:**
55+
- `-p, --path <path>` - API path prefix (default: `/api`)
56+
57+
**Creates:**
58+
- `src/modules/<name>/<name>.dto.ts` - Zod schemas and TypeScript types
59+
- `src/modules/<name>/<name>.model.ts` - Mongoose model
60+
- `src/modules/<name>/<name>.schema.ts` - Request/response validation schemas
61+
- `src/modules/<name>/<name>.services.ts` - Business logic and data access
62+
- `src/modules/<name>/<name>.controller.ts` - HTTP request handlers
63+
- `src/modules/<name>/<name>.router.ts` - MagicRouter route definitions
64+
65+
### generate:plugin
66+
67+
Generate a new plugin with the standard structure.
68+
69+
```bash
70+
pnpm tbk generate:plugin cache
71+
```
72+
73+
**Creates:**
74+
- `src/plugins/<name>/index.ts` - Plugin factory and registration
75+
76+
### generate:middleware
77+
78+
Generate a new Express middleware.
79+
80+
```bash
81+
pnpm tbk generate:middleware rateLimiter
82+
```
83+
84+
**Creates:**
85+
- `src/middlewares/<name>.ts` - Middleware function
86+
87+
### seed
88+
89+
Run database seeders to populate test data.
90+
91+
```bash
92+
# Run all seeders in dev group
93+
pnpm tbk seed
94+
95+
# Run specific seeders
96+
pnpm tbk seed --only UserSeeder,ProductSeeder
97+
98+
# Fresh run (drops collections)
99+
pnpm tbk seed --fresh
100+
101+
# Dry run (no writes)
102+
pnpm tbk seed --dry-run
103+
104+
# Force run in production
105+
pnpm tbk seed --force
106+
```
107+
108+
**Options:**
109+
- `-g, --group <group>` - Group to run (base|dev|test|demo) (default: `dev`)
110+
- `--only <names>` - Comma-separated seeder names
111+
- `--fresh` - Drop involved collections before seeding
112+
- `--force` - Force run in production
113+
- `--dry-run` - Do not write, only log actions
114+
- `--seed <number>` - Random seed for data generation (default: `1`)
115+
- `--no-transaction` - Disable transactions
116+
117+
### make:seeder
118+
119+
Scaffold a new seeder for a module. Automatically detects model fields and dependencies.
120+
121+
```bash
122+
pnpm tbk make:seeder user/User
123+
pnpm tbk make:seeder product/Product --count 10 --unique slug
124+
```
125+
126+
**Options:**
127+
- `-c, --count <number>` - Default count for dev/test (default: `5`)
128+
- `-u, --unique <field>` - Unique field to upsert by
129+
- `-d, --depends-on <names>` - Comma-separated additional dependencies
130+
- `--model <export>` - Model export name when not default
131+
132+
**Creates:**
133+
- `src/modules/<module>/seeders/<Name>Seeder.ts`
134+
135+
**Note:** The seeder must be manually registered in `src/seeders/registry.ts`.
136+
137+
### make:factory
138+
139+
Scaffold a new factory for a module. Automatically detects model fields and create functions.
140+
141+
```bash
142+
pnpm tbk make:factory user/User
143+
pnpm tbk make:factory product/Product --model ProductModel --use service
144+
```
145+
146+
**Options:**
147+
- `--model <export>` - Model export name when not default
148+
- `--use <service|model>` - Prefer using service create function when present (default: `service`)
149+
- `--id-type <string|objectId>` - Hint for _id type when ambiguous
150+
151+
**Creates:**
152+
- `src/modules/<module>/factories/<name>.factory.ts`
153+
154+
## Requirements
155+
156+
- Node.js >= 18.0.0
157+
- TypeScript Backend Toolkit project structure
158+
- MongoDB connection (for seed command)
159+
160+
## How It Works
161+
162+
The CLI tool uses dynamic imports and model introspection to:
163+
- Analyze Mongoose schemas to detect fields, types, and relationships
164+
- Generate type-safe code following project patterns
165+
- Ensure consistency with existing codebase structure
166+
167+
## Development
168+
169+
```bash
170+
# Build the package
171+
pnpm build
172+
173+
# Watch mode
174+
pnpm dev
175+
176+
# Type check
177+
pnpm typecheck
178+
```
179+
180+
## License
181+
182+
MIT
183+
184+
## Links
185+
186+
- [Main Toolkit Repository](https://github.com/muneebhashone/typescript-backend-toolkit)
187+
- [Report Issues](https://github.com/muneebhashone/typescript-backend-toolkit/issues)
188+

‎packages/tbk/package.json‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
{
2+
"name": "@tbk/cli",
3+
"version": "0.0.1",
4+
"description": "CLI tool for TypeScript Backend Toolkit - generate modules, plugins, middleware, seeders, and factories",
5+
"type": "module",
6+
"bin": {
7+
"tbk": "./dist/cli.js"
8+
},
9+
"files": [
10+
"dist"
11+
],
12+
"scripts": {
13+
"dev": "tsup --watch",
14+
"build": "tsup",
15+
"typecheck": "tsc --noEmit",
16+
"prepublishOnly": "pnpm build"
17+
},
18+
"keywords": [
19+
"typescript",
20+
"backend",
21+
"express",
22+
"mongodb",
23+
"cli",
24+
"scaffolding",
25+
"generator",
26+
"seeder",
27+
"factory"
28+
],
29+
"author": "muneebhashone",
30+
"repository": {
31+
"type": "git",
32+
"url": "https://github.com/muneebhashone/typescript-backend-toolkit.git",
33+
"directory": "packages/tbk"
34+
},
35+
"homepage": "https://github.com/muneebhashone/typescript-backend-toolkit/tree/main/packages/tbk",
36+
"bugs": {
37+
"url": "https://github.com/muneebhashone/typescript-backend-toolkit/issues"
38+
},
39+
"license": "MIT",
40+
"dependencies": {
41+
"commander": "^14.0.1"
42+
},
43+
"devDependencies": {
44+
"@types/node": "^18.11.18",
45+
"tsup": "^8.1.0",
46+
"typescript": "^5.1.6"
47+
},
48+
"engines": {
49+
"node": ">=18.0.0"
50+
}
51+
}

0 commit comments

Comments
 (0)