@no-k/hermes 0.1.0 → 0.3.0

package/dist/bin/hermes.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { validateCatalog } from "../lib/catalog.js";
+import { parseCliArguments, resolveCommand } from "../lib/command.js";
+import { InstallExecutionError } from "../lib/install.js";
+import { readJson, readPackageVersion } from "../lib/json.js";
+import { formatFilePlan, formatInstallSummary } from "../lib/report.js";
+import { terminalText } from "../lib/terminal-text.js";
+const packageDirectory = fileURLToPath(new URL("../../", import.meta.url));
+const help = [
+    "",
+    "Usage:",
+    "  hermes",
+    "  hermes add [item...] [--dir <directory>] [--dry-run] [--overwrite]",
+    "  hermes list",
+    "",
+    "Choose categories and utilities, review destinations and files, then confirm Yes to install.",
+    "Item names and --dir prefill the wizard; they never skip confirmation.",
+    "",
+    "Options:",
+    "  -d, --dir       Initial directory for each selected scope",
+    "  --dry-run       Review the plan without writing files or config",
+    "  --overwrite     Preselect replacements on the first conflict screen",
+    "  -h, --help      Show help",
+    "  -v, --version   Show version",
+    "",
+    "Defaults: Core → src/utils/hermes; libraries → libs/hermes.",
+    "Saved paths are read from no-k.config.ts in the current directory.",
+    "Run in an interactive terminal; choose No to edit your selection.",
+    "External npm dependencies are reported; they are not installed automatically.",
+    "",
+    "Example:",
+    "  npx @no-k/hermes add number-lcm tailwindcss-cn",
+].join("\n");
+async function main() {
+    const version = readPackageVersion(path.join(packageDirectory, "package.json"));
+    const intent = resolveCommand(parseCliArguments(process.argv.slice(2)), {
+        stdinIsTTY: process.stdin.isTTY,
+        stdoutIsTTY: process.stdout.isTTY,
+    });
+    if (intent.kind === "help") {
+        console.log("Hermes " + version + " — copy TypeScript utilities into your project\n" + help);
+        return;
+    }
+    if (intent.kind === "version") {
+        console.log(version);
+        return;
+    }
+    const catalog = validateCatalog(readJson(path.join(packageDirectory, "catalog.json")));
+    if (catalog.version !== version)
+        throw new Error("The catalog version does not match the package. Rebuild the CLI.");
+    if (intent.kind === "list") {
+        for (const item of catalog.items)
+            console.log(terminalText(item.name) + "\t" + terminalText(item.description));
+        return;
+    }
+    const { runInstallWizard } = await import("../lib/install-wizard.js");
+    const { withSelectionTerminal } = await import("../lib/terminal.js");
+    const result = await withSelectionTerminal((terminal) => runInstallWizard(intent.request, catalog, packageDirectory, process.cwd(), terminal));
+    if (result.status === "cancelled") {
+        console.log(result.reason === "interrupt"
+            ? "설치를 중단했습니다."
+            : result.reason === "eof"
+                ? "터미널 입력이 종료되었습니다."
+                : "설치를 취소했습니다.");
+        process.exitCode = result.reason === "interrupt" ? 130 : result.reason === "eof" ? 1 : 0;
+        return;
+    }
+    const { plan } = result;
+    for (const file of [...plan.files, plan.configFile])
+        console.log(terminalText(formatFilePlan(file, plan.dryRun)));
+    const selected = new Set(plan.targets.flatMap((target) => target.names));
+    console.log(formatInstallSummary(plan, catalog.items.filter((item) => selected.has(item.name)).map((item) => item.name + "@" + item.version), plan.dryRun));
+}
+try {
+    await main();
+}
+catch (error) {
+    console.error("Hermes: " + terminalText(error instanceof Error ? error.message : String(error)));
+    if (error instanceof InstallExecutionError) {
+        console.error(error.phase === "config" ? "설정 저장 실패. 이미 처리된 파일:" : "설정 저장 전 중단. 이미 처리된 파일:");
+        for (const file of error.completedFiles)
+            console.error(terminalText(formatFilePlan(file, false)));
+    }
+    process.exitCode = 1;
+}

