Merge pull request #14 from simple-frontend-dev/amazing-feedback

improve CLI tool based on user feedback

Author: jeremycolin

.changeset/afraid-facts-decide.md

@@ -0,0 +1,5 @@
+---
+"simplefrontend": minor
+---
+
+Improve edge cases such as no package managers found

README.md

@@ -1,5 +1,9 @@
 # simplefrontend, the [Simple Frontend](<[https://](https://www.simplefrontend.dev/)>) CLI
 
+A simple and straightforward CLI to help you setup and automate best practices and patterns for your frontend projects (formatting, linting, type checking) with end-to-end recipies (pre-push hook, CI/CD integration).
+
+As the CLI will auto-detect your package manager, the only requirement for it to run is to be within an existing project root folder already installed (where you should have a `package.json` and an existing lock file).
+
 ## Setup a new frontend project with patterns:
 
 ```bash

package.json

@@ -27,7 +27,8 @@
     "node": "22.x"
   },
   "scripts": {
-    "dev": "pnpm run build && node dist/cli.js",
+    "dev": "pnpm run build:dev && node dist/cli.js",
+    "build:dev": "rm -rf dist && tsc --noCheck",
     "build": "rm -rf dist && tsc",
     "test": "vitest run",
     "check:exports": "attw --pack . --ignore-rules=cjs-resolves-to-esm",

src/commands/setup.ts

@@ -1,5 +1,6 @@
 import { Argument, type Command } from "commander";
 import { isCancel, cancel, log, multiselect } from "@clack/prompts";
+import { packageManagerError } from "../utils/package-manager.js";
 import {
   installSolutions,
   type Solutions,
@@ -38,6 +39,12 @@ export function setupCommand({ program }: { program: Command }) {
       ]),
     )
     .action(async (pattern) => {
+      // This is a nicer user experience than throwing an exception for the CLI
+      if (packageManagerError) {
+        log.error(packageManagerError);
+        return;
+      }
+
       if (pattern === "pre-push") {
         await installPattern({ pattern: "pre-push" });
       } else if (pattern === "github-actions") {

src/solutions/github-actions.ts

@@ -1,20 +1,36 @@
-import { mkdirSync, writeFileSync } from "node:fs";
+import { mkdirSync, writeFileSync, existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { log } from "@clack/prompts";
 import { type Solutions } from "./install-solutions.js";
-import { getGithubActionsTemplate } from "../templates/github-actions.js";
+import { appendToWorkflowFile } from "../templates/github-actions.js";
 import { packageManager } from "../utils/package-manager.js";
 
 export function setupGithubActions({ solutions }: { solutions: Solutions }) {
   try {
-    const template = getGithubActionsTemplate({
-      agent: packageManager.name,
+    // step 1: if the folder does not exist, create it
+    if (!existsSync(resolve("./.github/workflows"))) {
+      mkdirSync(resolve("./.github/workflows"), { recursive: true });
+    }
+
+    // step 2: if the file already exists, read it to not override the existing configuration
+    let existingWorkflow = "";
+    if (existsSync(resolve("./.github/workflows/quality-checks.yml"))) {
+      existingWorkflow = readFileSync(
+        resolve("./.github/workflows/quality-checks.yml"),
+        "utf-8",
+      );
+    }
+
+    const finalWorkflowConfig = appendToWorkflowFile({
+      existingWorkflow,
       solutions,
+      agent: packageManager.name,
     });
-    mkdirSync(resolve("./.github/workflows"), { recursive: true });
+
+    // step 3: write the new workflow configuration to the file by merging the existing configuration with the template one
     writeFileSync(
       resolve("./.github/workflows/quality-checks.yml"),
-      template,
+      finalWorkflowConfig,
       "utf-8",
     );
   } catch (error: unknown) {

src/solutions/install-solutions.ts

@@ -46,7 +46,9 @@ export async function installSolutions({
 
   if (prePushHookConfirm) {
     setupPrePushHook({ solutions });
-    log.success("Sucessfully Setup pre-push hook solution: lefthook");
+    log.success(
+      "Sucessfully Setup pre-push hook solution: lefthook and created lefthook.yml",
+    );
   }
 
   const githubActionsConfirm = await confirm({
@@ -58,6 +60,8 @@ export async function installSolutions({
 
   if (githubActionsConfirm) {
     setupGithubActions({ solutions });
-    log.success("Successfully setup GitHub Actions workflow");
+    log.success(
+      "Successfully setup GitHub Actions workflow and created .github/workflows/quality-checks.yml",
+    );
   }
 }

src/solutions/prettier.ts

@@ -27,7 +27,7 @@ export function setupPrettier() {
     //   );
     // }
 
-    log.success("Successfully setup Prettier");
+    log.success("Successfully setup Prettier and created .prettierrc");
   } catch (error: unknown) {
     log.error(
       `Failed to install formatting solution: ${PACKAGE} - error: ${error}`,

src/solutions/typescript.ts

@@ -1,7 +1,7 @@
 import { existsSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import open from "open";
-import { cancel, isCancel, log, select } from "@clack/prompts";
+import { cancel, confirm, isCancel, log, select } from "@clack/prompts";
 import { packageManager, installPackage } from "../utils/package-manager.js";
 import {
   typeScriptConfigurationLibrary,
@@ -35,15 +35,21 @@ export async function setupTypescript() {
     });
 
     if (isCancel(environment)) {
-      cancel("typescript setup cancelled");
+      cancel("TypeScript setup cancelled");
       return;
     }
 
     if (environment === "browser") {
-      log.info(
-        "Browser environment has a lot of branching possibilities, I recommend you follow the recommended configurations from Vite starters at https://vite.dev/guide/#trying-vite-online",
-      );
-      await open("https://vite.dev/guide/#trying-vite-online");
+      const openViteStarter = await confirm({
+        message:
+          "For browser environments, I recommend you follow the recommended configurations from Vite starters at https://vite.dev/guide/#trying-vite-online. Do you want to open it now?",
+      });
+      if (isCancel(openViteStarter)) {
+        cancel("TypeScript setup cancelled");
+        return;
+      } else if (openViteStarter) {
+        await open("https://vite.dev/guide/#trying-vite-online");
+      }
     } else if (environment === "node") {
       // step 4: select the build context
       const buildContext = await select({
@@ -56,7 +62,7 @@ export async function setupTypescript() {
       });
 
       if (isCancel(buildContext)) {
-        cancel("typescript setup cancelled");
+        cancel("TypeScript setup cancelled");
         return;
       }
 
@@ -91,9 +97,8 @@ export async function setupTypescript() {
           JSON.stringify(typeScriptConfigurationServer, null, 2),
         );
       }
-
-      log.success("Successfully setup TypeScript");
     }
+    log.success("Successfully setup TypeScript and created tsconfig.json");
   } catch (error: unknown) {
     log.error(`Failed to install typescript - error: ${error}`);
   }

src/templates/github-actions.ts

@@ -36,14 +36,42 @@ function getAgentActionSetup(agent: AgentName) {
       ];
   }
 }
-export function getGithubActionsTemplate({
+
+function getSetupSteps(agent: AgentName) {
+  return [
+    {
+      uses: "actions/checkout@v4",
+    },
+    ...getAgentActionSetup(agent),
+    {
+      name: "Install dependencies",
+      run: `${agent} install`,
+    },
+  ];
+}
+
+function getPrettierActionSetup(agent: AgentName) {
+  return {
+    name: "Run code quality format check",
+    run: `${getExecCommand(agent)} prettier --check --ignore-unknown src`,
+  };
+}
+
+function getEslintActionSetup(agent: AgentName) {
+  return {
+    name: "Run code quality lint check",
+    run: `${getExecCommand(agent)} eslint --no-warn-ignored src`,
+  };
+}
+
+function getGithubActionsTemplate({
   agent,
   solutions,
 }: {
   agent: AgentName;
   solutions: Solutions;
 }) {
-  return yaml.stringify({
+  return {
     name: "Continuous Integration",
     on: {
       pull_request: {
@@ -58,32 +86,62 @@ export function getGithubActionsTemplate({
       "quality-checks": {
         "runs-on": "ubuntu-latest",
         steps: [
-          {
-            uses: "actions/checkout@v4",
-          },
-          ...getAgentActionSetup(agent),
-          {
-            name: "Install dependencies",
-            run: `${agent} install`,
-          },
+          ...getSetupSteps(agent),
           ...(solutions.includes("prettier")
-            ? [
-                {
-                  name: "Run code quality format check",
-                  run: `${getExecCommand(agent)} prettier --check --ignore-unknown src`,
-                },
-              ]
+            ? [getPrettierActionSetup(agent)]
             : []),
           ...(solutions.includes("eslint")
-            ? [
-                {
-                  name: "Run code quality lint check",
-                  run: `${getExecCommand(agent)} eslint --no-warn-ignored src`,
-                },
-              ]
+            ? [getEslintActionSetup(agent)]
             : []),
         ],
       },
     },
+  };
+}
+
+export function appendToWorkflowFile({
+  existingWorkflow,
+  solutions,
+  agent,
+}: {
+  existingWorkflow: string;
+  solutions: Solutions;
+  agent: AgentName;
+}) {
+  // If the workflow file is empty, return the template directly
+  if (!existingWorkflow) {
+    return yaml.stringify(getGithubActionsTemplate({ agent, solutions }));
+  }
+
+  // extend existing steps with prettier and/or eslint
+  const config = yaml.parse(existingWorkflow) ?? {};
+  const template = getGithubActionsTemplate({ agent, solutions });
+
+  const existingSteps: Array<{ name: string; run: string }> =
+    config.jobs?.["quality-checks"]?.steps ?? [];
+
+  const steps = [
+    ...existingSteps,
+    ...(solutions.includes("prettier") &&
+    !existingSteps.find((step) => step.name === "Run code quality format check")
+      ? [getPrettierActionSetup(agent)]
+      : []),
+    ...(solutions.includes("eslint") &&
+    !existingSteps.find((step) => step.name === "Run code quality lint check")
+      ? [getEslintActionSetup(agent)]
+      : []),
+  ];
+
+  return yaml.stringify({
+    ...template,
+    ...config,
+    jobs: {
+      ...config.jobs,
+      "quality-checks": {
+        "runs-on": "ubuntu-latest",
+        ...(config.jobs?.["quality-checks"] ?? {}),
+        steps,
+      },
+    },
   });
 }

src/utils/package-manager.ts

@@ -5,19 +5,21 @@ import { execSync } from "node:child_process";
 
 class PackageManagerDetector {
   public packageManager: DetectResult;
+  public packageManagerError: string | null = null;
 
   constructor() {
     const packageManager = detectSync();
     if (!packageManager) {
-      throw new Error(
-        "Not able to detect your package manager, make sure you have a lock file on disk first.",
-      );
+      this.packageManagerError =
+        "Unable to detect your package manager: simplefrontend CLI needs to run in an existing project root folder which is already installed (where you should have a `package.json` and an existing lock file).";
     }
-    this.packageManager = packageManager;
+    // this is unsafe but we stop on errors within commands
+    this.packageManager = packageManager as DetectResult;
   }
 }
 
-export const packageManager = new PackageManagerDetector().packageManager;
+export const { packageManager, packageManagerError } =
+  new PackageManagerDetector();
 
 function getDevDependencyArg(agent: AgentName) {
   switch (agent) {