complete-cli 1.0.1-dev.0

package/file-templates/static/_cspell.config.jsonc

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json",
+  "version": "0.2",
+  "import": ["@cspell/cspell-bundled-dicts"],
+  "files": ["**"],
+  "enableFiletypes": ["*"],
+  "enableGlobDot": true,
+  "useGitignore": true,
+  "ignorePaths": [
+    "*.min.js",
+    "*.mp3",
+    "*.pyc",
+    "*.svg",
+    ".git/**",
+    ".yarn/**",
+    "bun.lock",
+    "dist/**",
+    "LICENSE",
+    "node_modules/**",
+    "package-lock.json",
+    "pnpm-lock.yaml",
+    "yarn.lock",
+  ],
+  "words": ["dbaeumer", "esbenp", "lockb", "sarisia", "tseslint", "Zamiell"],
+}

package/file-templates/static/_gitattributes

@@ -0,0 +1,37 @@
+# https://git-scm.com/docs/git-config/#Documentation/git-config.txt-coreautocrlf
+# Default value: input
+# Explicitly setting it to false prevents Git from changing line endings at any point, which can
+# prevent issues when Windows users collaborate with MacOS/Linus users.
+core.autocrlf=false
+
+# https://git-scm.com/docs/git-config/#Documentation/git-config.txt-coreignoreCase
+# Default value: false (on Linux machines) or true (on Windows machines)
+# Explicitly setting it to false prevents the issue where Windows users cannot pull down
+# casing-related file renames.
+core.ignoreCase=false
+
+# https://git-scm.com/docs/git-config/#Documentation/git-config.txt-pullrebase
+# Default value: false
+# Setting this prevents spurious merge commits:
+# https://www.endoflineblog.com/gitflow-considered-harmful
+pull.rebase=true
+
+# Convert all files to use "\n" line endings.
+* text=auto eol=lf
+
+# Specify the file type for some binary files to prevent Git from changing the line endings upon
+# cloning the repository.
+*.mp3 binary
+*.png binary
+*.wav binary
+
+# Specify the file type for some files that GitHub will not automatically characterize properly.
+# https://github.com/github/linguist/blob/master/lib/linguist/languages.yml
+.vscode/*.json linguist-language=JSON-with-Comments
+tsconfig*.json linguist-language=JSON-with-Comments
+
+# Suppress displaying changes on certain files to prevent cluttering commit diffs on GitHub.
+package-lock.json linguist-generated=true
+yarn.lock linguist-generated=true
+pnpm-lock.yaml linguist-generated=true
+bun.lockb linguist-generated=true

package/file-templates/static/eslint.config.mjs

@@ -0,0 +1,18 @@
+// This is the configuration file for ESLint, the TypeScript linter:
+// https://eslint.org/docs/latest/use/configure/
+
+// @ts-check
+
+import { completeConfigBase } from "eslint-config-complete"; // eslint-disable-line import-x/no-extraneous-dependencies
+import tseslint from "typescript-eslint"; // eslint-disable-line import-x/no-extraneous-dependencies
+
+export default tseslint.config(
+  // https://github.com/complete-ts/complete/blob/main/packages/eslint-config-complete/src/base.js
+  ...completeConfigBase,
+
+  {
+    rules: {
+      // Insert changed or disabled rules here, if necessary.
+    },
+  },
+);

package/file-templates/static/knip.config.js

@@ -0,0 +1,20 @@
+// This is the configuration file for Knip:
+// https://knip.dev/overview/configuration
+
+// @ts-check
+
+/** @type {import("knip").KnipConfig} */
+const config = {
+  ignore: [
+    "eslint.config.mjs", // ESLint is provided by "complete-lint".
+    "prettier.config.mjs", // Prettier is provided by "complete-lint".
+  ],
+  ignoreBinaries: [
+    "tsx", // This is provided by "complete-lint".
+  ],
+  ignoreDependencies: [
+    "complete-lint", // This is a linting meta-package.
+  ],
+};
+
+export default config;

package/file-templates/static/prettier.config.mjs