package/dist/lib/catalog-query.js

@@ -0,0 +1,63 @@
+import { UTILITY_SCOPES, } from "./catalog.js";
+function searchText(value) {
+    return value.normalize("NFKC").toLowerCase();
+}
+export function filterCatalog(catalog, filter = {}) {
+    const terms = searchText(filter.query ?? "")
+        .split(/\s+/u)
+        .filter(Boolean);
+    const scopes = filter.scopes === undefined ? undefined : new Set(filter.scopes);
+    const categories = filter.categories === undefined ? undefined : new Set(filter.categories);
+    return catalog.items.filter((item) => {
+        if (scopes && !scopes.has(item.scope))
+            return false;
+        if (categories && !categories.has(item.category))
+            return false;
+        const name = searchText(item.name);
+        const description = searchText(item.description);
+        return terms.every((term) => name.includes(term) || description.includes(term));
+    });
+}
+export function getCatalogGroups(catalog, filter = {}) {
+    const items = filterCatalog(catalog, filter);
+    return UTILITY_SCOPES.flatMap((scope) => {
+        const selected = items.filter((item) => item.scope === scope);
+        if (!selected.length)
+            return [];
+        const categories = new Map();
+        for (const item of selected) {
+            const members = categories.get(item.category) ?? [];
+            members.push(item);
+            categories.set(item.category, members);
+        }
+        return [
+            {
+                scope,
+                count: selected.length,
+                categories: [...categories]
+                    .sort(([a], [b]) => a.localeCompare(b))
+                    .map(([id, members]) => ({
+                    id,
+                    name: id.slice(scope.length + 1),
+                    items: members,
+                })),
+            },
+        ];
+    });
+}
+const summarySegments = new Intl.Segmenter("und", { granularity: "grapheme" });
+export function summarizeDescription(description, maxCharacters = 100) {
+    if (!Number.isSafeInteger(maxCharacters) || maxCharacters < 0) {
+        throw new RangeError("Summary length must be a non-negative safe integer.");
+    }
+    if (maxCharacters === 0)
+        return "";
+    const text = description.replace(/\s+/gu, " ").trim();
+    const characters = [];
+    for (const { segment } of summarySegments.segment(text)) {
+        if (characters.length === maxCharacters)
+            return characters.slice(0, -1).join("").trimEnd() + "…";
+        characters.push(segment);
+    }
+    return text;
+}

package/dist/lib/catalog-selection.js

