create-hhmi-example 1.0.0

package/README.md

@@ -0,0 +1,78 @@
+# create-hhmi-example
+
+Scaffold a new HHMI-style app from the generic template. Use with:
+
+```bash
+npm create hhmi-example@latest my-project-name
+```
+
+Or with a prompt (no argument):
+
+```bash
+npm create hhmi-example@latest
+```
+
+## What it does
+
+1. Copies the bundled template into a new folder (e.g. `my-project-name/`).
+2. Renames projects and folders:
+   - `hhmiExample.Server` → `hhmiMyProjectName.Server`
+   - `hhmiexample.client` → `hhmimyprojectname.client`
+   - `hhmiExample.sln` → `hhmiMyProjectName.sln`
+   - Solution and project file names (`.csproj`, `.esproj`, `.http`) are updated to match.
+   - Client source: `pages/Example/` → `pages/MyProjectName/`, `IExampleUser.ts` → `IMyProjectNameUser.ts`, `ExampleConfig.tsx` → `MyProjectNameConfig.tsx`, etc.
+3. Replaces all generic tokens in file contents with your project name (see **Substitution rules** below).
+4. Runs `npm install` in the client folder.
+
+## Substitution rules
+
+Your project name is normalized as follows:
+
+- **PascalCase** (e.g. `MyProjectName`): from `my-project-name` or `my_project_name` — used for type names, module id, labels, folder names under `pages/`, and server/project naming.
+- **lowercase** (e.g. `myprojectname`): same input with no separators — used for route segments, schema names, and the client package/folder name.
+
+| Token in template | Replaced with | Example (`my-app`) |
+|-------------------|---------------|---------------------|
+| `Example`         | PascalCase    | `MyApp`             |
+| `example`         | lowercase     | `myapp`             |
+| `hhmiExample`     | `hhmi` + PascalCase | `hhmiMyApp`   |
+| `hhmiexample`     | `hhmi` + lowercase  | `hhmimyapp`   |
+| `IExample`        | `I` + PascalCase    | `IMyApp`      |
+| `IExampleUser`    | `I` + PascalCase + `User` | `IMyAppUser` |
+| `IExampleUserSettings` | `I` + PascalCase + `UserSettings` | `IMyAppUserSettings` |
+| `ExampleConfig`, `ExampleNavItems`, etc. | PascalCase + suffix | `MyAppConfig`, `MyAppNavItems` |
+| `getExampleUser`, `manageExampleUserSettings` | `get`/`manage` + PascalCase + suffix | `getMyAppUser`, `manageMyAppUserSettings` |
+| `example.p_Get_Example_User` (stored procedure) | `{lower}.p_Get_{Pascal}_User` | `myapp.p_Get_MyApp_User` |
+| `example.p_Example_Manage_UserSettings` | `{lower}.p_{Pascal}_Manage_UserSettings` | `myapp.p_MyApp_Manage_UserSettings` |
+| Route `/example`  | `/{lower}`    | `/myapp`            |
+| "Example App" (UI) | PascalCase + ` App` | "MyApp App"   |
+
+Substitution is applied in a fixed order so that longer tokens are replaced first and generic `Example` / `example` last.
+
+## After scaffolding
+
+```bash
+cd my-project-name
+```
+
+- Open the `.sln` in Visual Studio and run the Server project (it proxies to the client), or
+- Run the client: `cd hhmimyapp.client` then `npm run dev`.
+
+Implement the stored procedures (e.g. `myapp.p_Get_MyApp_User`, `myapp.p_MyApp_Manage_UserSettings`) in your database and configure the Server’s connection string.
+
+## Local development (repo maintainers)
+
+From the repo root, the template is at `template/`. To bundle it into this package (e.g. before publishing or testing):
+
+```bash
+cd packages/create-hhmi-example
+npm install
+```
+
+The `prepare` script copies `../../template` into `./template`. To test the CLI locally:
+
+```bash
+npm link
+cd /path/to/somewhere
+npm create hhmi-example my-test-app
+```

