@no-k/hermes 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 no-k contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
+OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
+CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# @no-k/hermes
+
+Hermes CLI로 필요한 TypeScript 유틸 소스를 지정한 디렉터리에 생성합니다.
+선택한 유틸과 필요한 보조 파일은 npm 패키지에 함께 들어 있습니다.
+CLI는 Node.js 기본 모듈만 사용하며 별도 런타임 의존성이 없습니다.
+
+## 사용
+
+Node.js 22 이상이 필요합니다. 아래 명령은 공개 배포 후 사용할 수 있습니다.
+
+```bash
+npx @no-k/hermes@0.1.0 list
+npx @no-k/hermes@0.1.0 add array-chunk --dir src/lib/hermes
+```
+
+두 번째 명령은 다음 파일을 생성합니다.
+
+```text
+src/lib/hermes/
+├── array/chunk/chunk.ts
+├── array/chunk/index.ts
+└── LICENSE
+```
+
+프로젝트의 실제 경로에 맞춰 import합니다.
+
+```ts
+import { chunk } from "./lib/hermes/array/chunk";
+
+chunk([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]
+```
+
+`--dir`는 현재 작업 디렉터리 기준 상대 경로나 절대 경로를 받습니다.
+공백이 있는 경로는 따옴표로 감싸세요. 그 아래에는 유틸의 카테고리/이름 구조를 유지합니다.
+설정 파일이나 package.json이 없는 디렉터리에서도 파일 생성이 가능합니다.
+
+## 명령과 옵션
+
+| 명령/옵션 | 동작 |
+| --- | --- |
+| list | 설치 가능한 항목과 설명 출력 |
+| add <항목...> --dir <경로> | 선택한 항목과 보조 파일 생성 |
+| --dry-run | 생성·유지·교체 예정 파일만 출력 |
+| --overwrite | 내용이 다른 기존 파일 교체를 명시적으로 허용 |
+| --help | 도움말 |
+| --version | CLI 버전 |
+
+```bash
+npx @no-k/hermes@0.1.0 add array-chunk number-lcm --dir src/shared/hermes
+npx @no-k/hermes@0.1.0 add array-chunk --dir "src/my utilities" --dry-run
+```
+
+내용이 같은 기존 파일은 유지합니다. 내용이 다른 파일이 하나라도 있으면 쓰기 전에 중단합니다.
+의도적으로 바꾸려면 변경 내용을 검토한 뒤 --overwrite를 사용하세요.
+목적지의 심볼릭 링크를 통해 파일을 쓰지 않습니다.
+
+## 항목과 의존성
+
+항목 이름은 core 디렉터리 경로를 하이픈으로 연결한 이름입니다.
+Tailwind 항목에는 tailwindcss- 접두어를 붙입니다.
+
+| 항목 | 포함하는 소스 |
+| --- | --- |
+| array-chunk | 배열 분할 |
+| number-lcm | 최소공배수와 필요한 gcd |
+| algorithm-graph-dijkstra | 최단 거리와 필요한 우선순위 큐·힙 |
+| tailwindcss-cn | 클래스 병합과 설정 |
+| tailwindcss-create-tailwind-css | 설정을 공유하는 cn·classVariant |
+| string-uuid | Node.js UUID 생성 |
+
+core 항목은 외부 런타임 npm 의존성이 없습니다.
+Tailwind 항목은 clsx, tailwind-merge, tailwind-variants 중 해당 항목이 참조하는 패키지가 필요합니다.
+CLI가 필요한 설치 명령을 출력합니다. 소비 프로젝트의 패키지 매니저에 맞춰 직접 설치하세요.
+CLI는 package.json이나 lockfile을 수정하지 않습니다.
+
+Node용 항목은 @types/node 설치 명령도 안내합니다.
+string-uuid는 정적 node:crypto import 때문에 Node.js에서 사용해야 합니다.
+dom-* 항목에는 DOM API와 DOM TypeScript 타입이 필요합니다.
+현재 Tailwind 헬퍼의 병합 규칙은 Tailwind CSS 4 기준입니다.
+
+## 업데이트와 라이선스
+
+명령에서 Hermes 버전을 고정하면 같은 템플릿을 받습니다.
+안내하는 외부 의존성은 버전 범위를 사용하므로 정확한 설치 버전은 소비 프로젝트 lockfile로 관리합니다.
+이미 복사한 소스는 새 버전이 나와도 자동 변경되지 않습니다.
+업데이트할 때는 직접 수정한 부분과 공통 보조 파일의 호환성을 함께 검토하세요.
+
+ISC 라이선스입니다. 함께 생성되는 LICENSE의 저작권·허가 문구를 유지해 주세요.

