@morda-dev/create-sdk 1.0.1 → 1.1.1

package/README.md

@@ -0,0 +1,51 @@
+# create-sdk
+
+Scaffold a production-ready TypeScript SDK with a strict public API.
+
+## 🚀 Quick start
+
+```bash
+npx @morda-dev/create-sdk my-sdk
+cd my-sdk
+npm install
+npm run build
+```
+
+## ✨ What you get
+
+⚡ TypeScript + ESM out of the box
+
+🔒 Strict public API enforcement (API Extractor)
+
+🧪 CI-ready project structure
+
+📦 Clean SDK architecture
+
+🚫 No accidental exports
+
+## 📁 Project structure
+src/
+  index.ts        # public API surface
+  modules/        # internal implementation
+  types/          # public types
+
+  Only symbols exported from src/index.ts are considered public.
+
+## 📜 Available scripts
+npm run build      # build the SDK
+npm run api:check  # validate public API
+
+## 🧠 Philosophy
+
+This CLI helps you build SDKs with a stable and explicit public API.
+
+Anything not exported from src/index.ts is treated as private by default.
+This prevents accidental breaking changes and enforces long-term stability.
+
+## ⚙️ Requirements
+
+Node.js >= 18
+
+## 📄 License
+
+ISC

package/bin/create-sdk.js

@@ -1,63 +1,172 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 import fs from "fs";
 import path from "path";
+import process from "process";
 import { fileURLToPath } from "url";
+import { execSync } from "child_process";
+import prompts from "prompts";
 
-/**
- * Resolve __dirname in ESM
+/* ============================================================================
+ * Environment checks
+ * ============================================================================
  */