package/copy-template.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+/**
+ * Copies the repo root template/ into this package's template/ so it can be
+ * bundled when published. Run automatically via "npm prepare" when in the repo.
+ * Excludes node_modules, dist, and other build artifacts to keep the copy small
+ * and to avoid Windows rmdir issues when re-copying.
+ */
+const fs = require("fs");
+const path = require("path");
+
+const repoRoot = path.join(__dirname, "..", "..");
+const source = path.join(repoRoot, "template");
+const dest = path.join(__dirname, "template");
+
+const EXCLUDE = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "obj",
+  "bin",
+  ".vs",
+  ".vscode",
+  ".tsbuildinfo",
+  "*.tsbuildinfo",
+]);
+
+function shouldExclude(name) {
+  if (EXCLUDE.has(name)) return true;
+  if (name.endsWith(".tsbuildinfo")) return true;
+  return false;
+}
+
+function copyRecursive(src, dst) {
+  const stat = fs.statSync(src);
+  if (stat.isDirectory()) {
+    if (!fs.existsSync(dst)) fs.mkdirSync(dst, { recursive: true });
+    for (const name of fs.readdirSync(src)) {
+      if (shouldExclude(name)) continue;
+      copyRecursive(path.join(src, name), path.join(dst, name));
+    }
+  } else {
+    fs.copyFileSync(src, dst);
+  }
+}
+
+function removeRecursive(dir) {
+  if (!fs.existsSync(dir)) return;
+  for (const name of fs.readdirSync(dir)) {
+    const full = path.join(dir, name);
+    if (fs.statSync(full).isDirectory()) {
+      removeRecursive(full);
+    } else {
+      try {
+        fs.unlinkSync(full);
+      } catch (e) {
+        console.warn("Could not delete file:", full, e.message);
+      }
+    }
+  }
+  try {
+    fs.rmdirSync(dir);
+  } catch (e) {
+    console.warn("Could not delete directory:", dir, e.message);
+  }
+}
+
+if (!fs.existsSync(source)) {
+  console.warn("create-hhmi-example: template not found at", source, "(skip copy)");
+  process.exit(0);
+}
+
+if (fs.existsSync(dest)) {
+  removeRecursive(dest);
+}
+copyRecursive(source, dest);
+console.log("create-hhmi-example: copied template into package");

