Skip to content

Commit c666e5a

Browse files
RomakitaRomakita
committed
docs(cli): rewrite README to clarify CLI structure, workspace, and dev workflow
- Expanded "Overview" section to detail the Ts.ED CLI purpose and structure. - Added detailed descriptions of workspace layout, development scripts, and local development steps. - Updated guidance for testing, building, and working with documentation and templates.
1 parent f97c5ab commit c666e5a

File tree

4 files changed

+130
-100
lines changed

4 files changed

+130
-100
lines changed

‎README.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
<p style="text-align: center" align="center">
2+
<a href="https://tsed.dev" target="_blank"><img src="https://tsed.dev/tsed-og.png" width="200" alt="Ts.ED logo"/></a>
3+
</p>
4+
5+
<div align="center">
6+
<h1>Ts.ED CLI</h1>
7+
8+
[![Build & Release](https://github.com/tsedio/tsed-cli/workflows/Build%20&%20Release/badge.svg?branch=master)](https://github.com/tsedio/tsed-cli/actions?query=workflow%3A%22Build+%26+Release%22)
9+
[![PR Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/tsedio/tsed-cli/blob/master/CONTRIBUTING.md)
10+
[![Coverage Status](https://coveralls.io/repos/github/tsedio/tsed-cli/badge.svg?branch=master)](https://coveralls.io/github/tsedio/tsed-cli?branch=master)
11+
[![npm version](https://badge.fury.io/js/%40tsed%2Fcli.svg)](https://badge.fury.io/js/%40tsed%2Fcli)
12+
[![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)
13+
[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
14+
[![backers](https://opencollective.com/tsed/tiers/badge.svg)](https://opencollective.com/tsed)
15+
16+
<br />
17+
<div align="center">
18+
<a href="https://cli.tsed.dev/">Website</a>
19+
<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
20+
<a href="https://cli.tsed.dev/getting-started.html">Getting started</a>
21+
<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
22+
<a href="https://slack.tsed.dev">Slack</a>
23+
<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
24+
<a href="https://twitter.com/TsED_io">Twitter</a>
25+
</div>
26+
<hr />
27+
</div>
28+
29+
## Overview
30+
31+
Ts.ED CLI is the official project generator and automation toolkit for Ts.ED applications. This repository is a Yarn 4 + Lerna monorepo that keeps the CLI core, plugins, generators, documentation, and automation scripts in sync. Refer to the [documentation](https://cli.tsed.dev/) for deep dives into commands, MCP tools, and authoring guides.
32+
33+
## Recent Updates
34+
35+
- Adopted a Yarn 4 + Lerna workspace layout backed by `@tsed/monorepo-utils`, so `monorepo` scripts can orchestrate builds, cleaning, publishing, and package syncing across every workspace.
36+
- Consolidated CLI building blocks: commands live under `packages/cli`, DI/prompt infrastructure in `packages/cli-core`, and shared tasks under `@tsed/cli-tasks`, ensuring plugins and templates render with the same `@clack/prompts` UX.
37+
- Refreshed the documentation pipeline so `tsdoc` feeds the VitePress site (`docs/`) and publishes to `cli.tsed.dev` through the `docs:*` scripts described below.
38+
39+
## Workspace layout
40+
41+
| Path | Purpose |
42+
| ------------------------ | ---------------------------------------------------------------------------------------------------------- |
43+
| `packages/cli` | Command entrypoints, `tsed` bin, and generator templates consumed by end users. |
44+
| `packages/cli-core` | Dependency injection, prompting helpers, context utilities, and shared task orchestration. |
45+
| `packages/cli-mcp` | MCP servers and tools that expose CLI capabilities to external agents. |
46+
| `packages/cli-plugin-*` | Framework- or feature-specific blueprints packaged as installable plugins. |
47+
| `packages/cli-testing` | Reusable testing harnesses, filesystem fakes, and fixtures for deterministic specs. |
48+
| `packages/cli/templates` | Handlebars/EJS templates that power `tsed init`, `add`, and plugin generators. |
49+
| `docs/` | VitePress site, TSDoc output, and guides served via `yarn docs:serve` or published through `docs:publish`. |
50+
| `dist/` | Build artifacts produced by `yarn build` and published to npm. |
51+
| `tools/*` | Automation helpers (TypeScript references, ESLint/Vitest installers, CI glue) invoked by `yarn build:*`. |
52+
53+
## Development scripts
54+
55+
| Command | Description |
56+
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------- |
57+
| `yarn configure` | Prepares CI metadata via `monorepo ci configure`. |
58+
| `yarn clean` | Removes build output across every workspace with `monorepo clean workspace`. |
59+
| `yarn build` | Runs `monorepo build --verbose`, compiling every package and depositing artifacts in `dist/`. |
60+
| `yarn build:references` | Refreshes TypeScript project references through `tools/typescript`. Run after adding/renaming packages. |
61+
| `yarn build:eslint` / `yarn build:vitest` | Installs pinned ESLint and Vitest binaries inside `tools/`. |
62+
| `yarn sync:packages` | Aligns dependency versions between packages with `monorepo sync packages`. |
63+
| `yarn lint` / `yarn lint:fix` | Applies the flat ESLint + Prettier setup (with `eslint-plugin-simple-import-sort`) across the repo. |
64+
| `yarn test [--coverage]` | Executes the Vitest suite once. Add `--coverage` for the V8 report enforced in CI. |
65+
| `yarn docs:serve` / `yarn docs:build` | Generates API docs with `tsdoc`, builds the VitePress site, then serves or builds the static output. |
66+
| `yarn docs:publish` | Publishes the VitePress build to `cli.tsed.dev` via the configured `gh-pages` target. |
67+
| `yarn api:build` / `yarn api:build:dev` | Rebuilds `docs/api` with `tsc -b` + `tsdoc`; the `:dev` variant watches templates with `chokidar`. |
68+
| `yarn release` / `yarn release:dryRun` | Triggers `semantic-release` to publish packages (or simulate the process). |
69+
70+
> Tip: run package-scoped commands with `yarn workspace <pkg> <script>` (for example, `yarn workspace @tsed/cli vitest run packages/cli/src/commands/init/InitCmd.spec.ts`).
71+
72+
## Local development
73+
74+
1. **Install dependencies**
75+
Enable Corepack (if needed) then install once for the monorepo and docs:
76+
77+
```bash
78+
corepack enable
79+
yarn install
80+
```
81+
82+
The root `postinstall` step automatically installs `docs/` dependencies.
83+
84+
2. **Build and iterate**
85+
86+
- `yarn build` ensures every package emits fresh artifacts under `dist/`.
87+
- Use targeted builds/tests via `yarn workspace <pkg> <command>` for fast feedback.
88+
- When touching DI helpers (`context()`, `runInContext`, etc.), rely on `cli-testing` utilities like `DITest.create()` inside specs.
89+
90+
3. **Test and lint**
91+
92+
- `yarn test --coverage` before opening a PR so CI thresholds stay green.
93+
- Co-locate fast unit specs next to sources and keep scenario tests under `packages/*/test/**`.
94+
- Mock filesystem/process work with helpers from `cli-testing` and `CliExeca` to avoid flaky suites.
95+
96+
4. **Docs and templates**
97+
- Iterate on documentation with `yarn docs:serve`.
98+
- Generator templates live in `packages/cli/templates`; plugin-specific templates stay inside their respective `cli-plugin-*` packages.
99+
- Run `yarn build:references` whenever new packages or templates are added so TS project references stay accurate.
100+
101+
## Contributors
102+
103+
Please read [contributing guidelines here](https://tsed.dev/CONTRIBUTING.html)
104+
105+
<a href="https://github.com/tsedio/ts-express-decorators/graphs/contributors"><img src="https://opencollective.com/tsed/contributors.svg?width=890" /></a>
106+
107+
## Backers
108+
109+
Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/tsed#backer)]
110+
111+
<a href="https://opencollective.com/tsed#backers" target="_blank"><img src="https://opencollective.com/tsed/tiers/backer.svg?width=890"></a>
112+
113+
## Sponsors
114+
115+
Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [[Become a sponsor](https://opencollective.com/tsed#sponsor)]
116+
117+
## License
118+
119+
The MIT License (MIT)
120+
121+
Copyright (c) 2016 - 2023 Romain Lenzotti
122+
123+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
124+
125+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
126+
127+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

‎docs/.templates/page/page.ejs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
symbol: <%- symbol.symbolName %>
3-
module: <%- symbol.module.moduleName %>
3+
module: "<%- symbol.module.moduleName %>"
44
type: <%- symbol.symbolType %>
55
meta:
66
- name: keywords

‎docs/.vitepress/config.mts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -117,9 +117,9 @@ export default defineConfig({
117117
team,
118118
apiRedirectUrl: "",
119119
repo: "tsedio/tsed",
120-
githubProxyUrl: "https://api.tsed.dev/rest/github/tsedio/tsed",
120+
githubProxyUrl: "https://api.tsed.dev/rest/github/tsedio/tsed-cli",
121121
editLink: {
122-
pattern: "https://github.com/tsedio/tsed/edit/production/docs/:path"
122+
pattern: "https://github.com/tsedio/tsed-cli/edit/master/docs/:path"
123123
},
124124
search: {
125125
provider: "algolia",

‎readme.md‎

Lines changed: 0 additions & 97 deletions
This file was deleted.

0 commit comments

Comments
 (0)