@@ -0,0 +1,24 @@
+// This is the configuration file for Prettier, the auto-formatter:
+// https://prettier.io/docs/en/configuration.html
+
+// @ts-check
+
+/** @type {import("prettier").Config} */
+const config = {
+  plugins: [
+    "prettier-plugin-organize-imports", // Prettier does not format imports by default.
+    "prettier-plugin-packagejson", // Prettier does not format "package.json" by default.
+  ],
+
+  overrides: [
+    // Allow proper formatting of JSONC files that have JSON file extensions.
+    {
+      files: ["**/.vscode/*.json", "**/tsconfig.json", "**/tsconfig.*.json"],
+      options: {
+        parser: "jsonc",
+      },
+    },
+  ],
+};
+
+export default config;

package/file-templates/static/scripts/build.ts

@@ -0,0 +1,5 @@
+import { $s, buildScript } from "complete-node";
+
+await buildScript(() => {
+  $s`tsc`;
+});

package/file-templates/static/scripts/lint.ts

@@ -0,0 +1,30 @@
+import { $, lintScript } from "complete-node";
+
+await lintScript(async () => {
+  await Promise.all([
+    // Use TypeScript to type-check the code.
+    $`tsc --noEmit`,
+    $`tsc --noEmit --project ./scripts/tsconfig.json`,
+
+    // Use ESLint to lint the TypeScript code.
+    // - "--max-warnings 0" makes warnings fail, since we set all ESLint errors to warnings.
+    $`eslint --max-warnings 0 .`,
+
+    // Use Prettier to check formatting.
+    // - "--log-level=warn" makes it only output errors.
+    $`prettier --log-level=warn --check .`,
+
+    // Use Knip to check for unused files, exports, and dependencies.
+    $`knip --no-progress`,
+
+    // Use CSpell to spell check every file.
+    // - "--no-progress" and "--no-summary" make it only output errors.
+    $`cspell --no-progress --no-summary .`,
+
+    // Check for unused words in the CSpell configuration file.
+    $`cspell-check-unused-words`,
+
+    // Check for template updates.
+    $`complete-cli check`,
+  ]);
+});

package/file-templates/static/scripts/tsconfig.json

@@ -0,0 +1,14 @@
+// A TypeScript configuration file, used by project scripts.
+{
+  "$schema": "https://raw.githubusercontent.com/complete-ts/complete/main/packages/complete-tsconfig/schemas/tsconfig-strict-schema.json",
+
+  "extends": [
+    // https://github.com/complete-ts/complete/blob/main/packages/complete-tsconfig/tsconfig.base.json
+    "complete-tsconfig/tsconfig.base.json",
+
+    // https://github.com/complete-ts/complete/blob/main/packages/complete-tsconfig/tsconfig.node.json
+    "complete-tsconfig/tsconfig.node.json",
+  ],
+
+  "include": ["*.ts"],
+}

package/file-templates/static/src/main.ts

@@ -0,0 +1,5 @@
+main();
+
+function main() {
+  console.log("Hello world.");
+}

package/file-templates/static/tsconfig.json

@@ -0,0 +1,12 @@
+// The configuration file for TypeScript.
+{
+  "$schema": "https://raw.githubusercontent.com/complete-ts/complete/main/packages/complete-tsconfig/schemas/tsconfig-strict-schema.json",
+
+  "extends": [
+    // https://github.com/complete-ts/complete/blob/main/packages/complete-tsconfig/tsconfig.base.json
+    "complete-tsconfig/tsconfig.base.json",
+
+    // https://github.com/complete-ts/complete/blob/main/packages/complete-tsconfig/tsconfig.node.json
+    "complete-tsconfig/tsconfig.node.json",
+  ],
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "complete-cli",
+  "version": "1.0.1-dev.0",
+  "description": "A command line tool for bootstrapping TypeScript projects.",
+  "keywords": [
+    "typescript"
+  ],
+  "homepage": "https://complete-ts.github.io/",
+  "bugs": {
+    "url": "https://github.com/complete-ts/complete/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/complete-ts/complete.git"
+  },
+  "license": "MIT",
+  "author": "Zamiell",
+  "type": "module",
+  "bin": {
+    "complete-cli": "./dist/main.js"
+  },
+  "files": [
+    "dist",
+    "file-templates",
+    "src",
+    "LICENSE",
+    "package.json",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsx ./scripts/build.ts",
+    "lint": "tsx ./scripts/lint.ts",
+    "start": "tsx ./src/main.ts",
+    "test": "glob \"./src/**/*.test.ts\" --cmd=\"node --import tsx --test --test-reporter spec\""
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.10.0",
+    "chalk": "^5.4.1",
+    "clipanion": "^4.0.0-rc.4",
+    "complete-common": "^1.0.1",
+    "complete-node": "^1.7.4",
+    "klaw-sync": "^6.0.0",
+    "yaml": "^2.7.0"
+  },
+  "devDependencies": {
+    "@types/klaw-sync": "^6.0.5",
+    "@types/node": "^22.13.4",
+    "@types/prompt": "^1.1.9",
+    "complete-node": "^1.7.4",
+    "eslint-plugin-sort-exports": "^0.9.1",
+    "glob": "^11.0.1",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.24.1",
+    "unbuild": "^3.3.1"
+  },
+  "engines": {
+    "node": ">= 20.11.0"
+  }
+}

