@navneet_25/tempjs 1.1.0 → 2.0.0

package/cli/index.js

@@ -1,8 +1,6 @@
 #!/usr/bin/env node
 
 import { execSync } from "node:child_process";
-import { createInterface } from "node:readline/promises";
-import { stdin as input, stdout as output } from "node:process";
 import { loadManifest, getPackageRoot, resolveRepositoryConfig } from "./config.js";
 import {
   promptTheme,
@@ -12,56 +10,69 @@ import {
 } from "./theme-manager.js";
 import { promptAndApplyBrand } from "./brand-manager.js";
 import { promptAndSetupDb } from "./db-setup.js";
+import { printTemplateInfo } from "./info.js";
+import { parseArgs, toCliOptions } from "./parse-args.js";
 import {
   copyTemplate,
   findConflictingPaths,
   isDirectoryEmpty,
   listDirectoryEntries,
-  removeDirectory,
   targetHasGitRepo,
 } from "./copy.js";
-import { fetchTemplateFromGitHub, resolveLocalTemplate } from "./fetch.js";
+import { writeProjectStamp } from "./project-stamp.js";
+import { printFetchComplete } from "./progress.js";
+import { confirmYesNo } from "./prompt.js";
+import { resolveTemplateSource } from "./template-resolver.js";
+import { runUpdate } from "./update.js";
 
 const HELP_TEXT = `
 tempjs — instantiate project templates from GitHub
 
 USAGE
   tempjs list
+  tempjs info <template-id>
   tempjs <template-id> [options]
-  tempjs <template-id> config     Initialize with interactive theme, typography, brand & database setup
-  tempjs theme                    Change the project's theme in an initialized directory
-  tempjs font                     Change the project's font styling in an initialized directory
-  tempjs brand                    Configure the brand & contact info in an initialized directory
-  tempjs init-db                  Configure .env and sync database schema in an initialized directory
+  tempjs <template-id> config     Interactive theme, typography, brand & database setup
+  tempjs update [--check | --merge]
+  tempjs theme                    Change theme in an initialized project
+  tempjs font                     Change font styling in an initialized project
+  tempjs brand                    Configure brand & contact info
+  tempjs init-db                  Configure .env and sync database schema
   tempjs --help
 
+UPDATE
+  tempjs update --check           Show diff vs latest template (read-only)
+  tempjs update --merge           Apply non-conflicting template updates only
+  tempjs update --merge --yes     Apply without confirmation prompt
+
 OPTIONS
-  --config      Prompt for full interactive setup (theme, font, brand, db) during initialization
-  --force       Overwrite existing files in the current directory
-  --remote      Fetch from GitHub even if a local template copy exists
-  --init-git    Run git init after copying the template
-  --help        Show this help message
+  --config          Run full setup (theme, font, brand, database) after copying
+  --yes, -y         Skip all prompts
+  --no-prompt       Same as --yes
+  --force, -f       Overwrite existing files without prompting
+  --remote          Fetch from GitHub even if a local template copy exists
+  --init-git        Run git init after copying the template
+
+  (See tempjs --help for theme, brand, and database flags.)
 
 EXAMPLES
   mkdir hotel-client && cd hotel-client
   tempjs hotel config
-  tempjs brand
-  tempjs init-db
+
+  tempjs update --check
+  tempjs update --merge --yes
 
 ENVIRONMENT
-  TEMPLATES_REPO_URL       GitHub repo URL or owner/repo (overrides templates.json)
+  TEMPLATES_REPO_URL       GitHub repo URL or owner/repo
   TEMPLATES_REPO_OWNER     GitHub owner/username
   TEMPLATES_REPO_REPO      GitHub repository name
   TEMPLATES_REPO_BRANCH    Branch name (default: main)
   TEMPLATE_USE_REMOTE=1    Always fetch from GitHub
-  GITHUB_TOKEN / GH_TOKEN    Optional — required only for private repositories
-
-CONFIGURATION
-  Repository and template mappings live in templates.json at the package root.
+  GITHUB_TOKEN / GH_TOKEN  Optional — private repositories only
 `;
 
 /**
- * @param {Record<string, { name: string, description: string }>} templates
+ * @param {Record<string, import('./config.js').TemplateEntry>} templates
  */
 function printTemplateList(templates) {
   console.log("Available templates:\n");
@@ -70,41 +81,20 @@ function printTemplateList(templates) {
 
   for (const id of ids) {
     const entry = templates[id];
-    console.log(`${id.padEnd(idWidth + 2)}${entry.name}`);
+    const version = entry.version ? ` v${entry.version}` : "";
+    console.log(`${id.padEnd(idWidth + 2)}${entry.name}${version}`);
     if (entry.description) {
       console.log(`${"".padEnd(idWidth + 2)}${entry.description}`);
     }
-  }
-  console.log("");
-}
-
-/**
- * @param {string[]} argv
- */
-function parseArgs(argv) {
-  const flags = {
-    force: false,
-    remote: false,
-    initGit: false,
-    help: false,
-    config: false,
-  };
-  const positionals = [];
-
-  for (const arg of argv) {
-    if (arg === "--force") flags.force = true;
-    else if (arg === "--remote") flags.remote = true;
-    else if (arg === "--init-git") flags.initGit = true;
-    else if (arg === "--help" || arg === "-h") flags.help = true;
-    else if (arg === "--config") flags.config = true;
-    else if (arg.startsWith("-")) {
-      throw new Error(`Unknown option: ${arg}`);
-    } else {
-      positionals.push(arg);
+    if (entry.tags?.length) {
+      console.log(`${"".padEnd(idWidth + 2)}[${entry.tags.join(", ")}]`);
+    }
+    if (entry.stack?.length) {
+      console.log(`${"".padEnd(idWidth + 2)}${entry.stack.slice(0, 4).join(" · ")}`);
     }
   }
-
-  return { flags, positionals };
+  console.log("");
+  console.log("Run `tempjs info <template-id>` for full details.\n");
 }
 
 /**
@@ -123,24 +113,10 @@ function printConflictWarning(conflicts) {
   console.log("");
 }
 
-/**
- * @param {boolean} force
- */
-async function confirmOverwrite(force) {
-  if (force) return true;
-  const rl = createInterface({ input, output });
-  try {
-    const answer = await rl.question("Continue? [y/N] ");
-    return answer.trim().toLowerCase() === "y" || answer.trim().toLowerCase() === "yes";
-  } finally {
-    rl.close();
-  }
-}
-
 /**
  * @param {string} targetDir
  * @param {string} templateId
- * @param {{ force: boolean, remote: boolean, initGit: boolean }} flags
+ * @param {import('./parse-args.js').CliFlags} flags
  * @param {boolean} runWithConfig
  */
 async function runTemplate(targetDir, templateId, flags, runWithConfig = false) {
@@ -156,30 +132,22 @@ async function runTemplate(targetDir, templateId, flags, runWithConfig = false)
 
   const repo = resolveRepositoryConfig(manifest.repository);
   const packageRoot = getPackageRoot();
+  const cliOptions = toCliOptions(flags);
   const useRemote =
     flags.remote ||
     process.env.TEMPLATE_USE_REMOTE === "1" ||
     process.env.TEMPLATE_USE_REMOTE === "true";
 
-  let sourceDir = null;
-  let cleanupDir = null;
+  let resolved = null;
 
   try {
-    if (!useRemote) {
-      sourceDir = await resolveLocalTemplate(
-        packageRoot,
-        repo.templatesPath,
-        entry.directory
-      );
-    }
-
-    if (!sourceDir) {
-      console.log(`Fetching template "${templateId}" from ${repo.owner}/${repo.repo}...`);
-      sourceDir = await fetchTemplateFromGitHub(repo, entry.directory);
-      cleanupDir = sourceDir.replace(/[/\\]template$/, "");
-    } else {
-      console.log(`Using local template "${templateId}"...`);
-    }
+    resolved = await resolveTemplateSource({
+      repo,
+      packageRoot,
+      templateDirectory: entry.directory,
+      useRemote,
+    });
+    printFetchComplete({ templateId, stats: resolved.stats });
 
     if (targetHasGitRepo(targetDir)) {
       console.warn(
@@ -189,19 +157,20 @@ async function runTemplate(targetDir, templateId, flags, runWithConfig = false)
 
     const entries = listDirectoryEntries(targetDir);
     const hasContent = entries.length > 0;
+    const autoConfirm = flags.force || flags.yes;
 
     if (hasContent && !flags.force) {
-      const conflicts = findConflictingPaths(sourceDir, targetDir);
+      const conflicts = findConflictingPaths(resolved.templateRoot, targetDir);
       if (conflicts.length > 0) {
         printConflictWarning(conflicts);
-        const confirmed = await confirmOverwrite(false);
+        const confirmed = await confirmYesNo("Continue? [y/N] ", autoConfirm);
         if (!confirmed) {
           console.log("Aborted.");
           return;
         }
       } else if (!isDirectoryEmpty(targetDir)) {
         console.log("Current directory is not empty, but no files would be overwritten.");
-        const confirmed = await confirmOverwrite(false);
+        const confirmed = await confirmYesNo("Continue? [y/N] ", autoConfirm);
         if (!confirmed) {
           console.log("Aborted.");
           return;
@@ -210,7 +179,17 @@ async function runTemplate(targetDir, templateId, flags, runWithConfig = false)
     }
 
     const allowOverwrite = flags.force || hasContent;
-    copyTemplate(sourceDir, targetDir, { force: allowOverwrite });
+    copyTemplate(resolved.templateRoot, targetDir, { force: allowOverwrite });
+
+    await writeProjectStamp(targetDir, {
+      templateId,
+      templateVersion: entry.version ?? "0.0.0",
+      templateDirectory: entry.directory,
+      repository: `${repo.owner}/${repo.repo}`,
+      branch: repo.branch,
+      sourceDir: resolved.templateRoot,
+      isUpdate: false,
+    });
 
     if (flags.initGit && !targetHasGitRepo(targetDir)) {
       execSync("git init", { cwd: targetDir, stdio: "inherit" });
@@ -218,18 +197,16 @@ async function runTemplate(targetDir, templateId, flags, runWithConfig = false)
 
     if (runWithConfig) {
       console.log("\nConfiguring project theme and typography...");
-      const selectedTheme = await promptTheme("theme1");
-      const selectedFont = await promptFont("default");
+      const selectedTheme = await promptTheme("theme1", cliOptions);
+      const selectedFont = await promptFont("default", cliOptions);
       await applyThemeAndFont(targetDir, selectedTheme, selectedFont);
 
-      // Interactive Brand & Contact Details configuration
-      await promptAndApplyBrand(targetDir);
-
-      // Environment & Database auto-setup
-      await promptAndSetupDb(targetDir);
+      await promptAndApplyBrand(targetDir, cliOptions);
+      await promptAndSetupDb(targetDir, cliOptions);
     }
 
     console.log(`\nTemplate "${entry.name}" created successfully in ${targetDir}`);
+    console.log(`Stamped .tempjs.json (template v${entry.version ?? "0.0.0"})`);
     console.log("\nNext steps:");
     console.log("  pnpm install   # or npm install");
     console.log("  pnpm dev       # start development server");
@@ -247,8 +224,8 @@ async function runTemplate(targetDir, templateId, flags, runWithConfig = false)
     console.error(`Error: ${error instanceof Error ? error.message : String(error)}`);
     process.exitCode = 1;
   } finally {
-    if (cleanupDir) {
-      removeDirectory(cleanupDir);
+    if (resolved) {
+      resolved.release();
     }
   }
 }
@@ -258,33 +235,87 @@ async function runTemplate(targetDir, templateId, flags, runWithConfig = false)
  */
 async function main(argv) {
   const { flags, positionals } = parseArgs(argv);
-  let command = positionals[0];
+  const command = positionals[0];
 
   if (flags.help || command === "help" || (!command && argv.length === 0)) {
     console.log(HELP_TEXT.trim());
     return;
   }
 
-  if (command === "theme" || command === "font" || command === "brand" || command === "init-db") {
+  const manifest = loadManifest();
+  const repo = resolveRepositoryConfig(manifest.repository);
+  const cliOptions = toCliOptions(flags);
+
+  if (command === "list") {
+    printTemplateList(manifest.templates);
+    return;
+  }
+
+  if (command === "info") {
+    const templateId = positionals[1];
+    if (!templateId) {
+      console.error("Usage: tempjs info <template-id>");
+      console.error("Run `tempjs list` to see available templates.");
+      process.exitCode = 1;
+      return;
+    }
+    const entry = manifest.templates[templateId];
+    if (!entry) {
+      console.error(`Unknown template: ${templateId}`);
+      console.error("Run `tempjs list` to see available templates.");
+      process.exitCode = 1;
+      return;
+    }
+    printTemplateInfo(templateId, entry, repo);
+    return;
+  }
+
+  if (command === "update") {
+    const hasCheck = flags.updateCheck || argv.includes("--check");
+    const hasMerge = flags.updateMerge || argv.includes("--merge");
+
+    if (!hasCheck && !hasMerge) {
+      console.error("Usage: tempjs update --check | tempjs update --merge [--yes]");
+      process.exitCode = 1;
+      return;
+    }
+
+    const targetDir = process.cwd();
+    await runUpdate(targetDir, flags, { checkOnly: hasCheck && !hasMerge });
+    return;
+  }
+
+  if (
+    command === "theme" ||
+    command === "font" ||
+    command === "brand" ||
+    command === "init-db"
+  ) {
     const targetDir = process.cwd();
     const currentConfig = getSavedConfig(targetDir);
 
     if (command === "theme") {
-      const selectedTheme = await promptTheme(currentConfig.theme || "theme1");
-      await applyThemeAndFont(targetDir, selectedTheme, currentConfig.font || "default");
+      const selectedTheme = await promptTheme(currentConfig.theme || "theme1", cliOptions);
+      const selectedFont = await promptFont(currentConfig.font || "default", {
+        ...cliOptions,
+        yes: cliOptions.yes || Boolean(cliOptions.font),
+      });
+      await applyThemeAndFont(targetDir, selectedTheme, selectedFont);
     } else if (command === "font") {
-      const selectedFont = await promptFont(currentConfig.font || "default");
-      await applyThemeAndFont(targetDir, currentConfig.theme || "theme1", selectedFont);
+      const selectedFont = await promptFont(currentConfig.font || "default", cliOptions);
+      await applyThemeAndFont(
+        targetDir,
+        currentConfig.theme || "theme1",
+        selectedFont
+      );
     } else if (command === "brand") {
-      await promptAndApplyBrand(targetDir);
+      await promptAndApplyBrand(targetDir, cliOptions);
     } else if (command === "init-db") {
-      await promptAndSetupDb(targetDir);
+      await promptAndSetupDb(targetDir, cliOptions);
     }
     return;
   }
 
-  const manifest = loadManifest();
-
   let runWithConfig = flags.config;
   if (positionals.length >= 2 && positionals[1] === "config") {
     runWithConfig = true;

package/cli/info.js

@@ -0,0 +1,88 @@
+import { loadManifest, resolveRepositoryConfig } from "./config.js";
+
+/**
+ * @param {string} templateId
+ * @param {import('./config.js').TemplateEntry} entry
+ * @param {import('./config.js').RepositoryConfig} repo
+ */
+export function printTemplateInfo(templateId, entry, repo) {
+  const lines = [];
+
+  lines.push(`${entry.name} (${templateId})`);
+  lines.push("=".repeat(Math.min(60, entry.name.length + templateId.length + 4)));
+  lines.push("");
+
+  if (entry.description) {
+    lines.push(entry.description);
+    lines.push("");
+  }
+
+  if (entry.version) {
+    lines.push(`Version:          ${entry.version}`);
+  }
+
+  if (entry.stack?.length) {
+    lines.push(`Stack:            ${entry.stack.join(", ")}`);
+  }
+
+  if (entry.node) {
+    lines.push(`Node.js:          ${entry.node}`);
+  }
+
+  if (entry.packageManager) {
+    lines.push(`Package manager:  ${entry.packageManager}`);
+  }
+
+  if (entry.setupTime) {
+    lines.push(`Typical setup:    ${entry.setupTime}`);
+  }
+
+  if (entry.docker !== undefined) {
+    lines.push(`Docker support:   ${entry.docker ? "Yes (docker-compose.yml)" : "No"}`);
+  }
+
+  if (entry.tags?.length) {
+    lines.push(`Tags:             ${entry.tags.join(", ")}`);
+  }
+
+  lines.push(`Source directory: ${repo.templatesPath}/${entry.directory}`);
+  lines.push(`Repository:       github.com/${repo.owner}/${repo.repo} (${repo.branch})`);
+
+  if (entry.features?.length) {
+    lines.push("");
+    lines.push("Features:");
+    for (const feature of entry.features) {
+      lines.push(`  • ${feature}`);
+    }
+  }
+
+  lines.push("");
+  lines.push("Quick start:");
+  lines.push(`  mkdir my-project && cd my-project`);
+  lines.push(`  tempjs ${templateId} config`);
+  lines.push(`  pnpm install && pnpm dev`);
+  lines.push("");
+  lines.push("Non-interactive:");
+  lines.push(
+    `  tempjs ${templateId} --config --yes --theme theme1 --name "My Brand" --db-host localhost`
+  );
+
+  if (entry.docs) {
+    lines.push("");
+    lines.push(`Docs in generated project: ${entry.docs}`);
+  }
+
+  console.log(lines.join("\n"));
+}
+
+/**
+ * @param {Record<string, import('./config.js').TemplateEntry>} templates
+ * @param {import('./config.js').RepositoryConfig} repo
+ */
+export function printAllTemplatesInfo(templates, repo) {
+  const ids = Object.keys(templates).sort();
+  for (let i = 0; i < ids.length; i++) {
+    if (i > 0) console.log("\n");
+    printTemplateInfo(ids[i], templates[ids[i]], repo);
+  }
+}

package/cli/parse-args.js

@@ -0,0 +1,156 @@
+/**
+ * @typedef {ReturnType<typeof createDefaultFlags>} CliFlags
+ */
+
+export function createDefaultFlags() {
+  return {
+    force: false,
+    remote: false,
+    initGit: false,
+    help: false,
+    config: false,
+    yes: false,
+    theme: undefined,
+    font: undefined,
+    name: undefined,
+    shortName: undefined,
+    baseUrl: undefined,
+    phone: undefined,
+    phoneDisplay: undefined,
+    countryCode: undefined,
+    email: undefined,
+    address: undefined,
+    dbHost: undefined,
+    dbPort: undefined,
+    dbUser: undefined,
+    dbPassword: undefined,
+    dbName: undefined,
+    adminUser: undefined,
+    adminPassword: undefined,
+    skipDbPush: false,
+    dbPush: false,
+    updateCheck: false,
+    updateMerge: false,
+  };
+}
+
+const FLAG_MAP = {
+  "--force": { key: "force", type: "boolean" },
+  "-f": { key: "force", type: "boolean" },
+  "--remote": { key: "remote", type: "boolean" },
+  "--init-git": { key: "initGit", type: "boolean" },
+  "--help": { key: "help", type: "boolean" },
+  "-h": { key: "help", type: "boolean" },
+  "--config": { key: "config", type: "boolean" },
+  "--yes": { key: "yes", type: "boolean" },
+  "-y": { key: "yes", type: "boolean" },
+  "--no-prompt": { key: "yes", type: "boolean" },
+  "--skip-db-push": { key: "skipDbPush", type: "boolean" },
+  "--db-push": { key: "dbPush", type: "boolean" },
+  "--check": { key: "updateCheck", type: "boolean" },
+  "--merge": { key: "updateMerge", type: "boolean" },
+  "--theme": { key: "theme", type: "string" },
+  "--font": { key: "font", type: "string" },
+  "--name": { key: "name", type: "string" },
+  "--short-name": { key: "shortName", type: "string" },
+  "--base-url": { key: "baseUrl", type: "string" },
+  "--phone": { key: "phone", type: "string" },
+  "--phone-display": { key: "phoneDisplay", type: "string" },
+  "--country-code": { key: "countryCode", type: "string" },
+  "--email": { key: "email", type: "string" },
+  "--address": { key: "address", type: "string" },
+  "--db-host": { key: "dbHost", type: "string" },
+  "--db-port": { key: "dbPort", type: "string" },
+  "--db-user": { key: "dbUser", type: "string" },
+  "--db-password": { key: "dbPassword", type: "string" },
+  "--db-name": { key: "dbName", type: "string" },
+  "--admin-user": { key: "adminUser", type: "string" },
+  "--admin-password": { key: "adminPassword", type: "string" },
+};
+
+/**
+ * @param {string[]} argv
+ */
+export function parseArgs(argv) {
+  const flags = createDefaultFlags();
+  const positionals = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+
+    if (arg.includes("=") && arg.startsWith("--")) {
+      const eqIndex = arg.indexOf("=");
+      const flagName = arg.slice(0, eqIndex);
+      const value = arg.slice(eqIndex + 1);
+      applyFlag(flags, flagName, value);
+      continue;
+    }
+
+    const spec = FLAG_MAP[arg];
+    if (spec) {
+      if (spec.type === "boolean") {
+        flags[spec.key] = true;
+      } else {
+        const value = argv[++i];
+        if (!value || value.startsWith("-")) {
+          throw new Error(`Option ${arg} requires a value`);
+        }
+        flags[spec.key] = value;
+      }
+      continue;
+    }
+
+    if (arg.startsWith("-")) {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+
+    positionals.push(arg);
+  }
+
+  return { flags, positionals };
+}
+
+/**
+ * @param {CliFlags} flags
+ * @param {string} flagName
+ * @param {string} value
+ */
+function applyFlag(flags, flagName, value) {
+  const spec = FLAG_MAP[flagName];
+  if (!spec) {
+    throw new Error(`Unknown option: ${flagName}`);
+  }
+  if (spec.type === "boolean") {
+    flags[spec.key] = value === "true" || value === "1";
+  } else {
+    flags[spec.key] = value;
+  }
+}
+
+/**
+ * @param {CliFlags} flags
+ */
+export function toCliOptions(flags) {
+  return {
+    yes: flags.yes,
+    theme: flags.theme,
+    font: flags.font,
+    name: flags.name,
+    shortName: flags.shortName,
+    baseUrl: flags.baseUrl,
+    phone: flags.phone,
+    phoneDisplay: flags.phoneDisplay,
+    countryCode: flags.countryCode,
+    email: flags.email,
+    address: flags.address,
+    dbHost: flags.dbHost,
+    dbPort: flags.dbPort,
+    dbUser: flags.dbUser,
+    dbPassword: flags.dbPassword,
+    dbName: flags.dbName,
+    adminUser: flags.adminUser,
+    adminPassword: flags.adminPassword,
+    skipDbPush: flags.skipDbPush,
+    dbPush: flags.dbPush,
+  };
+}

package/cli/progress.js

@@ -0,0 +1,33 @@
+/**
+ * @param {number} bytes
+ * @returns {string}
+ */
+export function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/**
+ * @param {number} ms
+ * @returns {string}
+ */
+export function formatDuration(ms) {
+  if (ms < 1000) return `${Math.round(ms)}ms`;
+  return `${(ms / 1000).toFixed(1)}s`;
+}
+
+/**
+ * @param {{
+ *   templateId: string,
+ *   stats: { bytes: number, files: number, durationMs: number, source?: string }
+ * }} options
+ */
+export function printFetchComplete(options) {
+  const { templateId, stats } = options;
+  const sourceLabel = stats.source === "local" ? "local copy" : "download";
+  const sizePart = stats.bytes > 0 ? `${formatBytes(stats.bytes)}, ` : "";
+  console.log(
+    `Fetching template "${templateId}"... done (${sizePart}${stats.files} files, ${formatDuration(stats.durationMs)}, ${sourceLabel})`
+  );
+}