@sundaysf/cli-v3 0.0.1 → 0.0.2

package/README.md

@@ -3,12 +3,56 @@
 CLI that scaffolds a production-ready REST API (Express 5 · TypeScript · Knex · PostgreSQL ·
 Zod · pino · Jest) and generates complete entity verticals inside it.
 
+## Commands
+
 ```bash
-npx @sundaysf/cli-v3 new my-api --with-auth
-cd my-api && docker compose up -d && npm run db:migrate && npm run start:dev
+# Create a project ---------------------------------------------------------------
+npx @sundaysf/cli-v3 new my-api                 # new folder ./my-api
+npx @sundaysf/cli-v3 new my-api --with-auth     # + user/auth tables, register/login/me, JWT
+npx @sundaysf/cli-v3 new .                      # scaffold INTO the current (empty) folder
+npx @sundaysf/cli-v3 new . --name my-api        # same, choosing the package name
+npx @sundaysf/cli-v3 new my-api -y              # no prompts, defaults (no auth, port 3005, npm)
+
+# Options for `new`
+#   --with-auth | --no-auth     include / skip auth without asking
+#   --port <n>                  HTTP port (default 3005)
+#   --pm npm|pnpm               package manager (auto-detected)
+#   --no-install                skip dependency installation
+#   --no-git                    skip git init and the initial commit
+#   --name <name>               project name when using "."
+#   -y, --yes                   accept every default, never prompt
+
+# Work inside the project --------------------------------------------------------
+docker compose up -d                            # local PostgreSQL 16
+npm run db:migrate                              # apply migrations
+npm run start:dev                               # http://localhost:3005/api/health
+npm test                                        # jest + coverage (needs Postgres)
+npm run test:unit                               # jest without database suites
+
+# Generate an entity (run inside the project) ------------------------------------
 sundaysf generate entity product name:string:unique price:decimal isActive:boolean=true
+sundaysf g entity order userId:user.id total:decimal 'notes:text?' status:string=pending
+sundaysf g entity tag --dry-run                 # print, write nothing (asks for fields on a TTY)
+
+# Options for `generate entity`
+#   --fields "<spec>"           fields as one string instead of positional args
+#   --no-tests                  skip unit + route tests
+#   --no-migration              skip the migration
+#   --dry-run                   print everything, write nothing
+#   --force                     overwrite existing code files (never migrations)
+
+# After generating
+npm run db:migrate && npm run typecheck && npm test
+
+# Global install instead of npx ----------------------------------------------------
+npm install -g @sundaysf/cli-v3                 # then: sundaysf new ..., sundaysf g entity ...
+sundaysf --help  |  sundaysf new --help  |  sundaysf generate entity --help
 ```
 