@@ -0,0 +1,199 @@
+import { filterCatalog, getCatalogGroups, summarizeDescription } from "./catalog-query.js";
+import {} from "./catalog.js";
+import { describeInstallation } from "./installation-status.js";
+import { Picker } from "./picker.js";
+const scopeLabels = { core: "Core", lib: "라이브러리" };
+function includesQuery(value, query) {
+    const normalized = value.normalize("NFKC").toLowerCase();
+    return query
+        .normalize("NFKC")
+        .toLowerCase()
+        .trim()
+        .split(/\s+/u)
+        .every((term) => normalized.includes(term));
+}
+export class CatalogSelection {
+    catalog;
+    scopes;
+    categories;
+    names;
+    groups;
+    pageStates = new Map();
+    constructor(catalog, initial = {}) {
+        this.catalog = catalog;
+        this.groups = getCatalogGroups(catalog);
+        const items = (initial.names ?? []).map((name) => {
+            const item = catalog.items.find((candidate) => candidate.name === name);
+            if (!item)
+                throw new Error("Unknown item: " + name);
+            return item;
+        });
+        this.scopes = new Set(initial.scopes ?? items.map((item) => item.scope));
+        this.categories = new Set(initial.categories ?? items.map((item) => item.category));
+        this.names = new Set(items.map((item) => item.name));
+    }
+    snapshot() {
+        return {
+            scopes: this.groups.filter((group) => this.scopes.has(group.scope)).map((group) => group.scope),
+            categories: this.groups
+                .flatMap((group) => group.categories)
+                .filter((category) => this.categories.has(category.id))
+                .map((category) => category.id),
+            names: this.catalog.items.filter((item) => this.names.has(item.name)).map((item) => item.name),
+        };
+    }
+    selectedNames() {
+        return this.catalog.items
+            .filter((item) => this.scopes.has(item.scope) && this.categories.has(item.category) && this.names.has(item.name))
+            .map((item) => item.name);
+    }
+    pages() {
+        const groups = this.groups.filter((group) => this.scopes.has(group.scope));
+        return [
+            { kind: "scopes" },
+            ...groups.map((group) => ({ kind: "categories", scope: group.scope })),
+            ...groups.flatMap((group) => group.categories
+                .filter((category) => this.categories.has(category.id))
+                .map((category) => ({ kind: "items", scope: group.scope, category: category.id }))),
+        ];
+    }
+    values(page) {
+        return [...(page.kind === "scopes" ? this.scopes : page.kind === "categories" ? this.categories : this.names)];
+    }
+    update(page, values) {
+        if (page.kind === "scopes") {
+            this.scopes.clear();
+            for (const value of values)
+                this.scopes.add(value);
+        }
+        else {
+            const ids = page.kind === "categories"
+                ? (this.groups.find((group) => group.scope === page.scope)?.categories.map((category) => category.id) ?? [])
+                : filterCatalog(this.catalog, { categories: [page.category] }).map((item) => item.name);
+            const selected = page.kind === "categories" ? this.categories : this.names;
+            for (const id of ids)
+                selected.delete(id);
+            for (const value of values)
+                if (ids.includes(value))
+                    selected.add(value);
+        }
+    }
+    countWith(page, values) {
+        const copy = new CatalogSelection(this.catalog, this.snapshot());
+        copy.update(page, values);
+        return copy.selectedNames().length;
+    }
+}
+function itemDetails(item, installed) {
+    const included = item.modules.filter((module) => module.name !== item.name);
+    const peers = item.modules.flatMap((module) => module.requires
+        .filter((requirement) => requirement.kind === "peer" && !requirement.internal)
+        .map((requirement) => `${requirement.packageName}@${requirement.range}${requirement.optional ? " (선택 사항)" : ""}`));
+    return [
+        `${item.name}@${item.version}`,
+        item.description,
+        "",
+        "함께 생성: " + (included.map((module) => `${module.name}@${module.version}`).join(", ") || "없음"),
+        "실행 환경: " +
+            (item.runtime === "node"
+                ? "Node.js 필요"
+                : item.runtime === "dom"
+                    ? "DOM API와 DOM TypeScript 타입 필요"
+                    : "별도 제한 없음"),
+        "npm 의존성: " + (item.dependencies.join(", ") || "없음"),
+        "개발 의존성: " + (item.devDependencies?.join(", ") || "없음"),
+        "peer 호환 범위: " + ([...new Set(peers)].join(", ") || "없음"),
+        "",
+        ...(installed.length
+            ? installed.flatMap((entry) => [
+                describeInstallation(entry),
+                ...(entry.via !== item.name ? [entry.via + "의 의존 모듈로 설치"] : []),
+            ])
+            : ["이 프로젝트의 설치 기록 없음"]),
+        "",
+        "생성 파일:",
+        ...item.files,
+    ];
+}
+function choicesFor(selection, page, installed) {
+    if (page.kind === "scopes")
+        return selection.groups.map((group) => ({
+            id: group.scope,
+            label: scopeLabels[group.scope],
+            summary: `${group.categories.length}개 하위 분류 · ${group.count}개 유틸`,
+            details: () => group.categories.map((category) => `${category.name} · ${category.items.length}개 유틸`),
+            matches: (query) => includesQuery(scopeLabels[group.scope], query) ||
+                filterCatalog(selection.catalog, { scopes: [group.scope], query }).length > 0,
+        }));
+    if (page.kind === "categories")
+        return (selection.groups.find((group) => group.scope === page.scope)?.categories ?? []).map((category) => ({
+            id: category.id,
+            label: category.name,
+            summary: `${category.items.length}개 유틸`,
+            details: () => category.items.map((item) => `${item.name} — ${item.description}`),
+            matches: (query) => includesQuery(category.id, query) ||
+                filterCatalog(selection.catalog, { categories: [category.id], query }).length > 0,
+        }));
+    return filterCatalog(selection.catalog, { categories: [page.category] }).map((item) => {
+        const locations = installed.get(item.name) ?? [];
+        const present = locations.some((entry) => ["present", "modified", "unverified"].includes(entry.status));
+        return {
+            id: item.name,
+            label: item.name + (present ? " [설치됨]" : locations.length ? " [설치 기록 확인]" : ""),
+            summary: summarizeDescription(item.description),
+            details: () => itemDetails(item, locations),
+            matches: (query) => filterCatalog({ ...selection.catalog, items: [item] }, { query }).length > 0,
+        };
+    });
+}
+export async function selectCatalog(selection, terminal, installed = new Map()) {
+    const states = selection.pageStates;
+    let index = 0;
+    let notice = "";
+    while (true) {
+        const page = selection.pages()[index];
+        if (!page)
+            throw new Error("Invalid catalog selection page.");
+        const id = page.kind === "scopes" ? "scopes" : page.kind === "categories" ? page.scope : page.category;
+        const title = page.kind === "scopes"
+            ? "어떤 것들을 추가하시겠어요? · 대분류 선택"
+            : page.kind === "categories"
+                ? `${scopeLabels[page.scope]} · 하위 분류 선택`
+                : `${scopeLabels[page.scope]} / ${page.category.slice(page.scope.length + 1)} · 유틸 선택`;
+        const result = await terminal.pick(new Picker({
+            title,
+            stage: page.kind === "scopes" ? "scope" : page.kind === "categories" ? "category" : "utility",
+            breadcrumb: page.kind === "scopes"
+                ? ["카탈로그", "시작"]
+                : page.kind === "categories"
+                    ? ["카탈로그", scopeLabels[page.scope]]
+                    : ["카탈로그", scopeLabels[page.scope], page.category.slice(page.scope.length + 1)],
+            choices: choicesFor(selection, page, installed),
+            selected: selection.values(page),
+            summary: (values) => `총 선택 유틸 ${selection.countWith(page, values)}개 · 체크 ${values.length}개`,
+            ...(page.kind !== "items"
+                ? { validate: (values) => (values.length ? undefined : "분류를 하나 이상 선택해 주세요.") }
+                : {}),
+            state: states.get(id),
+            notice,
+        }));
+        if (result.status === "cancelled")
+            return { ...result, state: selection.snapshot() };
+        states.set(id, result.state);
+        selection.update(page, result.selected);
+        notice = "";
+        if (result.status === "back") {
+            if (!index)
+                return { status: "cancelled", reason: "cancel", state: selection.snapshot() };
+            index--;
+        }
+        else if (index + 1 < selection.pages().length)
+            index++;
+        else {
+            const [first, ...rest] = selection.selectedNames();
+            if (first)
+                return { status: "selected", names: [first, ...rest], state: selection.snapshot() };
+            notice = "유틸을 하나 이상 선택해 주세요.";
+        }
+    }
+}