package/index.js

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+const readline = require("readline");
+
+const TEMPLATE_DIR = path.join(__dirname, "template");
+const FALLBACK_TEMPLATE = path.join(__dirname, "..", "..", "template");
+
+function toPascalCase(str) {
+  const s = String(str)
+    .trim()
+    .replace(/[-_\s]+/g, " ")
+    .split(" ")
+    .filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())
+    .join("");
+  return s || "Example";
+}
+
+function toLowerNoSeparators(str) {
+  return String(str)
+    .trim()
+    .toLowerCase()
+    .replace(/[-_\s]+/g, "");
+}
+
+function getProjectNameFromArgv() {
+  const args = process.argv.slice(2);
+  const name = args.find((a) => !a.startsWith("-"));
+  return name || null;
+}
+
+function prompt(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+function copyRecursive(src, dst) {
+  const stat = fs.statSync(src);
+  if (stat.isDirectory()) {
+    if (!fs.existsSync(dst)) fs.mkdirSync(dst, { recursive: true });
+    for (const name of fs.readdirSync(src)) {
+      copyRecursive(path.join(src, name), path.join(dst, name));
+    }
+  } else {
+    fs.copyFileSync(src, dst);
+  }
+}
+
+function renameInPlace(dir, oldName, newName) {
+  const oldPath = path.join(dir, oldName);
+  const newPath = path.join(dir, newName);
+  if (fs.existsSync(oldPath)) {
+    fs.renameSync(oldPath, newPath);
+  }
+}
+
+function walkDir(dir, fn, base = dir) {
+  if (!fs.existsSync(dir)) return;
+  for (const name of fs.readdirSync(dir)) {
+    const full = path.join(dir, name);
+    const rel = path.relative(base, full);
+    if (fs.statSync(full).isDirectory()) {
+      walkDir(full, fn, base);
+    } else {
+      fn(full, rel);
+    }
+  }
+}
+
+function applySubstitutions(filePath, replacements) {
+  let content = fs.readFileSync(filePath, "utf8");
+  for (const [from, to] of replacements) {
+    content = content.split(from).join(to);
+  }
+  fs.writeFileSync(filePath, content, "utf8");
+}
+
+function main() {
+  (async () => {
+    let projectName = getProjectNameFromArgv();
+    if (!projectName) {
+      projectName = await prompt("Project name (e.g. my-app or MyApp): ");
+    }
+    if (!projectName) {
+      console.error("A project name is required.");
+      process.exit(1);
+    }
+
+    const pascal = toPascalCase(projectName);
+    const lower = toLowerNoSeparators(projectName);
+
+    const hhmiPascal = "hhmi" + pascal;
+    const hhmiLower = "hhmi" + lower;
+
+    const targetDir = path.resolve(process.cwd(), projectName);
+    if (fs.existsSync(targetDir)) {
+      console.error(`Directory already exists: ${targetDir}`);
+      process.exit(1);
+    }
+
+    const templateSource = fs.existsSync(TEMPLATE_DIR) ? TEMPLATE_DIR : FALLBACK_TEMPLATE;
+    if (!fs.existsSync(templateSource)) {
+      console.error("Template not found. Run npm install in the create package first.");
+      process.exit(1);
+    }
+
+    console.log(`Creating app "${pascal}" in ${targetDir}...`);
+    fs.mkdirSync(targetDir, { recursive: true });
+    copyRecursive(templateSource, targetDir);
+
+    const serverOld = "hhmiExample.Server";
+    const serverNew = "hhmi" + pascal + ".Server";
+    const clientOld = "hhmiexample.client";
+    const clientNew = hhmiLower + ".client";
+    const slnOld = "hhmiExample.sln";
+    const slnNew = "hhmi" + pascal + ".sln";
+
+    const rootFiles = fs.readdirSync(targetDir);
+    for (const name of rootFiles) {
+      const full = path.join(targetDir, name);
+      if (fs.statSync(full).isDirectory()) {
+        if (name === serverOld) renameInPlace(targetDir, serverOld, serverNew);
+        else if (name === clientOld) renameInPlace(targetDir, clientOld, clientNew);
+      } else if (name === slnOld) {
+        renameInPlace(targetDir, slnOld, slnNew);
+      }
+    }
+
+    const serverDir = path.join(targetDir, serverNew);
+    const clientDir = path.join(targetDir, clientNew);
+    if (fs.existsSync(path.join(targetDir, "hhmiExample.Server"))) {
+      renameInPlace(targetDir, "hhmiExample.Server", serverNew);
+    }
+    if (fs.existsSync(path.join(targetDir, "hhmiexample.client"))) {
+      renameInPlace(targetDir, "hhmiexample.client", clientNew);
+    }
+    if (fs.existsSync(path.join(targetDir, "hhmiExample.sln"))) {
+      renameInPlace(targetDir, "hhmiExample.sln", slnNew);
+    }
+
+    const csprojOld = "hhmiExample.Server.csproj";
+    const csprojNew = "hhmi" + pascal + ".Server.csproj";
+    const esprojOld = "hhmiexample.client.esproj";
+    const esprojNew = clientNew + ".esproj";
+    const httpOld = "hhmiExample.Server.http";
+    const httpNew = "hhmi" + pascal + ".Server.http";
+
+    if (fs.existsSync(serverDir)) {
+      const serverFiles = fs.readdirSync(serverDir);
+      for (const n of serverFiles) {
+        if (n === csprojOld) renameInPlace(serverDir, csprojOld, csprojNew);
+        else if (n === httpOld) renameInPlace(serverDir, httpOld, httpNew);
+      }
+    }
+    if (fs.existsSync(clientDir)) {
+      const clientFiles = fs.readdirSync(clientDir);
+      for (const n of clientFiles) {
+        if (n === esprojOld) renameInPlace(clientDir, esprojOld, esprojNew);
+      }
+
+      const clientSrc = path.join(clientDir, "src");
+      const pagesDir = path.join(clientSrc, "pages");
+      const examplePageDir = path.join(pagesDir, "Example");
+      if (fs.existsSync(examplePageDir)) {
+        const newPageDir = path.join(pagesDir, pascal);
+        fs.renameSync(examplePageDir, newPageDir);
+        renameInPlace(newPageDir, "ExampleHomePage.tsx", pascal + "HomePage.tsx");
+        renameInPlace(newPageDir, "ExampleConfigurationPage.tsx", pascal + "ConfigurationPage.tsx");
+      }
+      const typesDir = path.join(clientSrc, "types");
+      if (fs.existsSync(typesDir)) {
+        renameInPlace(typesDir, "IExampleUser.ts", "I" + pascal + "User.ts");
+      }
+      const modulesDir = path.join(clientSrc, "components", "AppFrame", "modules");
+      if (fs.existsSync(modulesDir)) {
+        renameInPlace(modulesDir, "ExampleConfig.tsx", pascal + "Config.tsx");
+      }
+    }
+
+    const replacements = [
+      ["IExampleUser", "I" + pascal + "User"],
+      ["IExampleUserSettings", "I" + pascal + "UserSettings"],
+      ["IExamplePermissions", "I" + pascal + "Permissions"],
+      ["IExample", "I" + pascal],
+      ["ExampleConfig", pascal + "Config"],
+      ["ExampleNavItems", pascal + "NavItems"],
+      ["pages/Example/", "pages/" + pascal + "/"],
+      ["pages\\\\Example\\\\", "pages\\\\" + pascal + "\\\\"],
+      ["ExampleHomePage", pascal + "HomePage"],
+      ["ExampleConfigurationPage", pascal + "ConfigurationPage"],
+      ["resolveExamplePermissions", "resolve" + pascal + "Permissions"],
+      ["canViewExampleAdmin", "canView" + pascal + "Admin"],
+      ["getExampleUser", "get" + pascal + "User"],
+      ["manageExampleUserSettings", "manage" + pascal + "UserSettings"],
+      ["example.p_Get_Example_User", lower + ".p_Get_" + pascal + "_User"],
+      ["example.p_Example_Manage_UserSettings", lower + ".p_" + pascal + "_Manage_UserSettings"],
+      ["hhmiExample.Server", serverNew],
+      ["hhmiExample.sln", slnNew],
+      ["hhmiexample.client", clientNew],
+      ["hhmiExample", "hhmi" + pascal],
+      ["hhmiexample", hhmiLower],
+      ["/example", "/" + lower],
+      ["Example App", pascal + " App"],
+      ["Example App", pascal + " App"],
+      ["Welcome to the Example App", "Welcome to the " + pascal + " App"],
+      ["\"Example\"", '"' + pascal + '"'],
+      ["'Example'", "'" + pascal + "'"],
+      ["id: \"Example\"", "id: \"" + pascal + "\""],
+      ["label: \"Example\"", "label: \"" + pascal + "\""],
+      ["key: \"Example\"", "key: \"" + pascal + "\""],
+      ["text: 'Example'", "text: '" + pascal + "'"],
+      ["Example", pascal],
+      ["example", lower],
+    ];
+
+    walkDir(targetDir, (fullPath) => {
+      const ext = path.extname(fullPath);
+      const isText =
+        [".ts", ".tsx", ".js", ".json", ".cs", ".sln", ".csproj", ".esproj", ".http", ".md", ".html"].includes(ext) ||
+        fullPath.endsWith("tsconfig.json");
+      if (isText) {
+        try {
+          applySubstitutions(fullPath, replacements);
+        } catch (e) {
+          console.warn("Skip substitution:", fullPath, e.message);
+        }
+      }
+    });
+
+    console.log("Running npm install in client...");
+    try {
+      execSync("npm install", { cwd: clientDir, stdio: "inherit" });
+    } catch (e) {
+      console.warn("npm install in client failed. Run it manually:", clientDir);
+    }
+
+    console.log("Done. Next steps:");
+    console.log("  cd", projectName);
+    console.log("  Open", slnNew, "in Visual Studio, or run the Server project and open the client.");
+  })().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}
+
+main();

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "create-hhmi-example",
+  "version": "1.0.0",
+  "description": "Scaffold a new HHMI-style app from the generic template",
+  "bin": "index.js",
+  "scripts": {
+    "prepare": "node copy-template.js"
+  },
+  "files": [
+    "index.js",
+    "copy-template.js",
+    "template"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/template/hhmiExample.Server/Program.cs

@@ -0,0 +1,167 @@
+using System.Data;
+using System.Data.SqlClient;
+using System.Text.Json;
+
+var builder = WebApplication.CreateBuilder(args);
+
+// Add services to the container.
+// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
+builder.Services.AddEndpointsApiExplorer();
+builder.Services.AddSwaggerGen();
+
+var app = builder.Build();
+
+app.UseDefaultFiles();
+app.UseStaticFiles();
+
+// Configure the HTTP request pipeline.
+if (app.Environment.IsDevelopment())
+{
+    app.UseSwagger();
+    app.UseSwaggerUI();
+}
+
+app.UseHttpsRedirection();
+
+app.MapGet("/api/HeartBeat", () => "OK")
+    .WithName("HeartBeat")
+    .WithOpenApi();
+
+app.MapGet("/api/Environment", () => {
+    string? env = Environment.GetEnvironmentVariable("CollabEnvironment", EnvironmentVariableTarget.Process);
+    return env;
+})
+    .WithName("Environment")
+    .WithOpenApi();
+
+app.MapPost("/api/SyncData", (StandardSqlRequest standardSqlRequest) =>
+{
+    StandardObjectResponse standardObjectResponse = new StandardObjectResponse();
+    standardObjectResponse.ArrayOutput = new object[0];
+    standardObjectResponse.SingleOutput = null;
+
+    try
+    {
+        string? connString = Environment.GetEnvironmentVariable("SQLConnectionString", EnvironmentVariableTarget.Process);
+        if (connString != null)
+        {
+            using SqlConnection sqlConn = new SqlConnection(connString);
+            sqlConn.Open();
+
+            SqlCommand cmd = new SqlCommand(standardSqlRequest.StoredProcedure, sqlConn);
+            cmd.CommandTimeout = 120;
+            cmd.CommandType = CommandType.StoredProcedure;
+
+            foreach (var parameter in standardSqlRequest.Parameters)
+            {
+                if (parameter != null)
+                {
+                    if (parameter.ParameterValue == null)
+                    {
+                        cmd.Parameters.AddWithValue(parameter.ParameterName, DBNull.Value);
+                    }
+                    else
+                    {
+                        JsonElement parameterValue = (JsonElement)parameter.ParameterValue;
+                        switch (parameterValue.ValueKind.ToString())
+                        {
+                            case "String":
+                                cmd.Parameters.AddWithValue(parameter.ParameterName, parameterValue.ToString());
+                                break;
+                            case "Number":
+                                cmd.Parameters.AddWithValue(parameter.ParameterName, parameterValue.GetDecimal());
+                                break;
+                            case "True":
+                            case "False":
+                                cmd.Parameters.AddWithValue(parameter.ParameterName, parameterValue.GetBoolean());
+                                break;
+                            default:
+                                standardObjectResponse.ConfigurationError = parameter.ParameterName + ":" + parameterValue + ":" + parameterValue.ValueKind.ToString();
+                                break;
+                        }
+                    }
+                }
+            }
+
+            using SqlDataReader reader = cmd.ExecuteReader();
+            if (reader.HasRows)
+            {
+                if (standardSqlRequest.IsArray)
+                {
+                    var results = new List<object>();
+                    while (reader.Read())
+                    {
+                        var row = new Dictionary<string, object>();
+                        for (int i = 0; i < reader.FieldCount; i++)
+                        {
+                            row[reader.GetName(i)] = reader.GetValue(i);
+                        }
+                        results.Add(row);
+                    }
+                    standardObjectResponse.ArrayOutput = results.ToArray();
+                }
+                else
+                {
+                    if (reader.Read())
+                    {
+                        var row = new Dictionary<string, object>();
+                        for (int i = 0; i < reader.FieldCount; i++)
+                        {
+                            row[reader.GetName(i)] = reader.GetValue(i);
+                        }
+                        standardObjectResponse.SingleOutput = row;
+                    }
+                }
+            }
+        }
+        else
+        {
+            standardObjectResponse.ConfigurationError = "SQL Connection String has not been defined in the app settings.";
+        }
+    }
+    catch (SqlException sqlEx)
+    {
+        standardObjectResponse.ProcessingException = sqlEx.ToString();
+    }
+    catch (Exception ex)
+    {
+        standardObjectResponse.ProcessingException = ex.ToString();
+    }
+
+    return standardObjectResponse;
+})
+.WithName("SyncData")
+.WithOpenApi();
+
+app.MapFallbackToFile("/index.html");
+
+app.Run();
+
+public class StandardSqlRequest
+{
+
+    public required string StoredProcedure { get; set; }
+    public required bool IsArray { get; set; }
+
+    public required StandardSqlRequestParameter[] Parameters { get; set; }
+
+}
+
+public class StandardSqlRequestParameter
+{
+
+    public required string ParameterName { get; set; }
+
+
+    public Object? ParameterValue { get; set; }
+}
+
+public class StandardObjectResponse
+{
+    public Object? SingleOutput { get; set; }
+    public Object[]? ArrayOutput { get; set; }
+
+    public string? ConfigurationError { get; set; }
+
+    public string? ProcessingException { get; set; }
+}

package/template/hhmiExample.Server/Properties/launchSettings.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "http://json.schemastore.org/launchsettings.json",
+  "iisSettings": {
+    "windowsAuthentication": false,
+    "anonymousAuthentication": true,
+    "iisExpress": {
+      "applicationUrl": "http://localhost:34444",
+      "sslPort": 44347
+    }
+  },
+  "profiles": {
+    "http": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "launchUrl": "swagger",
+      "applicationUrl": "http://localhost:5207",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development",
+        "ASPNETCORE_HOSTINGSTARTUPASSEMBLIES": "Microsoft.AspNetCore.SpaProxy"
+      }
+    },
+    "https": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "launchUrl": "swagger",
+      "applicationUrl": "https://localhost:7086;http://localhost:5207",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development",
+        "ASPNETCORE_HOSTINGSTARTUPASSEMBLIES": "Microsoft.AspNetCore.SpaProxy"
+      }
+    },
+    "IIS Express": {
+      "commandName": "IISExpress",
+      "launchBrowser": true,
+      "launchUrl": "swagger",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development",
+        "ASPNETCORE_HOSTINGSTARTUPASSEMBLIES": "Microsoft.AspNetCore.SpaProxy"
+      }
+    }
+  }
+}

package/template/hhmiExample.Server/appsettings.Development.json

@@ -0,0 +1,8 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  }
+}

package/template/hhmiExample.Server/appsettings.json

@@ -0,0 +1,9 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  },
+  "AllowedHosts": "*"
+}