Skip to content

Commit e969540

Browse files
kaifcoderkaifcoder
committed
feat: initialize create-polyglot CLI with multi-language support
Signed-off-by: kaifcoder <kaifmohd2014@gmail.com>
1 parent 75384e6 commit e969540

File tree

22 files changed

+1630
-0
lines changed

22 files changed

+1630
-0
lines changed

‎.gitignore‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# Logs
2+
logs
3+
*.log
4+
npm-debug.log*
5+
yarn-debug.log*
6+
yarn-error.log*
7+
lerna-debug.log*
8+
9+
# Diagnostic reports (https://nodejs.org/api/report.html)
10+
report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
11+
12+
# Runtime data
13+
pids
14+
*.pid
15+
*.seed
16+
*.pid.lock
17+
18+
# Directory for instrumented libs generated by jscoverage/JSCover
19+
lib-cov
20+
21+
# Coverage directory used by tools like istanbul
22+
coverage
23+
*.lcov
24+
25+
# nyc test coverage
26+
.nyc_output
27+
28+
# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
29+
.grunt
30+
31+
# Bower dependency directory (https://bower.io/)
32+
bower_components
33+
34+
# node-waf configuration
35+
.lock-wscript
36+
37+
# Compiled binary addons (https://nodejs.org/api/addons.html)
38+
build/Release
39+
40+
# Dependency directories
41+
node_modules/
42+
jspm_packages/
43+
44+
# Snowpack dependency directory (https://snowpack.dev/)
45+
web_modules/
46+
47+
# TypeScript cache
48+
*.tsbuildinfo
49+
50+
# Optional npm cache directory
51+
.npm
52+
53+
# Optional eslint cache
54+
.eslintcache
55+
56+
# Optional stylelint cache
57+
.stylelintcache
58+
59+
# Optional REPL history
60+
.node_repl_history
61+
62+
# Output of 'npm pack'
63+
*.tgz
64+
65+
# Yarn Integrity file
66+
.yarn-integrity
67+
68+
# dotenv environment variable files
69+
.env
70+
.env.*
71+
!.env.example
72+
73+
# parcel-bundler cache (https://parceljs.org/)
74+
.cache
75+
.parcel-cache
76+
77+
# Next.js build output
78+
.next
79+
out
80+
81+
# Nuxt.js build / generate output
82+
.nuxt
83+
dist
84+
.output
85+
86+
# Gatsby files
87+
.cache/
88+
# Comment in the public line in if your project uses Gatsby and not Next.js
89+
# https://nextjs.org/blog/next-9-1#public-directory-support
90+
# public
91+
92+
# vuepress build output
93+
.vuepress/dist
94+
95+
# vuepress v2.x temp and cache directory
96+
.temp
97+
.cache
98+
99+
# Sveltekit cache directory
100+
.svelte-kit/
101+
102+
# vitepress build output
103+
**/.vitepress/dist
104+
105+
# vitepress cache directory
106+
**/.vitepress/cache
107+
108+
# Docusaurus cache and generated files
109+
.docusaurus
110+
111+
# Serverless directories
112+
.serverless/
113+
114+
# FuseBox cache
115+
.fusebox/
116+
117+
# DynamoDB Local files
118+
.dynamodb/
119+
120+
# Firebase cache directory
121+
.firebase/
122+
123+
# TernJS port file
124+
.tern-port
125+
126+
# Stores VSCode versions used for testing VSCode extensions
127+
.vscode-test
128+
129+
# yarn v3
130+
.pnp.*
131+
.yarn/*
132+
!.yarn/patches
133+
!.yarn/plugins
134+
!.yarn/releases
135+
!.yarn/sdks
136+
!.yarn/versions
137+
138+
# Vite files
139+
vite.config.js.timestamp-*
140+
vite.config.ts.timestamp-*
141+
.vite/

‎.vscode/settings.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"git.enableCommitSigning": true,
3+
"git.alwaysSignOff": true
4+
}

‎CONTRIBUTING.md‎

Lines changed: 241 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,241 @@
1+
# Contributing to `create-polyglot`
2+
3+
Thanks for your interest in contributing! This document explains how to set up a local development environment, propose changes, add new service templates or generators, and submit pull requests.
4+
5+
---
6+
## Table of Contents
7+
1. Prerequisites
8+
2. Project Overview
9+
3. Getting Started (Local Dev)
10+
4. Running / Debugging the CLI
11+
5. Adding or Updating Service Templates
12+
6. Adding External Generators (e.g. create-next-app)
13+
7. Docker & Compose Generation
14+
8. Presets (Turborepo / Nx)
15+
9. Shared Packages (Workspaces)
16+
10. Code Style & Tooling
17+
11. Commit Message Conventions
18+
12. Testing Strategy (Current & Future)
19+
13. Releasing / Publishing
20+
14. Issue Reporting & Pull Request Workflow
21+
15. Security / Responsible Disclosure
22+
16. Roadmap / Ideas
23+
24+
---
25+
## 1. Prerequisites
26+
- **Node.js**: >= 20 (commander@14 & other deps require current LTS / Active version).
27+
- **npm** (or pnpm / yarn / bun if you want to test multi-PM flows).
28+
- **Git** for version control.
29+
- Internet access if you test the `--frontend-generator` flag (uses `npx create-next-app`).
30+
31+
Optional tooling:
32+
- Docker (to validate generated Dockerfiles / `compose.yaml`).
33+
- Java 21 & Maven if testing the Spring Boot template build.
34+
- Go toolchain (>=1.22) for the Go service.
35+
- Python 3.12 for the FastAPI service.
36+
37+
---
38+
## 2. Project Overview
39+
`create-polyglot` scaffolds a polyglot microservice monorepo supporting multiple languages & frameworks:
40+
- Node.js (Express)
41+
- Python (FastAPI)
42+
- Go (net/http minimal)
43+
- Java (Spring Boot)
44+
- Frontend (Next.js) via internal template or `create-next-app` generator
45+
46+
Features:
47+
- Interactive wizard (like `create-next-app`) if no arguments passed.
48+
- Non‑interactive flags for automation.
49+
- Optional presets: Turborepo or Nx.
50+
- Shared workspace package example (`packages/shared`).
51+
- Dockerfile generation + `compose.yaml` (multi-service) with a shared network.
52+
- Linting / formatting (ESLint + Prettier) + root scripts.
53+
54+
---
55+
## 3. Getting Started (Local Dev)
56+
```bash
57+
# Clone your fork
58+
git clone https://github.com/<your-username>/create-polyglot.git
59+
cd create-polyglot
60+
61+
# Install dependencies
62+
npm install
63+
64+
# Link globally to test the CLI
65+
npm link
66+
67+
# Run interactively
68+
create-polyglot
69+
70+
# Or scripted
71+
create-polyglot demo -s node,python,go,java,frontend --preset turborepo --git
72+
```
73+
To unlink later:
74+
```bash
75+
npm unlink -g create-polyglot
76+
```
77+
78+
---
79+
## 4. Running / Debugging the CLI
80+
Without linking you can run directly:
81+
```bash
82+
node bin/index.js my-app -s node,python
83+
```
84+
Use environment variable `DEBUG=1` (you can instrument logs) if you add debug branches.
85+
86+
You can also insert `console.log` statements or use an inspector:
87+
```bash
88+
node --inspect-brk bin/index.js demo -s node
89+
```
90+
Then attach a debugger (e.g., VS Code).
91+
92+
---
93+
## 5. Adding or Updating Service Templates
94+
1. Add a folder under `templates/<service-name>`.
95+
2. Include minimal runnable code (avoid giant dependency graphs).
96+
3. Add necessary dependency manifests (e.g., `package.json`, `requirements.txt`, `pom.xml`, `go.mod`).
97+
4. If the template has files that some dev tools may auto-ignore (like `application.properties` earlier), you can store as `.txt` then rename during copy (see Spring Boot handling in `bin/index.js`).
98+
5. Update `allServiceChoices` array AND if you need alias matching add to `templateMap`.
99+
6. Document new service in README + (optionally) `--help` details.
100+
101+
Design guidelines:
102+
- Keep templates minimal & fast to scaffold.
103+
- Provide a `/health` endpoint for consistency.
104+
- Avoid binding privileged ports or random ephemeral ports.
105+
106+
---
107+
## 6. Adding External Generators (e.g. `create-next-app`)
108+
Current support: `--frontend-generator` triggers `npx create-next-app`. To add more:
109+
1. Introduce a general flag (e.g., `--use-generator <service[:generator]>`).
110+
2. Parse mapping: service -> command.
111+
3. Use `execa` to run the tool in the target directory.
112+
4. Wrap in try/catch, fallback to internal template on failure.
113+
5. Sanitize directory (remove pre-existing files) before invoking generation.
114+
115+
Keep external executions opt-in to avoid slow default scaffolds.
116+
117+
---
118+
## 7. Docker & Compose Generation
119+
The generator creates per-service `Dockerfile`s and a `compose.yaml`:
120+
- Shared network: `app-net`.
121+
- Ports mapped 1:1 (e.g., Node 3001:3001).
122+
- Environment variable `PORT` injected.
123+
124+
To modify behavior:
125+
- Edit section in `bin/index.js` after `// Generate Dockerfiles + compose.yaml`.
126+
- Consider adding `healthcheck` blocks or dependencies (e.g., databases) behind a new flag `--with-db`.
127+
128+
Testing:
129+
```bash
130+
cd <generated-project>
131+
docker compose up --build
132+
```
133+
134+
---
135+
## 8. Presets (Turborepo / Nx)
136+
- Preset selected via `--preset turborepo` or `--preset nx` (or interactive).
137+
- Alters `dev` script and adds `turbo.json` or `nx.json` plus relevant dev dependency.
138+
- Add a new preset: extend conditional block where `rootPkg` is built, then emit configuration file.
139+
140+
---
141+
## 9. Shared Packages (Workspaces)
142+
The example `packages/shared` demonstrates a simple util export. To add new shared libs:
143+
```bash
144+
mkdir -p packages/logger/src
145+
cat > packages/logger/package.json <<'EOF'
146+
{
147+
"name": "@shared/logger",
148+
"version": "0.0.1",
149+
"type": "module",
150+
"main": "src/index.js"
151+
}
152+
EOF
153+
```
154+
Then import from services that use Node.js / Frontend. (Other languages each maintain their own dependency system.)
155+
156+
---
157+
## 10. Code Style & Tooling
158+
- **Formatting**: Prettier (`npm run format`).
159+
- **Linting**: ESLint (`npm run lint`).
160+
- Keep `bin/index.js` logically segmented—prefer small helper functions if it grows.
161+
- Avoid introducing TypeScript in the CLI unless you add a build step.
162+
163+
Suggested style: keep functions small, prefer async/await, graceful error handling with actionable messages.
164+
165+
---
166+
## 11. Commit Message Conventions
167+
Use Conventional Commits where possible:
168+
```
169+
feat: add Rust service template
170+
fix: correct compose environment mapping
171+
chore: bump dependencies
172+
refactor: extract docker writer helper
173+
docs: update contributing guidelines
174+
```
175+
This assists in automated changelog generation later.
176+
177+
---
178+
## 12. Testing Strategy (Current & Future)
179+
Currently there are no automated tests. Suggested roadmap:
180+
- Unit tests for helper functions (after refactoring CLI logic into modules).
181+
- Snapshot tests for generated directory structures.
182+
- E2E tests using a temporary tmpdir: run CLI, assert expected files, run `node apps/node/src/index.js` health check.
183+
- Integration test to ensure docker compose builds (can be optional in CI).
184+
185+
Potential frameworks: `vitest` or `jest`.
186+
187+
---
188+
## 13. Releasing / Publishing
189+
1. Ensure `main` is green & docs updated.
190+
2. Bump version in `package.json` (follow semver).
191+
3. Update / create `CHANGELOG.md`.
192+
4. Commit & tag:
193+
```bash
194+
git add .
195+
git commit -m "chore: release vX.Y.Z"
196+
git tag vX.Y.Z
197+
git push origin main --tags
198+
```
199+
5. Publish:
200+
```bash
201+
npm publish --access public
202+
```
203+
6. Verify install:
204+
```bash
205+
npx create-polyglot --help
206+
```
207+
208+
---
209+
## 14. Issue Reporting & Pull Request Workflow
210+
**Issues:**
211+
- Use the issue template (if/when added).
212+
- Provide: environment (OS, Node version), command run, reproduction steps, expected vs actual.
213+
214+
**Pull Requests Checklist:**
215+
- One focused change per PR.
216+
- Updated docs / README / CONTRIBUTING sections if behavior changes.
217+
- Ran a local scaffold test (`node bin/index.js test -s node --no-install --force`).
218+
- No large unrelated formatting diffs.
219+
220+
**Review Tips:** Split big refactors into multiple smaller PRs whenever possible.
221+
222+
---
223+
## 15. Security / Responsible Disclosure
224+
If you discover a security issue (e.g., command injection risk in generator inputs), **do not** open a public issue immediately. Instead contact the maintainer (add contact method in README or via GitHub security advisories once configured). Provide clear reproduction details.
225+
226+
---
227+
## 16. Roadmap / Ideas
228+
- Add additional language templates: Rust (Axum), .NET (Minimal API), PHP (Laravel Octane lightweight variant), Deno/Fresh.
229+
- Configurable port allocation & detection of conflicts.
230+
- Pluggable recipe system (YAML describing services & generators).
231+
- Telemetry (opt-in) for anonymized feature usage.
232+
- `--with-ci github-actions` to generate workflow.
233+
- Test harness & code coverage.
234+
- Multi-stage infra: generate k8s manifests or helm charts.
235+
- Monorepo plugin system for custom user templates in `~/.config/create-polyglot/templates`.
236+
237+
---
238+
## Questions / Help
239+
Open an issue or start a discussion. PRs welcome!
240+
241+
Happy building 🌟

0 commit comments

Comments
 (0)