package/dist/lib/catalog.js

@@ -0,0 +1,144 @@
+import { satisfies, valid, validRange } from "semver";
+import { isRecord } from "./json.js";
+export const UTILITY_SCOPES = Object.freeze(["core", "lib"]);
+export const CATALOG_SCHEMA_VERSION = 3;
+const itemNamePattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export function isItemName(value) {
+    return typeof value === "string" && itemNamePattern.test(value);
+}
+export function isUtilityScope(value) {
+    return value === "core" || value === "lib";
+}
+export function isCatalogCategoryId(value, scope) {
+    if (typeof value !== "string")
+        return false;
+    const [owner, category, ...rest] = value.split("/");
+    return owner === scope && isItemName(category) && rest.length === 0;
+}
+export function isSourcePath(value) {
+    return (typeof value === "string" &&
+        value.endsWith(".ts") &&
+        !value.includes("\\") &&
+        !value.includes("\0") &&
+        !value.includes(":") &&
+        value.split("/").every((part) => part && part !== "." && part !== "..") &&
+        !/\.(test|spec|stories|config|d)\.ts$/.test(value));
+}
+function isDependencyList(value) {
+    return (Array.isArray(value) &&
+        value.every((dependency) => {
+            if (typeof dependency !== "string")
+                return false;
+            const separator = dependency.lastIndexOf("@");
+            return (separator > 0 && isPackageName(dependency.slice(0, separator)) && !!validRange(dependency.slice(separator + 1)));
+        }));
+}
+export function isPackageName(value) {
+    return typeof value === "string" && /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(value);
+}
+export function isModuleSnapshot(value) {
+    return (isRecord(value) &&
+        isItemName(value.name) &&
+        isPackageName(value.packageName) &&
+        typeof value.version === "string" &&
+        valid(value.version) === value.version &&
+        isUtilityScope(value.scope) &&
+        isRecord(value.files) &&
+        Object.keys(value.files).length > 0 &&
+        Object.entries(value.files).every(([file, hash]) => isSourcePath(file) && typeof hash === "string" && /^[a-f0-9]{64}$/.test(hash)) &&
+        Array.isArray(value.requires) &&
+        value.requires.every((requirement) => isRecord(requirement) &&
+            isPackageName(requirement.packageName) &&
+            typeof requirement.range === "string" &&
+            !!validRange(requirement.range) &&
+            (requirement.kind === "dependency" || requirement.kind === "peer") &&
+            typeof requirement.internal === "boolean" &&
+            typeof requirement.optional === "boolean" &&
+            (!requirement.optional || requirement.kind === "peer")));
+}
+export function validateModuleGraph(modules) {
+    const providers = new Map(modules.map((module) => [module.packageName, module]));
+    if (providers.size !== modules.length)
+        throw new Error("Duplicate utility package in module graph.");
+    for (const module of modules) {
+        for (const requirement of module.requires.filter((entry) => entry.internal)) {
+            const provider = providers.get(requirement.packageName);
+            if ((!requirement.optional || provider) && (!provider || !satisfies(provider.version, requirement.range))) {
+                throw new Error("Incompatible utility dependency: " +
+                    module.packageName +
+                    "@" +
+                    module.version +
+                    " requires " +
+                    requirement.packageName +
+                    "@" +
+                    requirement.range +
+                    "; available: " +
+                    (provider?.version ?? "missing") +
+                    ".");
+            }
+        }
+    }
+}
+function assertCatalog(catalog) {
+    if (!isRecord(catalog) ||
+        catalog.schemaVersion !== CATALOG_SCHEMA_VERSION ||
+        typeof catalog.version !== "string" ||
+        !Array.isArray(catalog.items) ||
+        catalog.items.length === 0) {
+        throw new Error("Invalid Hermes catalog. Rebuild the CLI with catalog schema " + CATALOG_SCHEMA_VERSION + ".");
+    }
+    const names = new Set();
+    const items = catalog.items;
+    for (const item of items) {
+        if (!isRecord(item) ||
+            !isItemName(item.name) ||
+            !isPackageName(item.packageName) ||
+            typeof item.version !== "string" ||
+            valid(item.version) !== item.version ||
+            !Array.isArray(item.modules) ||
+            !item.modules.every(isModuleSnapshot) ||
+            names.has(item.name) ||
+            !isUtilityScope(item.scope) ||
+            !isCatalogCategoryId(item.category, item.scope) ||
+            typeof item.description !== "string" ||
+            !Array.isArray(item.files) ||
+            item.files.length === 0 ||
+            !item.files.every(isSourcePath) ||
+            new Set(item.files).size !== item.files.length ||
+            (item.runtime !== undefined && item.runtime !== "node" && item.runtime !== "dom")) {
+            throw new Error("Invalid or duplicate Hermes item: " + (isRecord(item) ? item.name : undefined));
+        }
+        const modules = item.modules;
+        const own = modules.find((module) => module.name === item.name);
+        if (!own ||
+            own.packageName !== item.packageName ||
+            own.version !== item.version ||
+            own.scope !== item.scope ||
+            new Set(modules.map((module) => module.name)).size !== modules.length ||
+            JSON.stringify([...new Set(modules.flatMap((module) => Object.keys(module.files)))].sort()) !==
+                JSON.stringify([...item.files].sort())) {
+            throw new Error("Invalid module provenance for " + item.name);
+        }
+        validateModuleGraph(modules);
+        if (!isDependencyList(item.dependencies) ||
+            (item.devDependencies !== undefined && !isDependencyList(item.devDependencies))) {
+            throw new Error("Invalid dependencies for " + item.name);
+        }
+        names.add(item.name);
+    }
+    const roots = items.map((item) => item.modules.find((module) => module.name === item.name));
+    const byPackage = new Map(roots.map((module) => [module?.packageName, module]));
+    if (byPackage.size !== roots.length)
+        throw new Error("Duplicate utility package in catalog.");
+    for (const item of items) {
+        for (const module of item.modules) {
+            if (JSON.stringify(module) !== JSON.stringify(byPackage.get(module.packageName))) {
+                throw new Error("Inconsistent module snapshot: " + module.packageName);
+            }
+        }
+    }
+}
+export function validateCatalog(catalog) {
+    assertCatalog(catalog);
+    return catalog;
+}

