@ftisindia/create-app 0.1.0

package/LICENSE

@@ -0,0 +1,144 @@
+Copyright (c) 2026 ftisindia.com
+
+This software is licensed under the PolyForm Noncommercial License 1.0.0, the full
+text of which appears below. You may use, copy, modify, and distribute this software
+for any NONCOMMERCIAL purpose at no cost, subject to those terms.
+
+COMMERCIAL USE REQUIRES A SEPARATE COMMERCIAL LICENSE.
+To obtain a commercial license, contact ftisindia.com (https://ftisindia.com).
+
+Required Notice: Copyright ftisindia.com (https://ftisindia.com)
+
+----------------------------------------------------------------------
+
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose. However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software. Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software. For example:
+
+> Required Notice: Copyright ftisindia.com (https://ftisindia.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization,
+or government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else. These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice. Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization. **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise. Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.

package/bin/index.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../src/main.mjs';

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@ftisindia/create-app",
+  "version": "0.1.0",
+  "description": "One-command scaffolder for the Phase 1 NestJS foundation starter.",
+  "type": "module",
+  "bin": {
+    "ftis-nest": "bin/index.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "template",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "author": "ftisindia.com",
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "homepage": "https://ftisindia.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ftisindia/starter-package.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ftisindia/starter-package/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepack": "node ../../scripts/sync-template.mjs",
+    "prepublishOnly": "node ../../scripts/sync-template.mjs"
+  },
+  "dependencies": {}
+}

package/src/copy.mjs

@@ -0,0 +1,45 @@
+import { copyFile, mkdir, readdir } from "node:fs/promises";
+import { join } from "node:path";
+
+function targetName(name) {
+  if (name === "_package.json") {
+    return "package.json";
+  }
+
+  if (name === "_gitignore") {
+    return ".gitignore";
+  }
+
+  if (name.startsWith("_")) {
+    return `.${name.slice(1)}`;
+  }
+
+  return name;
+}
+
+async function copyDirectory(sourceDir, targetDir) {
+  await mkdir(targetDir, { recursive: true });
+
+  const entries = await readdir(sourceDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.name === "node_modules") {
+      continue;
+    }
+
+    const source = join(sourceDir, entry.name);
+    const target = join(targetDir, targetName(entry.name));
+
+    if (entry.isDirectory()) {
+      await copyDirectory(source, target);
+      continue;
+    }
+
+    if (entry.isFile()) {
+      await copyFile(source, target);
+    }
+  }
+}
+
+export async function copyTemplate(templateDir, targetDir) {
+  await copyDirectory(templateDir, targetDir);
+}

package/src/log.mjs

@@ -0,0 +1,23 @@
+const enabled = process.stdout.isTTY && process.env.NO_COLOR === undefined;
+
+function color(code, message) {
+  return enabled ? `\u001B[${code}m${message}\u001B[0m` : message;
+}
+
+export const log = {
+  step(message) {
+    console.log(color(36, `> ${message}`));
+  },
+  success(message) {
+    console.log(color(32, `✓ ${message}`));
+  },
+  warn(message) {
+    console.warn(color(33, `! ${message}`));
+  },
+  error(message) {
+    console.error(color(31, `✖ ${message}`));
+  },
+  plain(message = "") {
+    console.log(message);
+  },
+};

package/src/main.mjs

@@ -0,0 +1,221 @@
+import { copyFile, mkdir, readdir, stat } from "node:fs/promises";
+import { basename, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { fileURLToPath } from "node:url";
+import { copyTemplate } from "./copy.mjs";
+import { log } from "./log.mjs";
+import { run } from "./run.mjs";
+import { substituteProjectName } from "./substitute.mjs";
+
+const NAME_PATTERN = /^[a-z0-9][a-z0-9-_]*$/;
+const SUPPORTED_PACKAGE_MANAGERS = new Set(["npm", "pnpm", "yarn"]);
+
+function printHelp() {
+  log.plain(`ftis-nest — @ftisindia/create-app
+
+Usage:
+  npx @ftisindia/create-app <project-name|.> [options]
+  ftis-nest <project-name|.> [options]   # after: npm i -g @ftisindia/create-app
+
+Options:
+  --no-install   Copy files only; skip npm install and prisma generate
+  --no-git       Skip git init/add/commit
+  --pm <name>    Package manager to use: npm, pnpm, or yarn
+  --help         Show this help
+`);
+}
+
+function assertSupportedNode() {
+  const major = Number(process.versions.node.split(".")[0]);
+  if (major < 20) {
+    throw new Error(
+      `Node.js 20 or newer is required. Current version: ${process.version}`,
+    );
+  }
+}
+
+async function exists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function assertTargetDirectory(targetDir) {
+  if (!(await exists(targetDir))) {
+    await mkdir(targetDir, { recursive: true });
+    return;
+  }
+
+  const entries = await readdir(targetDir);
+  if (entries.length > 0) {
+    throw new Error(`Target directory is not empty: ${targetDir}`);
+  }
+}
+
+async function resolveTemplateDir() {
+  const monorepoTemplate = fileURLToPath(
+    new URL("../../template/", import.meta.url),
+  );
+  if (await exists(monorepoTemplate)) {
+    return monorepoTemplate;
+  }
+
+  const publishedTemplate = fileURLToPath(
+    new URL("../template/", import.meta.url),
+  );
+  if (await exists(publishedTemplate)) {
+    return publishedTemplate;
+  }
+
+  throw new Error("Could not find the template directory.");
+}
+
+async function initializeGitRepository(targetDir) {
+  const init = await run("git", ["init"], {
+    cwd: targetDir,
+    allowFailure: true,
+  });
+  if (!init.ok) {
+    log.warn("Skipped git initialization because git is unavailable.");
+    return false;
+  }
+
+  return true;
+}
+
+async function createInitialCommit(targetDir) {
+  await run("git", ["add", "-A"], { cwd: targetDir, allowFailure: true });
+  const commit = await run(
+    "git",
+    ["commit", "-m", "chore: initial commit from @ftisindia/create-app"],
+    {
+      cwd: targetDir,
+      allowFailure: true,
+    },
+  );
+
+  if (!commit.ok) {
+    log.warn(
+      "Git repository was initialized, but the initial commit was skipped.",
+    );
+  }
+}
+
+async function detectPackageManager(requested) {
+  if (requested) {
+    if (!SUPPORTED_PACKAGE_MANAGERS.has(requested)) {
+      throw new Error("--pm must be one of npm, pnpm, or yarn.");
+    }
+
+    return requested;
+  }
+
+  const userAgent = process.env.npm_config_user_agent ?? "";
+  if (userAgent.startsWith("pnpm/")) {
+    return "pnpm";
+  }
+
+  if (userAgent.startsWith("yarn/")) {
+    return "yarn";
+  }
+
+  return "npm";
+}
+
+function installCommand(packageManager) {
+  return packageManager === "npm"
+    ? { command: "npm", args: ["install"] }
+    : { command: packageManager, args: ["install"] };
+}
+
+function prismaGenerateCommand(packageManager) {
+  if (packageManager === "npm") {
+    return { command: "npx", args: ["--yes", "prisma", "generate"] };
+  }
+
+  if (packageManager === "pnpm") {
+    return { command: "pnpm", args: ["exec", "prisma", "generate"] };
+  }
+
+  return { command: "yarn", args: ["prisma", "generate"] };
+}
+
+async function main() {
+  assertSupportedNode();
+
+  const { values, positionals } = parseArgs({
+    allowPositionals: true,
+    options: {
+      help: { type: "boolean", default: false },
+      "no-install": { type: "boolean", default: false },
+      "no-git": { type: "boolean", default: false },
+      pm: { type: "string" },
+    },
+  });
+
+  if (values.help || positionals.length === 0) {
+    printHelp();
+    process.exit(values.help ? 0 : 1);
+  }
+
+  const rawProjectName = positionals[0];
+  const targetDir =
+    rawProjectName === "."
+      ? process.cwd()
+      : resolve(process.cwd(), rawProjectName);
+  const projectName = basename(targetDir);
+  if (!NAME_PATTERN.test(projectName)) {
+    throw new Error(
+      "Invalid project name. Use lowercase letters, numbers, hyphens, or underscores; start with a letter or number.",
+    );
+  }
+
+  const templateDir = await resolveTemplateDir();
+  const packageManager = await detectPackageManager(values.pm);
+
+  log.step(`Using template: ${templateDir}`);
+  await assertTargetDirectory(targetDir);
+
+  log.step(`Creating ${projectName}`);
+  await copyTemplate(templateDir, targetDir);
+  await substituteProjectName(targetDir, projectName);
+  await copyFile(
+    resolve(targetDir, ".env.example"),
+    resolve(targetDir, ".env"),
+  );
+
+  let gitInitialized = false;
+  if (!values["no-git"]) {
+    log.step("Initialising git");
+    gitInitialized = await initializeGitRepository(targetDir);
+  }
+
+  if (!values["no-install"]) {
+    const install = installCommand(packageManager);
+    log.step(`Installing dependencies with ${packageManager}`);
+    await run(install.command, install.args, { cwd: targetDir });
+
+    const generate = prismaGenerateCommand(packageManager);
+    log.step("Generating Prisma client");
+    await run(generate.command, generate.args, { cwd: targetDir });
+  }
+
+  if (gitInitialized) {
+    log.step("Creating initial git commit");
+    await createInitialCommit(targetDir);
+  }
+
+  log.success(`Done. Next:
+  ${rawProjectName === "." ? "" : `cd ${rawProjectName}\n  `}Start PostgreSQL locally, or set DATABASE_URL to a reachable server.
+  npm run setup:local
+  npm run start:dev
+  Docs: http://localhost:3000/docs`);
+}
+
+main().catch((error) => {
+  log.error(error.message);
+  process.exit(1);
+});

package/src/run.mjs

@@ -0,0 +1,52 @@
+import { spawn } from "node:child_process";
+
+function quoteWindowsArg(value) {
+  if (/^[a-zA-Z0-9_./:=@+-]+$/.test(value)) {
+    return value;
+  }
+
+  return `"${value.replaceAll('"', '\\"')}"`;
+}
+
+function commandForPlatform(command, args) {
+  if (process.platform !== "win32") {
+    return { command, args };
+  }
+
+  return {
+    command: process.env.ComSpec || "cmd.exe",
+    args: ["/d", "/s", "/c", [command, ...args].map(quoteWindowsArg).join(" ")],
+  };
+}
+
+export function run(command, args, options = {}) {
+  const { allowFailure = false, cwd = process.cwd() } = options;
+  const executable = commandForPlatform(command, args);
+
+  return new Promise((resolve, reject) => {
+    const child = spawn(executable.command, executable.args, {
+      cwd,
+      stdio: "inherit",
+    });
+
+    child.on("error", (error) => {
+      if (allowFailure) {
+        resolve({ ok: false, code: 1, error });
+        return;
+      }
+
+      reject(error);
+    });
+
+    child.on("close", (code) => {
+      if (code === 0 || allowFailure) {
+        resolve({ ok: code === 0, code });
+        return;
+      }
+
+      reject(
+        new Error(`${command} ${args.join(" ")} exited with code ${code}`),
+      );
+    });
+  });
+}

package/src/substitute.mjs

@@ -0,0 +1,40 @@
+import { readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const SUBSTITUTE_FILES = new Set(["package.json", "README.md"]);
+
+async function walk(dir) {
+  const entries = await readdir(dir);
+  const files = [];
+
+  for (const entry of entries) {
+    const path = join(dir, entry);
+    const info = await stat(path);
+
+    if (info.isDirectory()) {
+      files.push(...(await walk(path)));
+      continue;
+    }
+
+    files.push(path);
+  }
+
+  return files;
+}
+
+export async function substituteProjectName(targetDir, projectName) {
+  const files = await walk(targetDir);
+
+  await Promise.all(
+    files
+      .filter((file) => SUBSTITUTE_FILES.has(file.split(/[\\/]/).at(-1)))
+      .map(async (file) => {
+        const original = await readFile(file, "utf8");
+        const updated = original.replaceAll("__PROJECT_NAME__", projectName);
+
+        if (updated !== original) {
+          await writeFile(file, updated);
+        }
+      }),
+  );
+}

package/template/.env.example

@@ -0,0 +1,36 @@
+# Local PostgreSQL defaults. Override these if your database runs elsewhere.
+DATABASE_URL=postgresql://postgres:postgres@localhost:5432/app
+TEST_DATABASE_URL=postgresql://postgres:postgres@localhost:5432/app_test
+
+JWT_SECRET=
+JWT_ACCESS_EXPIRES_IN=15m
+JWT_REFRESH_EXPIRES_IN=7d
+JWT_ISSUER=foundation-starter
+JWT_AUDIENCE=foundation-api
+
+AUTH_EMAIL_PASSWORD_ENABLED=true
+AUTH_GOOGLE_ENABLED=false
+AUTH_GOOGLE_CLIENT_ID=
+AUTH_GOOGLE_CLIENT_SECRET=
+AUTH_GOOGLE_CALLBACK_URL=http://localhost:3000/auth/google/callback
+AUTH_GOOGLE_SUCCESS_REDIRECT_URL=http://localhost:3000/auth/google/success
+AUTH_GOOGLE_ERROR_REDIRECT_URL=http://localhost:3000/auth/google/error
+# Required when AUTH_GOOGLE_ENABLED=true. Use at least 32 random characters.
+SESSION_SECRET=
+AUTH_FACEBOOK_ENABLED=false
+AUTH_MOBILE_OTP_ENABLED=false
+AUTH_MAGIC_LINK_ENABLED=false
+
+RBAC_CACHE_TTL_SECONDS=60
+# Path is the only supported mode in this starter phase.
+ORG_CONTEXT_MODE=path
+
+NODE_ENV=development
+PORT=3000
+
+# Optional local bootstrap values used by npm run seed:test-user-org.
+TEST_USER_EMAIL=owner@example.com
+TEST_USER_PASSWORD=
+TEST_USER_DISPLAY_NAME=Starter Owner
+TEST_ORG_NAME=Demo Organisation
+TEST_ORG_SLUG=demo

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

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - name: Start native PostgreSQL
+        run: |
+          sudo systemctl start postgresql.service
+          sudo -u postgres psql -c "ALTER USER postgres PASSWORD 'postgres';"
+      - name: Install dependencies
+        run: npm install
+      - name: Create databases
+        run: npm run db:create
+      - name: Validate Prisma schema
+        run: npx prisma validate
+      - name: Generate Prisma client
+        run: npm run prisma:generate
+      - name: Deploy migrations
+        run: npm run prisma:deploy
+      - name: Lint
+        run: npm run lint
+      - name: Build
+        run: npm run build
+      - name: Unit tests
+        run: npm test
+      - name: E2E tests
+        run: npm run test:e2e

package/template/.husky/pre-commit

@@ -0,0 +1 @@
+npx lint-staged