+Field syntax: `name:type[?][:unique][=default]` with `string text integer decimal boolean date
+datetime json uuid <entity>.id`. Quote fields containing `?` in zsh (`'notes:text?'`).
+Full reference: [`sundaysf generate entity`](#sundaysf-generate-entity).
+
 - [What changed since v2](#what-changed-since-v2)
 - [Install](#install)
 - [`sundaysf new`](#sundaysf-new)
@@ -52,8 +96,10 @@ the local database (optional).
 ## `sundaysf new`
 
 ```
-sundaysf new [name] [options]
+sundaysf new <name|.> [options]
 
+  .                  scaffold into the current directory (must be empty; an existing .git is kept)
+  --name <name>      project/package name when using "." (default: the folder name, slugified)
   --with-auth        include auth (user/auth tables, register/login/me, JWT, bcrypt, middleware, tests)
   --no-auth          skip auth without asking
   --port <port>      HTTP port (default 3005)
@@ -68,14 +114,16 @@ are: no auth, port 3005, install, git.
 
 What it does:
 
-1. Validates the name (`^[a-z0-9][a-z0-9-]{0,63}$`) and that the target folder is empty.
+1. Validates the name (`^[a-z0-9][a-z0-9-]{0,63}$`) and that the target folder is empty. With
+   `.` the folder is the current directory: only `.git` and editor folders may already exist,
+   and the name comes from `--name` or the folder name (`My API v2` → `my-api-v2`).
 2. Copies the `api` template, applies the `api-auth` overlay when requested, replaces the
    `__SF_*__` tokens (project name, port, database name, CLI version), renames `_gitignore` and
    `_package.json`, and refuses to finish if any token is left or a `.npmrc` sneaked in.
 3. Writes `.env` from `.env.example`. With auth, `.env` gets a random 64-char `JWT_SECRET`
    (`.env.example` keeps a placeholder).
-4. `git init -b main`, `npm install`, `npm run format`, and an initial commit
-   (`chore: scaffold <name> with @sundaysf/cli-v3 <version>`).
+4. `git init -b main` (skipped when `.git` already exists), `npm install`, `npm run format`,
+   and an initial commit (`chore: scaffold <name> with @sundaysf/cli-v3 <version>`).
 5. Prints the next steps. A failing install or commit is reported but never deletes the files.
 
 Generated tree (auth files marked `*`):

package/dist/cli.js

@@ -298,6 +298,7 @@ var detectPackageManager = () => {
   const ua = process.env.npm_config_user_agent ?? "";
   return ua.startsWith("pnpm") ? "pnpm" : "npm";
 };
+var slugifyProjectName = (raw) => raw.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64);
 var validateProjectName = (name) => {
   if (!PROJECT_NAME_RE.test(name)) {
     return "Use lowercase letters, numbers and dashes, starting with a letter or number (max 64 chars)";
@@ -340,25 +341,46 @@ var scaffoldProject = async (dir, name, port, withAuth) => {
   await writeDotEnv(dir, withAuth);
   return { dir, name, port, withAuth };
 };
-var isEmptyDir = async (dir) => {
-  if (!await fs5.pathExists(dir)) return true;
+var HARMLESS_ENTRIES = /* @__PURE__ */ new Set([".git", ".DS_Store", ".idea", ".vscode"]);
+var listBlockingEntries = async (dir) => {
+  if (!await fs5.pathExists(dir)) return [];
   const entries = await fs5.readdir(dir);
-  return entries.length === 0;
+  return entries.filter((e) => !HARMLESS_ENTRIES.has(e));
+};
+var resolveTarget = async (rawName, cwd, explicitName) => {
+  const inPlace = rawName === ".";
+  const dir = inPlace ? path4.resolve(cwd) : path4.resolve(cwd, rawName);
+  const name = explicitName ?? (inPlace ? slugifyProjectName(path4.basename(dir)) : rawName);
+  const nameError = validateProjectName(name);
+  if (nameError) {
+    throw new Error(
+      inPlace ? `Cannot derive a project name from folder "${path4.basename(dir)}": ${nameError}. Use --name <name>.` : `Invalid project name "${name}": ${nameError}`
+    );
+  }
+  const blocking = await listBlockingEntries(dir);
+  if (blocking.length) {
+    throw new Error(
+      inPlace ? `The current directory is not empty (${blocking.slice(0, 5).join(", ")}${blocking.length > 5 ? ", ..." : ""}). Run \`sundaysf new .\` in an empty folder (a .git directory is fine).` : `Directory "${rawName}" already exists and is not empty.`
+    );
+  }
+  return { dir, name, inPlace };
 };
 var runNew = async (rawName, opts) => {
   const interactive = isInteractive() && !opts.yes;
   p2.intro(pc2.bgCyan(pc2.black(` sundaysf v${cliVersion()} `)) + " " + pc2.dim("new API project"));
-  let name = rawName?.trim();
-  if (!name) {
-    if (!interactive) throw new Error("Project name is required: sundaysf new <name>");
-    name = await text2("Project name", { placeholder: "my-api", validate: validateProjectName });
-  }
-  const nameError = validateProjectName(name);
-  if (nameError) throw new Error(`Invalid project name "${name}": ${nameError}`);
-  const dir = path4.resolve(process.cwd(), name);
-  if (!await isEmptyDir(dir)) {
-    throw new Error(`Directory "${name}" already exists and is not empty.`);
+  let target = rawName?.trim();
+  if (!target) {
+    if (!interactive)
+      throw new Error(
+        'Project name is required: sundaysf new <name> (or "." for the current directory)'
+      );
+    target = await text2('Project name ("." for the current directory)', {
+      placeholder: "my-api",
+      validate: (v) => v === "." ? void 0 : validateProjectName(v)
+    });
   }
+  const { dir, name, inPlace } = await resolveTarget(target, process.cwd(), opts.name);
+  if (inPlace) p2.log.info(`Scaffolding "${name}" into ${dir}`);
   let withAuth = opts.withAuth;
   if (withAuth === void 0) {
     withAuth = interactive ? await confirm2("Include auth (user/auth tables, register/login/me, JWT)?", false) : false;
@@ -378,7 +400,8 @@ var runNew = async (rawName, opts) => {
   });
   let gitOk = false;
   if (doGit) {
-    gitOk = await step("git init", async () => {
+    const hasGit = await fs5.pathExists(path4.join(dir, ".git"));
+    gitOk = hasGit ? true : await step("git init", async () => {
       await run("git", ["init", "-b", "main"], { cwd: dir });
     });
   }
@@ -404,7 +427,7 @@ var runNew = async (rawName, opts) => {
     });
   }
   const next = [
-    `cd ${name}`,
+    ...inPlace ? [] : [`cd ${name}`],
     ...doInstall && installOk ? [] : [`${pm} install`],
     "docker compose up -d          # local Postgres",
     `${pm} run db:migrate`,
@@ -415,8 +438,9 @@ var runNew = async (rawName, opts) => {
   p2.outro(pc2.green(`Project "${name}" is ready.`) + (withAuth ? pc2.dim(" (with auth)") : ""));
 };
 var registerNewCommand = (program2) => {
-  program2.command("new").description("Create a new API project (Express 5 + Knex + Postgres) ready to work on").argument("[name]", "project name (lowercase, dashes allowed)").option("--with-auth", "include auth: user/auth tables, register/login/me, JWT").option("--no-auth", "explicitly skip auth (no prompt)").option("--port <port>", "HTTP port for the API", void 0).option("--no-install", "skip dependency installation").option("--no-git", "skip git init and initial commit").option("--pm <pm>", "package manager: npm | pnpm").option("-y, --yes", "accept all defaults, no prompts").action(async (name, raw) => {
+  program2.command("new").description("Create a new API project (Express 5 + Knex + Postgres) ready to work on").argument("[name]", 'project name (lowercase, dashes allowed) or "." for the current directory').option("--name <name>", 'project name when scaffolding with "." (default: folder name)').option("--with-auth", "include auth: user/auth tables, register/login/me, JWT").option("--no-auth", "explicitly skip auth (no prompt)").option("--port <port>", "HTTP port for the API", void 0).option("--no-install", "skip dependency installation").option("--no-git", "skip git init and initial commit").option("--pm <pm>", "package manager: npm | pnpm").option("-y, --yes", "accept all defaults, no prompts").action(async (name, raw) => {
     const opts = {
+      name: raw.name,
       withAuth: raw.withAuth === true ? true : raw.auth === false ? false : void 0,
       port: raw.port,
       install: raw.install,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sundaysf/cli-v3",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Sundays Framework v3 CLI - scaffolds an Express 5 + Knex + Postgres API and generates entity verticals",
   "type": "module",
   "bin": {