package/src/commands/CheckCommand.ts

@@ -0,0 +1,249 @@
+import chalk from "chalk";
+import { Command, Option } from "clipanion";
+import { ReadonlySet } from "complete-common";
+import {
+  $s,
+  deleteFileOrDirectory,
+  fatalError,
+  isDirectory,
+  isFile,
+  readFile,
+  writeFile,
+} from "complete-node";
+import klawSync from "klaw-sync";
+import path from "node:path";
+import {
+  ACTION_YML,
+  ACTION_YML_TEMPLATE_PATH,
+  CWD,
+  TEMPLATES_DYNAMIC_DIR,
+  TEMPLATES_STATIC_DIR,
+} from "../constants.js";
+import { getTruncatedText } from "./check/getTruncatedText.js";
+
+const URL_PREFIX =
+  "https://raw.githubusercontent.com/complete-ts/complete/main/packages/complete-cli/file-templates";
+
+export class CheckCommand extends Command {
+  static override paths = [["check"], ["c"]];
+
+  ignore = Option.String("-i,--ignore", {
+    description: "Comma separated list of file names to ignore.",
+  });
+
+  verbose = Option.Boolean("-v,--verbose", false, {
+    description: "Enable verbose output.",
+  });
+
+  static override usage = Command.Usage({
+    description:
+      "Check the template files of the current TypeScript project to see if they are up to date.",
+  });
+
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async execute(): Promise<void> {
+    let oneOrMoreErrors = false;
+    const ignore = this.ignore ?? "";
+    const ignoreFileNames = ignore.split(",");
+    const ignoreFileNamesSet = new ReadonlySet(ignoreFileNames);
+
+    // First, check the static files.
+    if (
+      checkTemplateDirectory(
+        TEMPLATES_STATIC_DIR,
+        ignoreFileNamesSet,
+        this.verbose,
+      )
+    ) {
+      oneOrMoreErrors = true;
+    }
+
+    // Second, check dynamic files that require specific logic.
+    if (checkIndividualFiles(ignoreFileNamesSet, this.verbose)) {
+      oneOrMoreErrors = true;
+    }
+
+    if (oneOrMoreErrors) {
+      fatalError("The check command failed.");
+    }
+  }
+}
+
+function checkTemplateDirectory(
+  templateDirectory: string,
+  ignoreFileNamesSet: ReadonlySet<string>,
+  verbose: boolean,
+): boolean {
+  let oneOrMoreErrors = false;
+
+  for (const klawItem of klawSync(templateDirectory)) {
+    const templateFilePath = klawItem.path;
+
+    if (isDirectory(templateFilePath)) {
+      continue;
+    }
+
+    const originalFileName = path.basename(templateFilePath);
+    if (originalFileName === "main.ts") {
+      continue;
+    }
+
+    const relativeTemplateFilePath = path.relative(
+      templateDirectory,
+      templateFilePath,
+    );
+    const templateFileName = path.basename(relativeTemplateFilePath);
+
+    let projectFilePath = path.join(CWD, relativeTemplateFilePath);
+    switch (templateFileName) {
+      case "_cspell.config.jsonc": {
+        projectFilePath = path.join(
+          projectFilePath,
+          "..",
+          "cspell.config.jsonc",
+        );
+        break;
+      }
+
+      case "_gitattributes": {
+        projectFilePath = path.join(projectFilePath, "..", ".gitattributes");
+        break;
+      }
+
+      default: {
+        break;
+      }
+    }
+
+    const projectFileName = path.basename(projectFilePath);
+    if (ignoreFileNamesSet.has(projectFileName)) {
+      continue;
+    }
+
+    if (!compareTextFiles(projectFilePath, templateFilePath, verbose)) {
+      oneOrMoreErrors = true;
+    }
+  }
+
+  return oneOrMoreErrors;
+}
+
+function checkIndividualFiles(
+  ignoreFileNamesSet: ReadonlySet<string>,
+  verbose: boolean,
+) {
+  let oneOrMoreErrors = false;
+
+  if (!ignoreFileNamesSet.has(ACTION_YML)) {
+    const templateFilePath = ACTION_YML_TEMPLATE_PATH;
+    const relativeTemplateFilePath = path.relative(
+      TEMPLATES_DYNAMIC_DIR,
+      templateFilePath,
+    );
+    const projectFilePath = path.join(CWD, relativeTemplateFilePath);
+    if (!compareTextFiles(projectFilePath, templateFilePath, verbose)) {
+      oneOrMoreErrors = true;
+    }
+  }
+
+  return oneOrMoreErrors;
+}
+
+/** @returns Whether the project file is valid in reference to the template file. */
+function compareTextFiles(
+  projectFilePath: string,
+  templateFilePath: string,
+  verbose: boolean,
+): boolean {
+  if (!isFile(projectFilePath)) {
+    console.log(`Failed to find the following file: ${projectFilePath}`);
+    printTemplateLocation(templateFilePath);
+
+    return false;
+  }
+
+  const projectFileObject = getTruncatedFileText(
+    projectFilePath,
+    new Set(),
+    new Set(),
+  );
+
+  const templateFileObject = getTruncatedFileText(
+    templateFilePath,
+    projectFileObject.ignoreLines,
+    projectFileObject.linesBeforeIgnore,
+  );
+
+  if (projectFileObject.text === templateFileObject.text) {
+    return true;
+  }
+
+  console.log(
+    `The contents of the following file do not match: ${chalk.red(
+      projectFilePath,
+    )}`,
+  );
+  printTemplateLocation(templateFilePath);
+
+  if (verbose) {
+    const originalTemplateFile = readFile(templateFilePath);
+    const originalProjectFile = readFile(projectFilePath);
+
+    console.log("--- Original template file: ---\n");
+    console.log(originalTemplateFile);
+    console.log();
+    console.log("--- Original project file: ---\n");
+    console.log(originalProjectFile);
+    console.log();
+    console.log("--- Parsed template file: ---\n");
+    console.log(templateFileObject.text);
+    console.log();
+    console.log("--- Parsed project file: ---\n");
+    console.log(projectFileObject.text);
+    console.log();
+  }
+
+  const tempProjectFilePath = path.join(CWD, "tempProjectFile.txt");
+  const tempTemplateFilePath = path.join(CWD, "tempTemplateFile.txt");
+
+  writeFile(tempProjectFilePath, projectFileObject.text);
+  writeFile(tempTemplateFilePath, templateFileObject.text);
+
+  $s`diff ${tempProjectFilePath} ${tempTemplateFilePath} --ignore-blank-lines`;
+
+  deleteFileOrDirectory(tempProjectFilePath);
+  deleteFileOrDirectory(tempTemplateFilePath);
+
+  return false;
+}
+
+function getTruncatedFileText(
+  filePath: string,
+  ignoreLines: ReadonlySet<string>,
+  linesBeforeIgnore: ReadonlySet<string>,
+) {
+  const fileName = path.basename(filePath);
+  const fileContents = readFile(filePath);
+
+  return getTruncatedText(
+    fileName,
+    fileContents,
+    ignoreLines,
+    linesBeforeIgnore,
+  );
+}
+
+function printTemplateLocation(templateFilePath: string) {
+  const unixPath = templateFilePath.split(path.sep).join(path.posix.sep);
+  const match = unixPath.match(/.+\/file-templates\/(?<urlSuffix>.+)/);
+  if (match === null || match.groups === undefined) {
+    fatalError(`Failed to parse the template file path: ${templateFilePath}`);
+  }
+  const { urlSuffix } = match.groups;
+
+  console.log(
+    `You can find the template at: ${chalk.green(
+      `${URL_PREFIX}/${urlSuffix}`,
+    )}\n`,
+  );
+}