package/bin/hermes.mjs

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+import { lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { validateCatalog } from "../lib/catalog.mjs";
+
+const packageDirectory = fileURLToPath(new URL("../", import.meta.url));
+const manifest = JSON.parse(readFileSync(path.join(packageDirectory, "package.json"), "utf8"));
+const help = [
+  "Hermes " + manifest.version + " — copy TypeScript utilities into your project",
+  "",
+  "Usage:",
+  "  hermes list",
+  "  hermes add <item...> --dir <directory> [--dry-run] [--overwrite]",
+  "",
+  "Options:",
+  "  -d, --dir       Destination for utility folders and LICENSE (required for add)",
+  "  --dry-run       Show the planned files without writing",
+  "  --overwrite     Replace existing files whose contents differ",
+  "  -h, --help      Show help",
+  "  -v, --version   Show version",
+  "",
+  "Example:",
+  "  npx @no-k/hermes add array-chunk --dir src/lib/hermes",
+  "",
+  "External npm dependencies are reported; they are not installed automatically.",
+].join("\n");
+
+function stat(file) {
+  try {
+    return lstatSync(file);
+  } catch (error) {
+    if (error.code === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+function destinationStat(directory, relative) {
+  let current = directory;
+  const segments = relative.split("/");
+  for (let index = -1; index < segments.length; index += 1) {
+    if (index >= 0) current = path.join(current, segments[index]);
+    const info = stat(current);
+    if (info?.isSymbolicLink()) throw new Error("Refusing to write through a symbolic link: " + current);
+    if (index < segments.length - 1 && info && !info.isDirectory()) {
+      throw new Error("Expected a directory: " + current);
+    }
+    if (index === segments.length - 1) {
+      if (info && !info.isFile()) throw new Error("Expected a regular file: " + current);
+      return info;
+    }
+  }
+}
+
+function sourceContent(relative) {
+  const directory = realpathSync(path.join(packageDirectory, "templates"));
+  const file = realpathSync(path.join(directory, relative));
+  const fromRoot = path.relative(directory, file);
+  if (path.isAbsolute(fromRoot) || fromRoot === ".." || fromRoot.startsWith(".." + path.sep)) {
+    throw new Error("Source template escapes its directory: " + relative);
+  }
+  return readFileSync(file, "utf8");
+}
+
+function add(items, options) {
+  if (!options.dir?.trim()) throw new Error("Specify a destination with --dir <directory>.");
+  const directory = path.resolve(options.dir);
+  const files = new Map();
+  for (const item of items) {
+    for (const file of item.files) {
+      if (!files.has(file)) files.set(file, sourceContent(file));
+    }
+  }
+  files.set("LICENSE", readFileSync(path.join(packageDirectory, "LICENSE"), "utf8"));
+  const plan = [...files]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([file, content]) => {
+      const destination = path.join(directory, file);
+      const existing = destinationStat(directory, file);
+      const same = existing && readFileSync(destination, "utf8") === content;
+      return { file, content, destination, action: same ? "keep" : existing ? "replace" : "create" };
+    });
+  const conflicts = plan.filter((file) => file.action === "replace");
+  if (conflicts.length && !options.overwrite) {
+    throw new Error(
+      "Existing files differ; no files were written:\n" +
+        conflicts.map((file) => "  " + file.destination).join("\n") +
+        "\nReview the changes, then use --overwrite if you want to replace them.",
+    );
+  }
+  for (const file of plan) {
+    if (!options["dry-run"] && file.action !== "keep") {
+      mkdirSync(path.dirname(file.destination), { recursive: true });
+      writeFileSync(file.destination, file.content, { flag: file.action === "create" ? "wx" : "w" });
+    }
+    console.log((options["dry-run"] ? "[dry-run] " : "") + file.action + " " + file.destination);
+  }
+  const dependencies = [...new Set(items.flatMap((item) => item.dependencies))].sort();
+  const devDependencies = [...new Set(items.flatMap((item) => item.devDependencies ?? []))].sort();
+  if (dependencies.length || devDependencies.length) {
+    console.log("\nThese utilities need npm packages. Install them in your consuming project:");
+    if (dependencies.length)
+      console.log("  npm install " + dependencies.map((value) => JSON.stringify(value)).join(" "));
+    if (devDependencies.length) {
+      console.log("  npm install --save-dev " + devDependencies.map((value) => JSON.stringify(value)).join(" "));
+    }
+  }
+  for (const item of items) {
+    if (item.runtime === "node") console.log("\n" + item.name + ": requires Node.js (imports a Node.js builtin).");
+    if (item.runtime === "dom") console.log("\n" + item.name + ": requires DOM APIs and DOM TypeScript types.");
+  }
+  console.log("\n" + (options["dry-run"] ? "Planned" : "Added") + " " + items.map((item) => item.name).join(", "));
+}
+
+function main() {
+  const { values, positionals } = parseArgs({
+    options: {
+      dir: { type: "string", short: "d" },
+      "dry-run": { type: "boolean" },
+      overwrite: { type: "boolean" },
+      help: { type: "boolean", short: "h" },
+      version: { type: "boolean", short: "v" },
+    },
+    allowPositionals: true,
+  });
+  if (values.help || (!positionals.length && !values.version)) {
+    console.log(help);
+    return;
+  }
+  if (values.version) {
+    console.log(manifest.version);
+    return;
+  }
+  const [command, ...names] = positionals;
+  if (!["list", "add"].includes(command)) throw new Error("Unknown command: " + command + ". Use --help.");
+  const catalog = validateCatalog(JSON.parse(readFileSync(path.join(packageDirectory, "catalog.json"), "utf8")));
+  if (catalog.version !== manifest.version)
+    throw new Error("The catalog version does not match the package. Rebuild the CLI.");
+  if (command === "list") {
+    if (names.length || values.dir || values.overwrite || values["dry-run"]) throw new Error("Usage: hermes list");
+    for (const item of catalog.items) console.log(item.name + "\t" + item.description);
+    return;
+  }
+  if (!names.length) throw new Error("Specify at least one item. Use 'hermes list' to see available items.");
+  const items = [...new Set(names)].map((name) => {
+    const item = catalog.items.find((candidate) => candidate.name === name);
+    if (!item) throw new Error("Unknown item: " + name + ". Use 'hermes list' to see available items.");
+    return item;
+  });
+  add(items, values);
+}
+
+try {
+  main();
+} catch (error) {
+  console.error("Hermes: " + error.message);
+  process.exitCode = 1;
+}