261117_01_ENH: 생성 의존성 실제 버전으로 기록, cn을 @kri/common과 동기화하고 clsx·tailwind-merge 제거

This commit is contained in:
2026-11-17 09:19:15 +09:00
parent 263a32b99f
commit a90f9c8cd9
3 changed files with 132 additions and 34 deletions

View File

@@ -230,6 +230,7 @@ When implementation is complete, report in Korean:
- Treat the current React version, component style, state management, routing, styling, and test approach as authoritative. - Treat the current React version, component style, state management, routing, styling, and test approach as authoritative.
- Do not perform unrelated class-to-hook, JavaScript-to-TypeScript, state-library, styling-system, or React-to-Next.js migrations. - Do not perform unrelated class-to-hook, JavaScript-to-TypeScript, state-library, styling-system, or React-to-Next.js migrations.
- Keep components focused and follow the repository's established split between presentation, state, data access, and side effects. - Keep components focused and follow the repository's established split between presentation, state, data access, and side effects.
- Do not use nested ternary expressions. Use clear `if`/`else` branches, early returns, or well-named intermediate variables instead; a single, non-nested ternary is acceptable only when it remains immediately readable.
- Keep effects dependency-correct and clean up subscriptions, timers, listeners, and in-flight work where applicable. - Keep effects dependency-correct and clean up subscriptions, timers, listeners, and in-flight work where applicable.
- Use stable semantic keys and preserve accessibility, loading, empty, error, disabled, and success states. - Use stable semantic keys and preserve accessibility, loading, empty, error, disabled, and success states.
- Preserve public component props and shared UI contracts unless a coordinated breaking change is explicitly approved. - Preserve public component props and shared UI contracts unless a coordinated breaking change is explicitly approved.
@@ -266,6 +267,35 @@ Before each related task, read the current contents of every matching reference,
If a task spans multiple scopes, read every matching reference. Generated files under `.agent-harness/references/` are read-only copies; edit KriFrontCommon's `.agent/consumer.md` or `.agent/consumer-references/` and recompose instead. If a task spans multiple scopes, read every matching reference. Generated files under `.agent-harness/references/` are read-only copies; edit KriFrontCommon's `.agent/consumer.md` or `.agent/consumer-references/` and recompose instead.
## Noti-hub SMS Types
- `MessageType.SMS = 21`, `LMS = 22`, `MMS = 23`; `ChannelType.SMS = 2` is unchanged. `SMS_TYPE_ARRAY` and `SmsType` include all three.
- `LMS_MMS = 22` remains a deprecated source-compatibility alias for LMS only. It does not represent MMS. Enum reverse lookup for 22 returns LMS. Use numeric bulk-list paths; the server no longer accepts LMS_MMS in paths. Numeric 21/22/23 bulk-list requests all return the entire SMS channel, not type-filtered lists.
- Requests retain their existing URLs/body shapes. The server chooses the actual type per recipient after substitution: attachment -> MMS; otherwise title or UTF-8 body >= 90 bytes -> LMS; otherwise SMS.
- Refresh templates from the save response (`tmplatTy`); display actual delivery types from `sendTy`, not the template or result code. A bulk can contain multiple SMS types. LMS/MMS share result codes; use existing server result labels.
- SMS, LMS, MMS and KKO use cancellation code 9998. Verify with `npm run typecheck`, `npm run build`, and `node --test tests/noti-hub-sms.test.mjs`.
## Noti-hub Reservation Cancellation
- Import cancellation types, constants, and helpers from `@kri/common/noti-hub` only. They are runtime-neutral and require no optional peers.
- Individual current cancellation state is determined by resultCode via isReserveCanceledResult; bulk current state is cancellationStatus (NONE/PARTIAL/ALL). These describe current cancellation state, not cancellation eligibility. cancelDt and cancelUser are request history, not current state.
- SendResultInfo, SendInfo, and BulkSendInfo expose optional cancelable. Use isSendCancelable(item), which returns true only for cancelable === true, for cancellation eligibility; missing values from older responses are treated as false. Never infer eligibility from cancelDt, result labels, or result codes.
- cancelable reflects query-time state and may change before cancellation. Determine the final outcome from SendCancelResponse counts.
- sendIdx is the single-cancel identifier, not cmid. It is absent from the latest abbreviated report (/api/v1/report/last/send/...). Request sendIdx must be a positive integer; bulkSendKey is required and at most 32 characters.
- EMAIL_RESERVE_CANCELED_RESULT_CODE is 108 for EMAIL. SMS_KKO_RESERVE_CANCELED_RESULT_CODE is 9998 for SMS, LMS, MMS, and KKO. Unknown message types are not recognized as canceled.
- Display the server's resultViewLabel/resultLabel ("예약 취소"). There is no separate result-code list API.
- HTTP 200 can contain notCancelableCount. parseSendCancelResponse validates nonnegative integer counts and targetCount = canceledCount + alreadyCanceledCount + notCancelableCount, throwing TypeError on invalid data. Bulk targetCount counts currently registered detail rows; response canceledCount counts only cancellations made by that request.
- Existing response fields are unchanged; all added fields on existing types are optional. Verify with npm run typecheck and npm run build.
## HTTP Streaming
- `@kri/common/http` HTTP clients expose streamGet/streamPost/streamPut/streamPatch/streamDel, returning HttpStreamResponse (status, statusText, headers, url, nullable body).
- Streaming shares ordinary authentication, URL, body and HTTP-error policy. Read body incrementally; no automatic JSON/NDJSON/SSE parsing or reconnect is performed.
- Streaming options accept an external AbortSignal. Caller cancellation raises AbortError without an HTTP error notification. Cancel the body when it will not be consumed.
- timeoutMs covers connection/headers (and an HTTP error body); idleTimeoutMs covers inactivity after successful headers and resets on consumed chunks. Both default to the client's defaultTimeoutMs (60 seconds by default), and 0 disables that timer for streaming only.
- Mid-stream transport/time-out errors reach the body reader. HTTP error statuses use existing HttpError handlers before a stream is returned. A 204 response has body=null.
- See HTTP_STREAMING.md for examples and node --test tests/http-stream.test.mjs for focused validation after npm run build.
## KriUiRegistry Consumer Contract ## KriUiRegistry Consumer Contract
When implementing or changing frontend UI, use this order: When implementing or changing frontend UI, use this order:
@@ -275,6 +305,28 @@ When implementing or changing frontend UI, use this order:
3. Otherwise, prefer a suitable shadcn/ui component. 3. Otherwise, prefer a suitable shadcn/ui component.
4. Create a custom component only when the preceding options cannot meet the requirement safely. 4. Create a custom component only when the preceding options cannot meet the requirement safely.
### KriAutoComplete Search Scroll
- `kri-auto-complete` exposes `resetScrollOnSearch?: boolean` on `KriSingleSelect`, `KriMultiSelect`, and `MultiSelect`. It defaults to `false`, preserving existing behavior.
- When enabled, a search value change (including clearing it) resets the option list scroll to the top on the next animation frame in both `filter` and `inputOnly` modes. Async result updates alone do not trigger another reset.
### KriAutoComplete Option Tooltip
- `kri-auto-complete` exposes `optionTooltip?: 'singleLine' | 'wrap'` and `optionTooltipClassName?: string` on `KriSingleSelect`, `KriMultiSelect`, and `MultiSelect`. It is off by default, preserving existing behavior.
- When enabled, hovering an option shows its full `label` in a right-side tooltip. `singleLine` stays on one line until the available viewport width; `wrap` wraps at 28rem. The item depends on the shadcn `tooltip` component and provides its own `TooltipProvider`.
### KriAutoComplete Search Match
- `kri-auto-complete` exposes `searchMatch?: 'fuzzy' | 'contains'` on `KriSingleSelect`, `KriMultiSelect`, and `MultiSelect`. It defaults to `fuzzy` (cmdk's default subsequence scoring), preserving existing behavior.
- `contains` keeps only options whose label or value contains the search text as a case-insensitive substring, in the original option order. It applies only when `searchMode` is `filter`.
### KriEditor SMS Preview
- `changeSmsType` reports `SMS | LMS | MMS`. Update consumer callbacks to handle `MMS`; this widens the previous callback contract.
- Attachment presence (`smsHasAttachment`) takes priority and reports MMS. Otherwise a title or UTF-8 preview size >= `smsMaxBytes` (default 90) reports LMS; the remainder reports SMS. LMS/MMS share `lmsMaxBytes` (default 2000).
- UTF-8 byte counting includes `smsPreviewSuffix` and its separating newline, without storing the suffix in the body.
- This is a preview. Use the template-save response for saved `tmplatTy` and delivery-result `sendTy` for actual per-recipient type after server substitution. Registry updates require updating installed consumer copies.
### Required Shared References ### Required Shared References
Before each related task, read the current contents of every matching reference, even if it was read earlier in the session. Before each related task, read the current contents of every matching reference, even if it was read earlier in the session.

View File

@@ -50,12 +50,13 @@ Agent Harness 관련 기본값과 옵션:
## 생성 과정 ## 생성 과정
1. 표준 템플릿 복사 1. 표준 템플릿 복사
2. Next.js 및 shadcn 호환 npm 의존성 설치 2. Next.js 및 shadcn 호환 npm 의존성 설치(설치 시점의 실제 버전 범위로 기록)
3. `@kri/common@latest` 설치 후 exact 버전 기록 3. `@kri/common@latest` 설치 후 exact 버전 기록
4. KRI UI Registry 9개 항목 설치 4. KRI UI Registry 9개 항목 설치
5. TypeScript 검사 5. `cn` 버전을 설치된 `@kri/common`의 `cn` 의존성과 같은 exact 버전으로 동기화
6. Next.js production build 6. TypeScript 검사
7. Agent Harness 공유 등록, `AGENTS.md`/`CLAUDE.md` 합성 및 검증 7. Next.js production build
8. Agent Harness 공유 등록, `AGENTS.md`/`CLAUDE.md` 합성 및 검증
UI Registry: `https://ui-registry.kric.com/r` UI Registry: `https://ui-registry.kric.com/r`
@@ -78,6 +79,9 @@ UI Registry: `https://ui-registry.kric.com/r`
## 호환성 정책 ## 호환성 정책
- 생성 프로젝트는 Node.js 22 이상이 필요합니다(`@kri/common`의 `cn` 의존성 요구 사항).
- 의존성은 `latest`를 그대로 기록하지 않고, 설치 시점에 해석된 실제 버전 범위(예: `^19.2.1`)로 기록합니다. `--skip-install`로 생성하면 설치 전이므로 spec(`latest` 등)이 그대로 남습니다.
- `@kri/common`은 프로젝트 생성 시점의 최신 버전을 설치하고 exact 버전으로 기록합니다. - `@kri/common`은 프로젝트 생성 시점의 최신 버전을 설치하고 exact 버전으로 기록합니다.
- `cn`은 `@kri/common`이 의존하는 버전을 읽어 같은 exact 버전으로 설치합니다. shadcn 기본 컴포넌트와 `@kri/common/ui`가 같은 `cn`을 사용해 중복 설치되지 않습니다.
- Next.js 생태계 호환성을 위해 생성 프로젝트의 TypeScript는 최신 5.x, ESLint는 최신 9.x를 사용합니다. - Next.js 생태계 호환성을 위해 생성 프로젝트의 TypeScript는 최신 5.x, ESLint는 최신 9.x를 사용합니다.
- shadcn 기본 컴포넌트가 사용하는 `class-variance-authority`, `clsx`, `tailwind-merge`, `lucide-react`를 기본 의존성에 포함합니다. - shadcn 기본 컴포넌트가 사용하는 `class-variance-authority`, `lucide-react`를 기본 의존성에 포함합니다. 클래스 병합은 `clsx`·`tailwind-merge` 대신 `cn`을 사용합니다.

View File

@@ -1,6 +1,6 @@
import { fileURLToPath } from "node:url"; import { fileURLToPath } from "node:url";
import path from "node:path"; import path from "node:path";
import { writeFile } from "node:fs/promises"; import { readFile, writeFile } from "node:fs/promises";
import { KRI_REGISTRY_ITEMS, REGISTRY_BASE_URL } from "./constants.js"; import { KRI_REGISTRY_ITEMS, REGISTRY_BASE_URL } from "./constants.js";
import { copyTemplate, ensureTargetDirectory, removeJenkinsfile, replacePlaceholders } from "./files.js"; import { copyTemplate, ensureTargetDirectory, removeJenkinsfile, replacePlaceholders } from "./files.js";
import { composeAgentHarness } from "./harness.js"; import { composeAgentHarness } from "./harness.js";
@@ -10,8 +10,39 @@ import type { CliOptions } from "./types.js";
const currentDir = path.dirname(fileURLToPath(import.meta.url)); const currentDir = path.dirname(fileURLToPath(import.meta.url));
const templateDir = path.resolve(currentDir, "../templates/base"); const templateDir = path.resolve(currentDir, "../templates/base");
// 설치 시점에 각 spec을 해석해 npm이 실제 버전 범위(예: ^19.2.1)로 package.json에 기록한다.
// `@kri/common`은 별도 단계에서 exact 버전으로, `cn`은 `@kri/common`과 같은 exact 버전으로 설치한다.
const DEPENDENCY_SPECS: Record<string, string> = {
"@tanstack/react-query": "latest",
"class-variance-authority": "latest",
jotai: "latest",
"lucide-react": "latest",
next: "latest",
react: "latest",
"react-dom": "latest",
"server-only": "latest",
sonner: "latest",
};
const DEV_DEPENDENCY_SPECS: Record<string, string> = {
"@tailwindcss/postcss": "latest",
"@types/node": "latest",
"@types/react": "latest",
"@types/react-dom": "latest",
"babel-plugin-react-compiler": "latest",
// `^`는 Windows cmd.exe 이스케이프 문자라 메이저 버전만 지정한다(9 = 최신 9.x).
eslint: "9",
"eslint-config-next": "latest",
tailwindcss: "latest",
"tw-animate-css": "latest",
typescript: "5",
};
const toInstallArgs = (specs: Record<string, string>): string[] =>
Object.entries(specs).map(([name, spec]) => `${name}@${spec}`);
function packageJson(options: CliOptions) { function packageJson(options: CliOptions) {
return { const base = {
name: options.projectName, name: options.projectName,
version: "0.1.0", version: "0.1.0",
private: true, private: true,
@@ -22,33 +53,39 @@ function packageJson(options: CliOptions) {
lint: "eslint", lint: "eslint",
typecheck: "tsc --noEmit", typecheck: "tsc --noEmit",
}, },
dependencies: {
"@kri/common": "latest",
"@tanstack/react-query": "latest",
"class-variance-authority": "latest",
clsx: "latest",
jotai: "latest",
"lucide-react": "latest",
next: "latest",
react: "latest",
"react-dom": "latest",
"server-only": "latest",
sonner: "latest",
"tailwind-merge": "latest",
},
devDependencies: {
"@tailwindcss/postcss": "latest",
"@types/node": "latest",
"@types/react": "latest",
"@types/react-dom": "latest",
"babel-plugin-react-compiler": "latest",
eslint: "^9",
"eslint-config-next": "latest",
tailwindcss: "latest",
"tw-animate-css": "latest",
typescript: "^5",
},
}; };
if (options.install) return base;
// --skip-install: 설치하지 않으므로 나중에 `npm install`할 수 있도록 spec을 그대로 기록한다.
return {
...base,
dependencies: { "@kri/common": "latest", ...DEPENDENCY_SPECS },
devDependencies: { ...DEV_DEPENDENCY_SPECS },
};
}
async function readKriCommonCnVersion(targetDir: string): Promise<string | null> {
const manifestPath = path.join(targetDir, "node_modules", "@kri", "common", "package.json");
const manifest: unknown = JSON.parse(await readFile(manifestPath, "utf8"));
if (typeof manifest !== "object" || manifest === null) return null;
const dependencies = (manifest as { dependencies?: unknown }).dependencies;
if (typeof dependencies !== "object" || dependencies === null) return null;
const cnVersion = (dependencies as Record<string, unknown>).cn;
return typeof cnVersion === "string" && cnVersion.trim() !== "" ? cnVersion.trim() : null;
}
// shadcn 기본 컴포넌트는 `cn` 패키지를 직접 import한다. `@kri/common`과 같은 버전으로 맞춰 중복 설치를 막는다.
async function syncCnWithKriCommon(targetDir: string): Promise<void> {
const cnVersion = await readKriCommonCnVersion(targetDir);
if (!cnVersion) {
console.warn("[WARN] @kri/common이 cn에 의존하지 않아 cn 버전 동기화를 생략합니다.");
return;
}
await run("npm", ["install", "--save-exact", `cn@${cnVersion}`], targetDir);
} }
export async function createProject(options: CliOptions): Promise<void> { export async function createProject(options: CliOptions): Promise<void> {
@@ -86,7 +123,8 @@ export async function createProject(options: CliOptions): Promise<void> {
} }
console.log("\n[1/4] npm 의존성 설치"); console.log("\n[1/4] npm 의존성 설치");
await run("npm", ["install"], options.targetDir); await run("npm", ["install", ...toInstallArgs(DEPENDENCY_SPECS)], options.targetDir);
await run("npm", ["install", "--save-dev", ...toInstallArgs(DEV_DEPENDENCY_SPECS)], options.targetDir);
console.log("\n[2/4] 최신 @kri/common 설치"); console.log("\n[2/4] 최신 @kri/common 설치");
await run("npm", ["install", "--save-exact", "@kri/common@latest"], options.targetDir); await run("npm", ["install", "--save-exact", "@kri/common@latest"], options.targetDir);
@@ -105,6 +143,10 @@ export async function createProject(options: CliOptions): Promise<void> {
console.log("[SKIP] UI Registry 설치"); console.log("[SKIP] UI Registry 설치");
} }
// shadcn 설치가 cn 의존성을 추가·변경할 수 있으므로 UI 설치 뒤에 맞춘다.
console.log("\ncn 버전을 @kri/common과 동기화");
await syncCnWithKriCommon(options.targetDir);
if (options.build) { if (options.build) {
if (!options.installUi) { if (!options.installUi) {
console.warn("[WARN] --skip-ui 때문에 typecheck/build를 생략합니다."); console.warn("[WARN] --skip-ui 때문에 typecheck/build를 생략합니다.");