+
+const REQUIRED_NODE_MAJOR = 18;
+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}`
+  );
+  process.exit(1);
+}
+
+/* ============================================================================
+ * CLI args & flags
+ * ============================================================================
+ */
+
+const rawArgs = process.argv.slice(2);
+
+const flags = {
+  yes: rawArgs.includes("--yes"),
+  noGit: rawArgs.includes("--no-git"),
+  noInstall: rawArgs.includes("--no-install"),
+};
+
+if (rawArgs.includes("--version") || rawArgs.includes("-v")) {
+  console.log("create-sdk v1.1.0");
+  process.exit(0);
+}
+
+if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
+  console.log(`
+create-sdk — scaffold a production-ready TypeScript SDK
+
+Usage:
+  npx @morda-dev/create-sdk <project-name>
+
+Options:
+  --yes           Skip prompts and use defaults
+  --no-git        Do not initialize git repository
+  --no-install    Do not install dependencies
+  --help, -h      Show this help
+  --version, -v   Show version
+
+Example:
+  npx @morda-dev/create-sdk my-sdk
+  npx @morda-dev/create-sdk my-sdk --yes --no-install
+`);
+  process.exit(0);
+}
+
+/* ============================================================================
+ * Paths
+ * ============================================================================
+ */
+
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
+const templateDir = path.resolve(__dirname, "../template");
 
-/**
- * Project name from CLI args
+/* ============================================================================
+ * Project name & interactive flow
+ * ============================================================================
  */
-const projectName = process.argv[2];
+
+const argProjectName = rawArgs.find((a) => !a.startsWith("-"));
+
+let projectName;
+let initGit = !flags.noGit;
+let installDeps = !flags.noInstall;
+
+if (flags.yes && argProjectName) {
+  projectName = argProjectName;
+} else if (!argProjectName) {
+  const answers = await prompts(
+    [
+      {
+        type: "text",
+        name: "name",
+        message: "Project name:",
+        validate: (v) => (v ? true : "Project name is required"),
+      },
+      {
+        type: "confirm",
+        name: "initGit",
+        message: "Initialize git repository?",
+        initial: true,
+      },
+      {
+        type: "confirm",
+        name: "installDeps",
+        message: "Install dependencies now?",
+        initial: false,
+      },
+    ],
+    {
+      onCancel: () => {
+        console.log("\n❌ Cancelled");
+        process.exit(1);
+      },
+    }
+  );
+
+  projectName = answers.name;
+  initGit = answers.initGit;
+  installDeps = answers.installDeps;
+} else {
+  projectName = argProjectName;
+}
 
 if (!projectName) {
-  console.error("❌ Please provide a project name");
-  console.error("   Usage: npx create-sdk my-sdk");
+  console.error("❌ Project name is required");
   process.exit(1);
 }
 
-/**
- * Paths
+/* ============================================================================
+ * Target directory
+ * ============================================================================
  */
-const targetDir = path.resolve(process.cwd(), projectName);
-const templateDir = path.resolve(__dirname, "../template");
 
-/**
+const dirName = projectName.startsWith("@")
+  ? projectName.split("/")[1]
+  : projectName;
+
+const targetDir = path.resolve(process.cwd(), dirName);
+
+/* ============================================================================
  * Safety checks
+ * ============================================================================
  */
+
 if (!fs.existsSync(templateDir)) {
-  console.error("❌ Template directory not found:");
-  console.error("   ", templateDir);
+  console.error("❌ Template directory not found:", templateDir);
   process.exit(1);
 }
 
 if (fs.existsSync(targetDir)) {
-  console.error(`❌ Directory "${projectName}" already exists`);
+  console.error(`❌ Directory "${dirName}" already exists`);
   process.exit(1);
 }
 
-/**
- * Create project
+/* ============================================================================
+ * Scaffold project
+ * ============================================================================
  */
+
 console.log("🚀 Creating SDK:", projectName);
 
 copyDir(templateDir, targetDir);
 
-/**
+/* ============================================================================
  * Update package.json
+ * ============================================================================
  */
-const pkgPath = path.join(targetDir, "package.json");
-
-if (!fs.existsSync(pkgPath)) {
-  console.error("❌ package.json not found in template");
-  process.exit(1);
-}
 
+const pkgPath = path.join(targetDir, "package.json");
 const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
 
 pkg.name = projectName;
@@ -66,18 +175,63 @@ delete pkg.private;
 
 fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
 
-/**
+/* ============================================================================
+ * Update README title
+ * ============================================================================
+ */
+
+const readmePath = path.join(targetDir, "README.md");
+
+if (fs.existsSync(readmePath)) {
+  const updated = fs
+    .readFileSync(readmePath, "utf8")
+    .replace(/^# .*/m, `# ${projectName}`);
+
+  fs.writeFileSync(readmePath, updated);
+}
+
+/* ============================================================================
+ * Git init
+ * ============================================================================
+ */
+
+if (initGit) {
+  try {
+    execSync("git init", { cwd: targetDir, stdio: "ignore" });
+  } catch {}
+}
+
+/* ============================================================================
+ * Install dependencies
+ * ============================================================================
+ */
+
+if (installDeps) {
+  try {
+    execSync("npm install", { cwd: targetDir, stdio: "inherit" });
+  } catch {
+    console.warn("⚠️ Failed to install dependencies");
+  }
+}
+
+/* ============================================================================
  * Done
+ * ============================================================================
  */
-console.log("✅ SDK created successfully!");
+
+console.log("");
+console.log("🎉 SDK scaffolded successfully!");
 console.log("");
 console.log("Next steps:");
-console.log(`  cd ${projectName}`);
-console.log("  npm install");
+console.log(`  cd ${dirName}`);
+if (!installDeps) console.log("  npm install");
 console.log("  npm run build");
+console.log("");
+console.log("Happy hacking 🚀");
 