package/dist/lib/command.js

@@ -0,0 +1,50 @@
+import { parseArgs } from "node:util";
+export function parseCliArguments(args) {
+    return parseArgs({
+        args: [...args],
+        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,
+    });
+}
+// 실행 의도만 결정한다. 화면 연결과 설치 실행은 별도 단계에서 수행한다.
+export function resolveCommand({ values, positionals }, terminal) {
+    if (values.help)
+        return { kind: "help" };
+    if (values.version)
+        return { kind: "version" };
+    const [command, ...requestedNames] = positionals;
+    const interactive = terminal.stdinIsTTY === true && terminal.stdoutIsTTY === true;
+    if (command === undefined && !interactive)
+        return { kind: "help" };
+    if (command !== undefined && command !== "list" && command !== "add") {
+        throw new Error("Unknown command: " + command + ". Use --help.");
+    }
+    if (command === "list") {
+        if (requestedNames.length || values.dir !== undefined || values.overwrite || values["dry-run"]) {
+            throw new Error("Usage: hermes list");
+        }
+        return { kind: "list" };
+    }
+    if (!interactive) {
+        throw new Error("Interactive installation requires a terminal for selection and confirmation. Use 'hermes list' to browse available items.");
+    }
+    const directory = values.dir;
+    if (directory !== undefined && !directory.trim()) {
+        throw new Error("Specify a destination with --dir <directory>.");
+    }
+    return {
+        kind: "install-wizard",
+        request: {
+            initialNames: [...new Set(requestedNames)],
+            ...(directory === undefined ? {} : { directory }),
+            dryRun: values["dry-run"] ?? false,
+            overwrite: values.overwrite ?? false,
+        },
+    };
+}