create-qs 0.0.0 → 0.8.21

package/README.md

@@ -1,5 +1,51 @@
 # create-qs
 
-Name placeholder for the Quicksilver scaffolding CLI (`pnpm create qs`).
+English | [简体中文](README.zh-CN.md) | [繁體中文](README.zh-TW.md)
 
-No functionality is published yet.
+Create a full-stack Quicksilver project with a single command.
+
+```bash
+npm create qs
+```
+
+Use npm for this one command, not pnpm. Since pnpm 11, `pnpm create` skips any version published
+less than 24 hours ago (`minimumReleaseAge`) and does not report it, so a scaffolder released the
+same day is silently replaced by an older one. npm applies no such delay by default. Everything
+after scaffolding uses pnpm.
+
+The scaffolder is published on the public npm registry, so it runs on a clean machine with no
+registry to configure first. It asks a few questions about the project and its first module, then
+writes out a full-stack project that runs as-is: a Kotlin/Spring Boot backend, a Preact/TypeScript
+frontend, the Gradle wrapper, and a file-based H2 development database.
+
+## Requirements
+
+- **JDK 25.** The backend compiles for Java 25, and a lower version fails to compile.
+- **Node.js `>=22.13.0`**, the minimum that pnpm 11 accepts.
+- **pnpm 11** for all development after scaffolding. Workspaces and catalogs depend on it, so npm
+  and yarn are not supported.
+- **Access to the internal Nexus server**, described in the next section.
+
+## Before the first install
+
+`create-qs` is the only package published publicly. The rest of the platform, namely the
+`@qs-platform/*`, `@qs-elements/*` and `@qs-charts/*` npm packages, the Quicksilver Gradle plugin
+and every Maven artifact, is on the internal Nexus server. Its address is not made public, so the
+generated project ships no address. Get the address and a login from whoever provides you with
+Quicksilver, then configure them once per machine: the npm scopes in `~/.npmrc`, and the Gradle
+repository and login in `~/.gradle/gradle.properties`.
+
+The exact lines are in the setup chapter of the handbook, `.quicksilver/manual/en-US/00-setup.md`
+in the generated project. It is committed with the project, so it is there before the first
+install, and the scaffolder points to it when it finishes.
+
+Then start the project:
+
+```bash
+cd <project-name>
+pnpm install
+pnpm dev
+```
+
+Open <http://localhost:6286> and sign in as `admin` / `123456`. `pnpm install` also writes the
+other chapters of the handbook next to `00-setup.md`.

package/README.zh-CN.md

@@ -0,0 +1,36 @@
+# create-qs
+
+[English](README.md) | 简体中文 | [繁體中文](README.zh-TW.md)
+
+用一条命令创建全栈 Quicksilver 项目。
+
+```bash
+npm create qs
+```
+
+这一条命令请使用 npm，不要使用 pnpm。自 pnpm 11 起，`pnpm create` 会跳过发布不足 24 小时的版本（`minimumReleaseAge`），且不给出任何提示，当天发布的脚手架会被静默替换为较早的版本。npm 默认没有这一限制。项目创建完成后，其余操作一律使用 pnpm。
+
+脚手架发布在公网 npmjs 上，未做任何配置的机器即可直接运行。它会询问项目及其第一个模块的若干问题，然后生成一个可以直接运行的全栈项目，包括 Kotlin/Spring Boot 后端、Preact/TypeScript 前端、Gradle Wrapper，以及文件型 H2 开发数据库。
+
+## 环境要求
+
+- **JDK 25**。后端按 Java 25 编译，版本更低时无法编译。
+- **Node.js `>=22.13.0`**，这是 pnpm 11 要求的最低版本。
+- **pnpm 11**，创建项目之后的所有开发工作都使用它。workspace 与 catalog 均依赖 pnpm，因此不支持 npm 与 yarn。
+- **能够访问内部 Nexus**，见下一节。
+
+## 首次安装依赖之前
+
+`create-qs` 是唯一发布到公网的包。平台的其余部分，包括 `@qs-platform/*`、`@qs-elements/*`、`@qs-charts/*` 三组 npm 包、Quicksilver 的 Gradle 插件以及全部 Maven 构件，都发布在内部 Nexus 上。内部 Nexus 的地址不对外公开，因此生成的项目不预置任何地址。请先向提供 Quicksilver 的一方获取地址与账户，然后在每台机器上配置一次。npm 的三个 scope 配置在 `~/.npmrc` 中，Gradle 的仓库地址与账户配置在 `~/.gradle/gradle.properties` 中。
+
+具体写法见生成项目中开发手册的环境准备一章，即 `.quicksilver/manual/zh-CN/00-setup.md`。该章随项目提交，首次安装依赖之前即可阅读，脚手架执行完毕时也会提示它的位置。
+
+然后启动项目：
+
+```bash
+cd <项目名>
+pnpm install
+pnpm dev
+```
+
+在浏览器中访问 <http://localhost:6286>，使用 `admin` / `123456` 登录。`pnpm install` 同时会在 `00-setup.md` 所在目录写入开发手册的其余章节。