package/src/commands/InitCommand.ts

@@ -0,0 +1,105 @@
+import { Command, Option } from "clipanion";
+import path from "node:path";
+import { promptGitHubRepoOrGitRemoteURL } from "../git.js";
+import { promptEnd, promptStart } from "../prompt.js";
+import { checkIfProjectPathExists } from "./init/checkIfProjectPathExists.js";
+import { createProject } from "./init/createProject.js";
+import { getAuthorName } from "./init/getAuthorName.js";
+import { getProjectPath } from "./init/getProjectPath.js";
+import { getPackageManagerUsedForNewProject } from "./init/packageManager.js";
+import { vsCodeInit } from "./init/vsCodeInit.js";
+
+export class InitCommand extends Command {
+  static override paths = [["init"], ["i"]];
+
+  // The first positional argument.
+  name = Option.String({
+    required: false,
+  });
+
+  yes = Option.Boolean("-y,--yes", false, {
+    description:
+      'Answer yes to every dialog option, similar to how "npm init --yes" works.',
+  });
+
+  useCurrentDirectory = Option.Boolean("--use-current-directory", false, {
+    description: "Use the current directory as the root for the project.",
+  });
+
+  customDirectory = Option.String("--custom-directory", {
+    description:
+      "Initialize the project into the specified directory (instead of creating a new one based on the name or using the current working directory).",
+  });
+
+  vsCode = Option.Boolean("--vscode", false, {
+    description: "Open the project in VSCode after initialization.",
+  });
+
+  npm = Option.Boolean("--npm", false, {
+    description: "Use npm as the package manager.",
+  });
+
+  yarn = Option.Boolean("--yarn", false, {
+    description: "Use yarn as the package manager.",
+  });
+
+  pnpm = Option.Boolean("--pnpm", false, {
+    description: "Use pnpm as the package manager.",
+  });
+
+  skipGit = Option.Boolean("--skip-git", false, {
+    description: "Do not initialize Git.",
+  });
+
+  skipInstall = Option.Boolean("--skip-install", false, {
+    description:
+      "Do not automatically install the dependencies after initializing the project.",
+  });
+
+  forceName = Option.Boolean("-f,--force-name", false, {
+    description: "Allow project names that are normally illegal.",
+  });
+
+  static override usage = Command.Usage({
+    description: "Initialize a new TypeScript project.",
+  });
+
+  async execute(): Promise<void> {
+    promptStart();
+
+    const packageManager = getPackageManagerUsedForNewProject(this);
+
+    // Prompt the end-user for some information (and validate it as we go).
+    const { projectPath, createNewDir } = await getProjectPath(
+      this.name,
+      this.useCurrentDirectory,
+      this.customDirectory,
+      this.yes,
+      this.forceName,
+    );
+    await checkIfProjectPathExists(projectPath, this.yes);
+
+    const projectName = path.basename(projectPath);
+    const authorName = await getAuthorName();
+    const gitRemoteURL = await promptGitHubRepoOrGitRemoteURL(
+      projectName,
+      this.yes,
+      this.skipGit,
+    );
+
+    // Now that we have asked the user all of the questions we need, we can create the project.
+    await createProject(
+      projectName,
+      authorName,
+      projectPath,
+      createNewDir,
+      gitRemoteURL,
+      this.skipInstall,
+      packageManager,
+    );
+
+    await vsCodeInit(projectPath, this.vsCode, this.yes);
+
+    promptEnd("Initialization completed.");
+  }
+}

package/src/commands/NukeCommand.ts

@@ -0,0 +1,17 @@
+import { Command } from "clipanion";
+import { nukeDependencies } from "complete-node";
+
+export class NukeCommand extends Command {
+  static override paths = [["nuke"], ["n"]];
+
+  static override usage = Command.Usage({
+    description:
+      'Delete the "node_modules" directory and the package lock file, then reinstall the dependencies for the project.',
+  });
+
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async execute(): Promise<void> {
+    nukeDependencies();
+    console.log("Successfully reinstalled dependencies from npm.");
+  }
+}