virastack 0.0.1 → 1.0.1

package/LICENSE

@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/README.md

@@ -1,35 +1,111 @@
 <div align="center">
-  <img src="./public/start.jpg" alt="Vira Stack CLI" />
+
+<a href="https://github.com/virastack/start" target="_blank" rel="noreferrer">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/virastack/start/main/assets/logo-dark.png">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/virastack/start/main/assets/logo-light.png">
+    <img src="https://raw.githubusercontent.com/virastack/start/main/assets/logo-light.png" alt="ViraStack Start" height="120" style="max-width: 100%;" />
+  </picture>
+</a>
+
+*Production-grade scaffolding CLI for modern React — integrate ecosystem tools in one command.*
+
+[![ViraStack Start](https://img.shields.io/badge/ViraStack-Start-%2300bba7)](https://virastack.com/start/)
+[![npm version](https://img.shields.io/npm/v/virastack?color=blue)](https://www.npmjs.com/package/virastack)
+[![npm downloads](https://img.shields.io/npm/dt/virastack)](https://www.npmjs.com/package/virastack)
+[![Node](https://img.shields.io/badge/node-%3E%3D20.9-339933?logo=node.js&logoColor=white)](package.json)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![@virastack](https://img.shields.io/badge/-%40virastack-black?logo=x&logoColor=white)](https://x.com/virastack)
+
 </div>
 
-<br />
+---
 
-# ViraStack CLI
+### [Read the full documentation →](https://virastack.com/start/)
 
-Automated scaffolding tool to initialize and scale high-discipline ViraStack architectures.
+## Why ViraStack Start?
 
-## Explore the ViraStack Ecosystem
+- **Interactive CLI:** Interactive prompts for template selection, project naming, and ecosystem tool integration.
+- **Production-Ready Foundations:** Scaffolds Next.js or TanStack Start projects with pre-configured feature-sliced architecture.
+- **Built-in AI Protocols:** Integrates [**ViraStack AI**](https://github.com/virastack/ai) automatically — architecture rules, `AGENTS.md`, and design skills from [**Emil Kowalski**](https://github.com/emilkowalski/skills) and [**Jakub Krehel**](https://github.com/jakubkrehel/make-interfaces-feel-better) — giving your coding agents a strict "constitution" from day one.
+- **End-to-End Type Safety:** Strict TypeScript rules, Zod validation, and native package manager alignment (pnpm, npm, yarn, bun).
+- **Ecosystem Integration:** Add optional ViraStack tools (`@virastack/mask`, `@virastack/password`) seamlessly.
+
+## Quick Start
+
+**Recommended (pnpm):**
+```bash
+pnpm dlx virastack
+```
+
+**Alternatives:**
+```bash
+npx virastack
+# or
+yarn dlx virastack
+# or
+bunx virastack
+```
+
+## What it asks
+
+```text
+What is your project named?
+  virastack-app
 
-### Projects
+Which template would you like to use?
+  › Next.js App Router
+    TanStack Start
 
-- [**Next.js Boilerplate**](https://github.com/virastack/nextjs-boilerplate) - Production-ready Next.js 16+ starter template built with Tailwind CSS 4 and TypeScript.
-- [**AI Rules**](https://github.com/virastack/ai-rules) - AI-native architecture kit and high-discipline protocols for modern React applications.
-- [**Input Mask**](https://github.com/virastack/input-mask) - Lightweight, zero-dependency input masking library optimized for React Hook Form.
-- [**Password Toggle**](https://github.com/virastack/password-toggle) - Fully accessible and highly customizable password visibility hook for React.
-- [**Modern Web in 3 Minutes**](https://github.com/virastack/modern-web-in-3-minutes) - Master modern web development standards in just 3 minutes.
+Would you like multi-language (i18n) support?
+  › Yes
+    No
 
-### 🚧 Coming Soon
+Which ViraStack tools would you like to include?
+  [ ] @virastack/mask
+  [ ] @virastack/password
+```
 
-- [**Start (CLI)**](https://github.com/virastack/cli) - Automated scaffolding tool to initialize and scale high-discipline ViraStack architectures.
-- [**TanStack Boilerplate**](https://github.com/virastack/tanstack-boilerplate) - Production-ready TanStack Start starter template built with Tailwind CSS 4 and TypeScript.
-- [**Standards**](https://github.com/virastack/standards) - A unified suite of ESLint, Prettier, and architectural rules to enforce absolute code integrity.
-- [**Error Guard**](https://github.com/virastack/error-guard) - Pro-grade error handling and smart recovery protocols for zero-friction React environments.
+## Tools
+
+| Tool | Description |
+| :--- | :--- |
+| `@virastack/ai` | Pre-configured AI layer and coding rules for modern AI assistants (included in templates by default) |
+| `@virastack/mask` | Input masking and formatting (Phone, IBAN, etc.) |
+| `@virastack/password` | Password visibility toggle with customizable icons and text |
+
+## Options
+
+| Flag | Description |
+| :--- | :--- |
+| `--name <name>` | Project name (or pass as positional / `.`) |
+| `--template <name>` | `nextjs` or `tanstack` |
+| `--tools <list>` | Comma-separated tools (`mask,password`) |
+| `--i18n` / `--no-i18n` | Enable or disable the i18n template |
+| `--yes`, `-y` | Non-interactive mode (flags + defaults) |
+| `--skip-install` | Scaffold files only; skip install + AI setup |
+| `--tr` | Turkish prompts |
+| `--telemetry-disable` | Permanently disable anonymous usage tracking |
+| `-v`, `--version` | Print CLI version |
+| `-h`, `--help` | Show usage |
+
+## Telemetry
+
+To understand which tools and templates are preferred by the community, ViraStack collects strictly anonymous usage data (template, i18n choice, selected tools, package manager, and CLI version). Absolutely no personal data, project names, or file paths are collected.
+
+Opt out anytime: `pnpm dlx virastack --telemetry-disable`
+
+## Contributing
+
+Ideas and bug reports are welcome — open an [issue](https://github.com/virastack/start/issues).
+
+## Explore the ViraStack Ecosystem
 
-... and more at [**virastack.com**](https://virastack.com)
+Discover all ViraStack tools, libraries, and boilerplates at [**virastack.com**](https://virastack.com).
 
 ## License
 
-Licensed under the <a href="https://github.com/virastack/cli/blob/main/LICENSE">MIT License</a>.
+Licensed under the [MIT License](LICENSE).
 
 ## Maintainer
 

package/bin/virastack.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from "../src/index.js";
+
+main().catch((error) => {
+  console.error(error?.stack ?? error);
+  process.exitCode = 1;
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "virastack",
-  "version": "0.0.1",
-  "description": "Virastack CLI",
+  "version": "1.0.1",
+  "description": "Scaffold new projects and add tools from the ViraStack ecosystem with a single command.",
   "author": {
     "name": "Ömer Gülçiçek (ViraStack)",
     "email": "iletisim@omergulcicek.com",
@@ -11,18 +11,52 @@
   "homepage": "https://virastack.com",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/virastack/cli.git"
+    "url": "git+https://github.com/virastack/start.git"
   },
   "bugs": {
-    "url": "https://github.com/virastack/cli/issues"
+    "url": "https://github.com/virastack/start/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20.9.0"
+  },
+  "publishConfig": {
+    "access": "public"
   },
-  "main": "index.js",
   "bin": {
-    "virastack": "./index.js"
+    "virastack": "./bin/virastack.js"
   },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "templates-i18n",
+    "!src/**/*.test.js"
+  ],
   "keywords": [
     "virastack",
+    "start",
     "cli",
-    "init"
-  ]
-}
+    "create-virastack",
+    "scaffolding",
+    "boilerplate",
+    "nextjs",
+    "tanstack",
+    "react",
+    "typescript",
+    "dx"
+  ],
+  "dependencies": {
+    "@clack/prompts": "^1.7.0",
+    "cross-spawn": "^7.0.6",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "vitest": "^3.2.7"
+  },
+  "scripts": {
+    "start": "node ./bin/virastack.js",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/commands/add.js

@@ -0,0 +1,64 @@
+import path from "node:path";
+import { promises as fs } from "node:fs";
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+
+import { t, getLocale } from "../i18n.js";
+import { runCommand } from "../utils/exec.js";
+import { detectPackageManager, getAddArgs } from "../utils/package-manager.js";
+import { trackEvent } from "../utils/telemetry.js";
+import { findTool, TOOLS } from "../utils/tools.js";
+
+async function fileExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function runAdd(toolId) {
+  console.log();
+  p.intro(pc.bgMagenta(pc.black(" ViraStack ")));
+
+  const toolList = TOOLS.map((tool) => tool.id).join(", ");
+
+  if (!toolId) {
+    p.log.error(t("add.toolMissing", { list: toolList }));
+    process.exit(1);
+  }
+
+  const tool = findTool(toolId);
+  if (!tool) {
+    p.log.error(t("add.toolInvalid", { tool: toolId, list: toolList }));
+    process.exit(1);
+  }
+
+  const cwd = process.cwd();
+  if (!(await fileExists(path.join(cwd, "package.json")))) {
+    p.log.error(t("add.notAProject"));
+    process.exit(1);
+  }
+
+  const packageManager = detectPackageManager();
+  const spinner = p.spinner();
+  spinner.start(t("add.installing", { pkg: tool.package }));
+
+  try {
+    if (tool.kind === "dependency") {
+      await runCommand(packageManager, getAddArgs(packageManager, [tool.package]), { cwd });
+    } else {
+      const args = ["--yes", tool.package, "init", "--force"];
+      if (getLocale() === "tr") args.push("--tr");
+      await runCommand("npx", args, { cwd });
+    }
+    spinner.stop(t("add.done", { pkg: tool.package }));
+  } catch (error) {
+    spinner.stop(t("add.installFailed", { pkg: tool.package }));
+    p.log.error(String(error?.message ?? error));
+    process.exit(1);
+  }
+
+  await trackEvent("add", { tool: tool.id, packageManager });
+}

package/src/commands/init.js

@@ -0,0 +1,286 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import * as p from "@clack/prompts";
+import pc from "picocolors";
+
+import { t, getLocale } from "../i18n.js";
+import { copyTemplate, dirHasFiles, isDirEmpty } from "../utils/copy-template.js";
+import { runCommand } from "../utils/exec.js";
+import { initGitRepo } from "../utils/git.js";
+import { isOnline } from "../utils/is-online.js";
+import {
+  detectPackageManager,
+  getAiInitCommand,
+  getInstallArgs,
+  getInstallCommand,
+  getRunDevCommand,
+} from "../utils/package-manager.js";
+import { trackEvent, isTelemetryDisabled, hasSeenTelemetryNotice, markTelemetryNoticeShown } from "../utils/telemetry.js";
+import { TOOLS, parseToolsFlag } from "../utils/tools.js";
+import { setupEnvFile } from "../utils/setup-env.js";
+import { updatePackageJson } from "../utils/update-package-json.js";
+import { updateReadme } from "../utils/update-readme.js";
+import { validateProjectName } from "../utils/validate-project-name.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_DIR = path.resolve(__dirname, "../../templates");
+const TEMPLATES_I18N_DIR = path.resolve(__dirname, "../../templates-i18n");
+const VALID_TEMPLATES = new Set(["nextjs", "tanstack"]);
+
+function cancelAndExit() {
+  p.cancel(t("cancel"));
+  process.exit(0);
+}
+
+function failAndExit(message) {
+  p.log.error(message);
+  process.exit(1);
+}
+
+/**
+ * @param {{
+ *   name?: string,
+ *   template?: string,
+ *   i18n?: boolean,
+ *   tools?: string[] | string | true,
+ *   yes?: boolean,
+ *   skipInstall?: boolean,
+ * }} [options]
+ */
+export async function runInit(options = {}) {
+  const yes = Boolean(options.yes);
+  const skipInstall = Boolean(options.skipInstall);
+
+  console.clear();
+  p.intro(pc.bgMagenta(pc.black(" ViraStack ")));
+
+  if (!(await isTelemetryDisabled()) && !(await hasSeenTelemetryNotice())) {
+    p.log.info(t("telemetry.notice"));
+    await markTelemetryNoticeShown();
+  }
+
+  let projectNameInput = options.name;
+
+  if (projectNameInput == null) {
+    if (yes) {
+      failAndExit(t("projectName.errorNonInteractive"));
+    }
+
+    projectNameInput = await p.text({
+      message: t("projectName.message"),
+      placeholder: t("projectName.placeholder"),
+      validate: (value) => {
+        const error = validateProjectName(value);
+        if (error === "empty") return t("projectName.errorEmpty");
+        if (error === "invalid") return t("projectName.errorInvalid");
+      },
+    });
+    if (p.isCancel(projectNameInput)) return cancelAndExit();
+  } else {
+    const error = validateProjectName(projectNameInput);
+    if (error === "empty") failAndExit(t("projectName.errorEmpty"));
+    if (error === "invalid") failAndExit(t("projectName.errorInvalid"));
+  }
+
+  const useCurrentDir = projectNameInput === ".";
+  const targetDir = useCurrentDir
+    ? process.cwd()
+    : path.resolve(process.cwd(), projectNameInput);
+  const projectName = useCurrentDir ? path.basename(targetDir) : projectNameInput;
+
+  if (!(await isDirEmpty(targetDir))) {
+    if (yes) {
+      p.log.warn(
+        t("projectName.confirmNonEmptyDir", {
+          dir: useCurrentDir ? "." : projectNameInput,
+        }),
+      );
+    } else {
+      const proceed = await p.confirm({
+        message: t("projectName.confirmNonEmptyDir", {
+          dir: useCurrentDir ? "." : projectNameInput,
+        }),
+        initialValue: false,
+      });
+      if (p.isCancel(proceed) || !proceed) return cancelAndExit();
+    }
+  }
+
+  let template = options.template;
+  if (template != null && !VALID_TEMPLATES.has(template)) {
+    failAndExit(t("template.errorInvalid", { template }));
+  }
+
+  if (template == null) {
+    if (yes) {
+      template = "nextjs";
+    } else {
+      template = await p.select({
+        message: t("template.message"),
+        options: [
+          {
+            value: "nextjs",
+            label: t("template.nextjs.label"),
+            hint: t("template.nextjs.hint"),
+          },
+          {
+            value: "tanstack",
+            label: t("template.tanstack.label"),
+            hint: t("template.tanstack.hint"),
+          },
+        ],
+      });
+      if (p.isCancel(template)) return cancelAndExit();
+    }
+  }
+
+  if (template === "tanstack" && !(await dirHasFiles(path.join(TEMPLATES_DIR, "tanstack")))) {
+    p.log.warn(t("template.tanstack.notReady"));
+    template = "nextjs";
+  }
+
+  let wantsI18n = options.i18n;
+  if (wantsI18n == null) {
+    if (yes) {
+      wantsI18n = false;
+    } else {
+      wantsI18n = await p.confirm({
+        message: t("i18n.message"),
+        active: t("i18n.active"),
+        inactive: t("i18n.inactive"),
+        initialValue: false,
+      });
+      if (p.isCancel(wantsI18n)) return cancelAndExit();
+    }
+  }
+
+  if (wantsI18n && !(await dirHasFiles(path.join(TEMPLATES_I18N_DIR, template)))) {
+    p.log.warn(t("i18n.notReady"));
+    wantsI18n = false;
+  }
+
+  let tools = options.tools;
+  if (tools == null) {
+    if (yes) {
+      tools = [];
+    } else {
+      tools = await p.multiselect({
+        message: t("tools.message"),
+        required: false,
+        options: TOOLS.filter((tool) => !tool.hiddenFromInit).map((tool) => ({
+          value: tool.id,
+          label: t(`tools.${tool.id}.label`),
+          hint: t(`tools.${tool.id}.hint`),
+        })),
+      });
+      if (p.isCancel(tools)) return cancelAndExit();
+    }
+  } else {
+    tools = Array.isArray(tools) ? tools : parseToolsFlag(tools);
+  }
+
+  const packageManager = detectPackageManager();
+  const templateSourceDir = path.join(
+    wantsI18n ? TEMPLATES_I18N_DIR : TEMPLATES_DIR,
+    template,
+  );
+
+  const scaffoldSpinner = p.spinner();
+  scaffoldSpinner.start(t("scaffold.copying"));
+  await copyTemplate(templateSourceDir, targetDir);
+  await updatePackageJson(targetDir, { projectName, tools });
+  await updateReadme(targetDir, projectName);
+  await setupEnvFile(targetDir);
+  scaffoldSpinner.stop(t("scaffold.copyDone"));
+
+  const gitSpinner = p.spinner();
+  gitSpinner.start(t("scaffold.gitInit"));
+  const gitInitialized = await initGitRepo(targetDir);
+  gitSpinner.stop(
+    gitInitialized ? t("scaffold.gitInitDone") : t("scaffold.gitInitSkipped"),
+  );
+
+  const online = await isOnline();
+  let installOk = false;
+  let aiOk = false;
+  let offline = false;
+
+  if (skipInstall) {
+    p.log.info(t("scaffold.skipInstall"));
+  } else if (!online) {
+    offline = true;
+    p.log.warn(t("scaffold.offline"));
+  } else {
+    const installSpinner = p.spinner();
+    installSpinner.start(t("scaffold.installing", { pm: packageManager }));
+    try {
+      await runCommand(packageManager, getInstallArgs(packageManager), { cwd: targetDir });
+      installSpinner.stop(t("scaffold.installDone"));
+      installOk = true;
+    } catch (error) {
+      installSpinner.stop(t("scaffold.installFailed"));
+      p.log.error(String(error?.message ?? error));
+    }
+
+    if (installOk) {
+      const aiSpinner = p.spinner();
+      aiSpinner.start(t("scaffold.aiInit"));
+      try {
+        const args = ["--yes", "@virastack/ai", "init", "--force"];
+        if (getLocale() === "tr") args.push("--tr");
+        await runCommand("npx", args, { cwd: targetDir });
+        aiSpinner.stop(t("scaffold.aiInitDone"));
+        aiOk = true;
+      } catch {
+        aiSpinner.stop(t("scaffold.aiInitFailed"));
+      }
+
+      if (aiOk) {
+        try {
+          await runCommand("npx", ["--yes", "skills@latest", "add", "emilkowalski/skills", "--skill", "emil-design-eng", "-y"], { cwd: targetDir });
+          await runCommand("npx", ["--yes", "skills@latest", "add", "jakubkrehel/make-interfaces-feel-better", "-y"], { cwd: targetDir });
+        } catch {
+          p.log.warn(t("scaffold.skillsInitFailed"));
+        }
+      }
+    } else {
+      p.log.warn(t("scaffold.aiInitSkipped"));
+    }
+  }
+
+  await trackEvent("create", {
+    template,
+    i18n: wantsI18n,
+    tools,
+    packageManager,
+    installOk,
+    skipInstall,
+  });
+
+  const cdHint = useCurrentDir ? null : t("done.cd", { dir: projectName });
+  const installCmd = getInstallCommand(packageManager);
+  const aiCmd = getAiInitCommand();
+  const devCmd = getRunDevCommand(packageManager);
+
+  if (skipInstall || offline || !installOk) {
+    const outroLines = [t("done.partialTitle")];
+    if (cdHint) outroLines.push(cdHint);
+    outroLines.push(t("done.manualInstall", { cmd: installCmd }));
+    outroLines.push(t("done.manualAi", { cmd: aiCmd }));
+    outroLines.push(t("done.dev", { cmd: devCmd }));
+    if (!installOk && !offline && !skipInstall) {
+      p.log.error(t("done.installFailedNote"));
+    }
+    p.outro(outroLines.join("\n"));
+    if (!installOk && !offline && !skipInstall) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  const outroLines = [t("done.title")];
+  if (cdHint) outroLines.push(cdHint);
+  if (!aiOk) outroLines.push(t("done.manualAi", { cmd: aiCmd }));
+  outroLines.push(t("done.dev", { cmd: devCmd }));
+  p.outro(outroLines.join("\n"));
+}