package/README.zh-TW.md

@@ -0,0 +1,36 @@
+# create-qs
+
+[English](README.md) | [简体中文](README.zh-CN.md) | 繁體中文
+
+用一個指令建立全端 Quicksilver 專案。
+
+```bash
+npm create qs
+```
+
+這一個指令請使用 npm，不要使用 pnpm。自 pnpm 11 起，`pnpm create` 會略過發布不足 24 小時的版本（`minimumReleaseAge`），且不會給出任何提示，當天發布的鷹架會被默默替換為較早的版本。npm 預設沒有這項限制。專案建立完成後，其餘操作一律使用 pnpm。
+
+鷹架發布在公開的 npmjs 上，未做任何設定的電腦即可直接執行。它會詢問專案及其第一個模組的幾個問題，然後產生一個可以直接執行的全端專案，包括 Kotlin/Spring Boot 後端、Preact/TypeScript 前端、Gradle Wrapper，以及檔案型 H2 開發資料庫。
+
+## 環境需求
+
+- **JDK 25**。後端依 Java 25 編譯，版本較低時無法編譯。
+- **Node.js `>=22.13.0`**，這是 pnpm 11 要求的最低版本。
+- **pnpm 11**，建立專案之後的所有開發工作都使用它。workspace 與 catalog 均依賴 pnpm，因此不支援 npm 與 yarn。
+- **能夠存取內部 Nexus**，請參閱下一節。
+
+## 首次安裝相依套件之前
+
+`create-qs` 是唯一發布到公開 npmjs 的套件。平台的其餘部分，包括 `@qs-platform/*`、`@qs-elements/*`、`@qs-charts/*` 三組 npm 套件、Quicksilver 的 Gradle 外掛程式以及全部 Maven 構件，都發布在內部 Nexus 上。內部 Nexus 的位址不對外公開，因此產生的專案不預設任何位址。請先向提供 Quicksilver 的一方取得位址與帳號，然後在每台電腦上設定一次。npm 的三個 scope 設定在 `~/.npmrc` 中，Gradle 的儲存庫位址與帳號設定在 `~/.gradle/gradle.properties` 中。
+
+具體寫法請參閱產生的專案中開發手冊的環境準備一章，即 `.quicksilver/manual/zh-TW/00-setup.md`。該章隨專案提交，首次安裝相依套件之前即可閱讀，鷹架執行完畢時也會提示它的位置。
+
+然後啟動專案：
+
+```bash
+cd <專案名稱>
+pnpm install
+pnpm dev
+```
+
+在瀏覽器中開啟 <http://localhost:6286>，使用 `admin` / `123456` 登入。`pnpm install` 同時會在 `00-setup.md` 所在目錄寫入開發手冊的其餘章節。