-/**
- * ===== Helpers =====
+/* ============================================================================
+ * Helpers
+ * ============================================================================
  */
 
 function copyDir(src, dest) {

package/package.json

@@ -1,14 +1,41 @@
 {
   "name": "@morda-dev/create-sdk",
-  "version": "1.0.1",
-  "description": "CLI to scaffold a production-ready TypeScript SDK",
+  "version": "1.1.1",
+  "description": "CLI to scaffold a production-ready TypeScript SDK with a strict public API",
   "type": "module",
   "bin": {
     "create-sdk": "./bin/create-sdk.js"
   },
   "files": [
     "bin",
-    "template"
+    "template",
+    "README.md"
   ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "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",
+    "sdk",
+    "cli",
+    "scaffold",
+    "api-extractor",
+    "library"
+  ],
+  "scripts": {
+    "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"
+  },
   "license": "ISC"
 }

package/template/.github/workflows/ci.yml

@@ -1,35 +1,30 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: npm
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Lint
-        run: npm run lint
-
-      - name: Typecheck
-        run: npm run typecheck
-
-      - name: Build
-        run: npm run build
-
-      - name: Test
-        run: npm run test
+name: CI
+
+on:
+  pull_request:
+    branches: [ main ]
+  push:
+    branches: [ main ]
+
+jobs:
+  build-and-api-check:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: API Extractor check
+        run: npm run api:check

package/template/api-extractor.json

@@ -5,16 +5,15 @@
 
   "apiReport": {
     "enabled": true,
-    "reportFolder": "./etc",
-    "reportFileName": "project-template.api.md"
+    "reportFileName": "project-template.api.md",
+    "reportFolder": "./etc"
   },
 
-  "dtsRollup": {
-    "enabled": true,
-    "untrimmedFilePath": "./dist/project-template.d.ts"
+  "docModel": {
+    "enabled": false
   },
 
-  "docModel": {
+  "dtsRollup": {
     "enabled": false
   },
 
@@ -24,6 +23,7 @@
         "logLevel": "warning"
       }
     },
+
     "extractorMessageReporting": {
       "default": {
         "logLevel": "warning"

package/template/etc/project-template.api.md

@@ -1,32 +1,32 @@
-## API Report File for "project-template"
-
-> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
-
-```ts
-// @public
-export type ApiResult<T> =
-  | {
-      ok: true;
-      data: T;
-    }
-  | {
-      ok: false;
-      error: string;
-    };
-
-// @public
-export function getUser(id: number): ApiResult<User>;
-
-// @public
-export function sumAges(users: User[]): number;
-
-// @public
-export interface User {
-  // (undocumented)
-  age: number;
-  // (undocumented)
-  id: number;
-  // (undocumented)
-  name: string;
-}
-```
+## API Report File for "@morda-dev/project-template"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+// @public
+export type ApiResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: string;
+};
+
+// @public
+export function getUser(id: number): ApiResult<User>;
+
+// @public
+export function sumAges(users: User[]): number;
+
+// @public
+export interface User {
+    // (undocumented)
+    age: number;
+    // (undocumented)
+    id: number;
+    // (undocumented)
+    name: string;
+}
+
+```

package/template/package.json

@@ -4,32 +4,41 @@
   "description": "Production-ready TypeScript SDK template with a strict public API",
   "license": "ISC",
   "type": "module",
+
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+
   "exports": {
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
     }
   },
+
   "files": [
-    "dist"
+    "dist",
+    "etc"
   ],
+
   "sideEffects": false,
+
   "engines": {
     "node": ">=18"
   },
+
   "repository": {
     "type": "git",
     "url": "https://github.com/mordaHQ/project-template.git"
   },
+
   "scripts": {
-    "build": "tsc -p tsconfig.build.json"
+    "build": "tsc -p tsconfig.build.json",
+    "api:update": "api-extractor run --local",
+    "api:check": "api-extractor run"
   },
+
   "devDependencies": {
+    "@microsoft/api-extractor": "^7.55.2",
     "typescript": "^5.9.3"
-  },
-  "dependencies": {
-    "@morda-dev/project-template": "^0.1.1"
   }
 }

package/template/src/index.ts

@@ -1,7 +1,11 @@
 /**
- * Project Template — Public API
- *
  * @packageDocumentation
+ *
+ * Production-ready TypeScript SDK template.
+ *
+ * This file defines the public API surface of the package.
+ * Only symbols exported from this file are considered stable
+ * and part of the public contract.
  */
 
 /* ============================================================================
@@ -9,6 +13,7 @@
  * ============================================================================
  */
 
+/** @public */
 export type { User, ApiResult } from "./types/user.js";
 
 /* ============================================================================
@@ -16,4 +21,5 @@ export type { User, ApiResult } from "./types/user.js";
  * ============================================================================
  */
 
+/** @public */
 export { getUser, sumAges } from "./modules/user.js";

package/template/src/modules/user.ts

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

package/template/src/types/user.ts

@@ -1,9 +1,17 @@
-export interface User {
+/**
+ * @public
+ * User entity
+ */
+export interface User {
   id: number;
   name: string;
   age: number;
 }
 
+/**
+ * @public
+ * Generic API result
+ */
 export type ApiResult<T> =
-  | { ok: true; data: T }
-  | { ok: false; error: string };
+  | { success: true; data: T }
+  | { success: false; error: string };

package/template/.github/CODEOWNERS

@@ -1,2 +0,0 @@
-# Автоматический выбор ревьювера для всех файлов
-* @mordaHQ