@morda-dev/create-sdk 1.2.1 → 1.3.10

package/README.md

@@ -1,4 +1,5 @@
 # create-sdk
+# create-sdk
 ![npm](https://img.shields.io/npm/v/@morda-dev/create-sdk)
 ![npm downloads](https://img.shields.io/npm/dm/@morda-dev/create-sdk)
 ![CI](https://github.com/mordaHQ/create-sdk/actions/workflows/ci.yml/badge.svg)
@@ -8,6 +9,8 @@
 > ⚠️ Early-stage project (v0.x).  
 > Public API is intentionally strict, but may evolve before v1.0.0.
 
+> **If it’s not exported from `src/index.ts`, it’s not part of the public API.**
+
 `create-sdk` is a CLI tool that bootstraps a modern TypeScript SDK with an
 **ESM-first setup**, **API Extractor**, and a **CI-ready structure** —
 so you can focus on features, not boilerplate.
@@ -38,6 +41,19 @@ npm run build
 
 That’s it. You now have a solid, production-oriented SDK foundation.
 
+## 📁 Project structure
+
+The generated SDK includes:
+
+- `src/index.ts` — the single public API entrypoint
+- `src/modules/*` — internal implementation modules
+- `src/types/*` — public & internal types
+- `dist/` — compiled output (ESM)
+- `api-extractor.json` — public API surface control
+- CI workflow for build & API checks
+
+Only symbols exported from `src/index.ts` are considered public and stable.
+
 
 ## 📘 Example SDK
 

package/bin/create-sdk.js

@@ -13,7 +13,7 @@ const CURRENT_NODE_MAJOR = Number(process.versions.node.split(".")[0]);
 if (CURRENT_NODE_MAJOR < REQUIRED_NODE_MAJOR) {
   console.error(
     `❌ Node.js ${REQUIRED_NODE_MAJOR}+ is required.\n` +
-      `   You are using Node.js ${process.versions.node}`
+    `   You are using Node.js ${process.versions.node}`
   );
   process.exit(1);
 }
@@ -35,7 +35,27 @@ const flags = {
 const projectName = rawArgs.find((a) => !a.startsWith("-"));
 
 /* ============================================================================
- * Interactive mode
+ * Help (EARLY EXIT, SNAPSHOT SAFE)
+ * ============================================================================
+ */
+if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
+  console.log(
+`Usage:
+  create-sdk <project-name> [options]
+
+Options:
+  --yes           Skip all prompts
+  --no-git        Do not initialize git repository
+  --no-install    Do not install dependencies
+  --dry-run       Show what would be done without writing files
+  --force         Overwrite existing directory
+  --help, -h      Show this help message`
+  );
+  process.exit(0);
+}
+
+/* ============================================================================
+ * Interactive / Non-interactive resolution
  * ============================================================================
  */
 let name = projectName;
@@ -66,7 +86,7 @@ if (!flags.yes && !name) {
     ],
     {
       onCancel: () => {
-        console.log("\n❌ Cancelled");
+        console.error("❌ Cancelled");
         process.exit(1);
       },
     }
@@ -77,19 +97,39 @@ if (!flags.yes && !name) {
   installDeps = answers.installDeps;
 }
 
+/* ============================================================================
+ * Validation
+ * ============================================================================
+ */
 if (!name) {
   console.error("❌ Project name is required");
   process.exit(1);
 }
 
 /* ============================================================================
- * Execute scaffold
+ * Execute scaffold (CLI CONTRACT OWNER)
  * ============================================================================
  */
-await scaffold({
-  projectName: name,
-  initGit,
-  installDeps,
-  dryRun: flags.dryRun,
-  force: flags.force,
-});
+try {
+  await scaffold({
+    projectName: name,
+    initGit,
+    installDeps,
+    dryRun: flags.dryRun,
+    force: flags.force,
+  });
+
+  if (flags.dryRun) {
+    console.log("ℹ️  Dry run completed. No files were written.");
+  } else {
+    console.log("🎉 SDK scaffolded successfully!");
+  }
+
+  process.exit(0);
+} catch (err) {
+  const message =
+    err instanceof Error ? err.message : "Unexpected error occurred";
+
+  console.error(`❌ ${message}`);
+  process.exit(1);
+}

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@morda-dev/create-sdk",
-  "version": "1.2.1",
+  "version": "1.3.10",
   "description": "CLI to scaffold a production-ready TypeScript SDK with a strict public API",
   "license": "ISC",
   "type": "module",
+
   "bin": {
     "create-sdk": "bin/create-sdk.js"
   },
+
   "files": [
     "bin",
     "src",
@@ -14,17 +16,22 @@
     "README.md",
     "LICENSE"
   ],
+
   "engines": {
     "node": ">=18"
   },
+
   "repository": {
     "type": "git",
     "url": "git+https://github.com/mordaHQ/create-sdk.git"
   },
+
   "homepage": "https://github.com/mordaHQ/create-sdk",
+
   "bugs": {
     "url": "https://github.com/mordaHQ/create-sdk/issues"
   },
+
   "keywords": [
     "create-sdk",
     "typescript",
@@ -36,20 +43,26 @@
     "esm",
     "developer-tools"
   ],
+
   "scripts": {
     "test": "vitest run",
     "test:watch": "vitest",
     "test:smoke": "node ./bin/create-sdk.js __tmp-smoke-sdk --yes --no-install --no-git && node -e \"import('fs').then(fs => fs.rmSync('__tmp-smoke-sdk', { recursive: true, force: true }))\""
   },
+
   "dependencies": {
     "prompts": "^2.4.2"
   },
+
   "devDependencies": {
     "@types/node": "^18.19.0",
-    "vitest": "^1.6.0",
     "execa": "^9.6.1",
     "fs-extra": "^11.3.3",
     "tmp": "^0.2.5",
-    "undici-types": "^7.16.0"
+    "vitest": "^1.6.0"
+  },
+
+  "publishConfig": {
+    "access": "public"
   }
 }

package/src/cli/scaffold.js

@@ -8,6 +8,10 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const templateDir = path.resolve(__dirname, "../../template");
 
+const isTest =
+  process.env.NODE_ENV === "test" ||
+  process.env.VITEST === "true";
+
 export async function scaffold({
   projectName,
   initGit = true,
@@ -26,7 +30,14 @@ export async function scaffold({
   const targetDir = path.resolve(process.cwd(), dirName);
 
   // ─────────────────────────────────────────────
-  // 🧪 DRY-RUN — ABSOLUTE NO-SIDE-EFFECT MODE
+  // 🔒 CLI CONTRACT — EARLY FAILURE
+  // ─────────────────────────────────────────────
+  if (fs.existsSync(targetDir) && !force) {
+    throw new Error(`Directory "${dirName}" already exists`);
+  }
+
+  // ─────────────────────────────────────────────
+  // 🧪 DRY-RUN — NO SIDE EFFECTS
   // ─────────────────────────────────────────────
   if (dryRun) {
     console.log("🧪 [dry-run] Creating SDK:", projectName);
@@ -35,26 +46,22 @@ export async function scaffold({
     if (initGit) console.log("🧪 [dry-run] Would init git");
     if (installDeps) console.log("🧪 [dry-run] Would install dependencies");
     console.log("🧪 [dry-run] Done (NO filesystem changes)");
-    return;
+    return { targetDir };
   }
 
   // ─────────────────────────────────────────────
-  // REAL MODE — FILESYSTEM IS TOUCHED ONLY HERE
+  // REAL MODE — FS MUTATIONS
   // ─────────────────────────────────────────────
   if (!fs.existsSync(templateDir)) {
     throw new Error(`Template directory not found: ${templateDir}`);
   }
 
-  if (fs.existsSync(targetDir)) {
-    if (!force) {
-      throw new Error(`Directory "${dirName}" already exists`);
-    }
+  if (fs.existsSync(targetDir) && force) {
     fs.rmSync(targetDir, { recursive: true, force: true });
   }
 
   console.log("🚀 Creating SDK:", projectName);
 
-  // copy template
   copyDir(templateDir, targetDir);
 
   // package.json
@@ -63,11 +70,8 @@ export async function scaffold({
 
   pkg.name = projectName;
   pkg.version = "0.1.0";
-
-  // шаблон НЕ должен быть private
   delete pkg.private;
 
-  // exports добавляются ТОЛЬКО тут
   pkg.main = "./dist/index.js";
   pkg.types = "./dist/index.d.ts";
   pkg.exports = {
@@ -88,20 +92,20 @@ export async function scaffold({
     fs.writeFileSync(readmePath, updated);
   }
 
-  // git
-  if (initGit) {
+  // git (disabled in tests)
+  if (initGit && !isTest) {
     try {
       execSync("git init", { cwd: targetDir, stdio: "ignore" });
     } catch {}
   }
 
-  // deps
-  if (installDeps) {
+  // deps (disabled in tests)
+  if (installDeps && !isTest) {
     execSync("npm install", {
       cwd: targetDir,
       stdio: "inherit",
     });
   }
 
-  console.log("🎉 SDK scaffolded successfully!");
+  return { targetDir };
 }

package/template/package.json

@@ -22,7 +22,10 @@
   },
 
   "files": [
-    "dist"
+    "dist",
+    "README.md",
+    "LICENSE",
+    "package.json"
   ],
 
   "repository": {

package/template/src/index.ts

@@ -17,9 +17,30 @@
 export type { User, ApiResult } from "./types/user.js";
 
 /* ============================================================================
- * Functions (Public)
+ * Values & Functions (Public)
  * ============================================================================
  */
 
-/** @public */
-export { getUser, sumAges } from "./modules/user.js";
+/**
+ * Public user entity.
+ *
+ * Exported explicitly to allow direct consumption:
+ * `import { user } from "sdk"`
+ *
+ * @public
+ */
+export { user } from "./modules/user.js";
+
+/**
+ * Returns a user entity.
+ *
+ * @public
+ */
+export { getUser } from "./modules/user.js";
+
+/**
+ * Example aggregate function.
+ *
+ * @public
+ */
+export { sumAges } from "./modules/user.js";

package/template/src/modules/user.ts

@@ -1,31 +1,30 @@
-import { ApiResult, User } from "../types/user.js";
+import type { User } from "../types/user.js";
 
 /**
+ * Public user constant
+ *
  * @public
- * Get a user by id
  */
-export function getUser(id: number): ApiResult<User> {
-  if (id <= 0) {
-    return {
-      success: false,
-      error: "Invalid user id",
-    };
-  }
+export const user: User = {
+  id: 1,
+  name: "Alice",
+  age: 30,
+};
 
-  return {
-    success: true,
-    data: {
-      id,
-      name: "John Doe",
-      age: 30,
-    },
-  };
+/**
+ * Returns a user entity.
+ *
+ * @public
+ */
+export function getUser(): User {
+  return user;
 }
 
 /**
+ * Example aggregate function.
+ *
  * @public
- * Sum ages of users
  */
 export function sumAges(users: User[]): number {
-  return users.reduce((sum, user) => sum + user.age, 0);
+  return users.reduce((a, u) => a + u.age, 0);
 }