Compare commits

..

9 Commits

27 changed files with 654 additions and 150 deletions

View File

@@ -0,0 +1,13 @@
<!--
GENERATED BY KRI AGENT HARNESS. DO NOT EDIT DIRECTLY.
Contract: kri-front-common
Source: .agent/consumer-references/change-and-verification.md
-->
# KriFrontCommon Change and Verification
- Pin or constrain the package version according to the consumer repository's dependency policy and commit its lockfile changes.
- Review release notes and the actual affected API before upgrading.
- Run the consumer's focused type-check, test, and build commands after an upgrade.
- Keep `.agent/project.md` near 2-3 KiB as a routing document. Move conditional schemas, endpoint inventories, examples, and issue history to routed `.agent/references/` documents instead of deleting them.
- Do not modify KriFrontCommon or another consumer repository unless it is explicitly included in the approved task scope.

View File

@@ -0,0 +1,15 @@
<!--
GENERATED BY KRI AGENT HARNESS. DO NOT EDIT DIRECTLY.
Contract: kri-front-common
Source: .agent/consumer-references/package-and-runtime.md
-->
# KriFrontCommon Package and Runtime Contract
- Use the package root for runtime-neutral object, URL, date, string, and shared type utilities.
- Use a focused subpath such as `@kri/common/http`, `@kri/common/browser`, `@kri/common/server`, `@kri/common/security`, `@kri/common/hooks`, `@kri/common/query`, `@kri/common/config`, `@kri/common/jotai`, or `@kri/common/noti-hub` for the corresponding capability.
- Keep browser, server, and runtime-neutral imports on their intended side of the application boundary.
- A consumer that uses React hooks, TanStack Query, or Jotai integrations must provide the compatible optional peer dependency required by its selected entry point.
- Preserve the project's established HTTP client, authentication, error-policy, query-client, storage, and environment conventions when adopting a shared helper.
- Validate external data at runtime; a shared TypeScript type alone does not validate an API response or persisted value.
- Prefer named public exports and retain the consumer project's current module system and bundler conventions.

View File

@@ -0,0 +1,13 @@
<!--
GENERATED BY KRI AGENT HARNESS. DO NOT EDIT DIRECTLY.
Contract: kri-front-common
Source: .agent/consumer-references/react-compiler.md
-->
# React Compiler and Manual Memoization
- `createKriNextConfig` enables `reactCompiler: true` unless the project overrides it; confirm the effective configuration.
- When enabled, rely on React Compiler instead of adding `useMemo`, `useCallback`, or `React.memo` as a routine performance precaution.
- Use manual memoization only for required reference stability, an Effect or third-party contract, compiler-incompatible code, or a measured performance problem.
- Preserve existing memoization unless approved and verified for removal.
- Use `"use memo"` or `"use no memo"` only for a documented compiler boundary.

View File

@@ -0,0 +1,11 @@
<!--
GENERATED BY KRI AGENT HARNESS. DO NOT EDIT DIRECTLY.
Contract: kri-ui-registry
Source: .agent/consumer-references/editor-html-compatibility.md
-->
# KriEditor HTML Compatibility
- `enableImageMap` opt-in preserves `map`, nested `area`, and `img.usemap` HTML in WYSIWYG mode; consumers remain responsible for sanitizing URLs and attributes according to their server policy.
- Use `htmlSanitizer` when a consumer must apply a stricter HTML policy than the editor's default DOMPurify profile.
- Use `getWysiwygCompatibility` to keep lossy HTML in HTML mode. The callback must return `compatible: false` when WYSIWYG parsing would remove or materially rewrite content.

View File

@@ -0,0 +1,23 @@
<!--
GENERATED BY KRI AGENT HARNESS. DO NOT EDIT DIRECTLY.
Contract: kri-ui-registry
Source: .agent/consumer-references/installation-and-adaptation.md
-->
# KriUiRegistry Installation and Adaptation
## Installation and Ownership
- Inspect the registry item and its dependencies before installation. Use the shadcn CLI with the approved registry endpoint under `https://ui-registry.kric.com/r/` instead of copying files from `dist/r` manually.
- `kri-data-table` uses the TanStack Table v8 API. Keep `@tanstack/react-table` within the supported `^8.21.3` range and do not upgrade it to v9 until KriUiRegistry provides an explicitly migrated component contract.
- Respect the consumer project's component aliases, target paths, package manager, styling system, React version, and existing design tokens.
- The shadcn workflow copies component source into the consumer repository. After installation, treat that copy as project-owned code; do not assume registry updates propagate automatically.
- Do not overwrite an existing project component without reviewing the diff and confirming that local behavior and accessibility are preserved.
- Keep package and lockfile changes produced by an installation within the approved scope.
## Adaptation and Verification
- Adapt business data and application behavior outside the shared component when possible. Avoid embedding project-specific API, route, authentication, or environment logic into a reusable component.
- Preserve the installed component's public props, accessibility, keyboard behavior, responsive layout, and loading, empty, error, and disabled states unless the task explicitly changes them.
- If the registry lacks a generally reusable capability, propose it in KriUiRegistry; do not modify that repository unless it is explicitly in scope.
- Run the consumer repository's focused type-check, lint, tests, and build after installation or upgrade.

View File

@@ -1,29 +1,18 @@
## KriCreateNextApp Repository Rules # KriCreateNextApp Project Instruction Router
### Repository Role and Contracts ## Required Project References
- This repository provides the Node.js 20 TypeScript CLI `@kri/create-next-app` and the template used to create KRI Next.js frontend applications. Before each related task, read the current contents of every matching reference below, even if it was read earlier in the session.
- Treat command names, flags, prompts, defaults, generated paths, dependency policy, template structure, and validation order as public contracts.
- `src` is authoritative. `dist` is ignored build output and must not be edited or committed directly.
- Keep the CLI implementation, help text, README, and templates synchronized whenever generated behavior changes.
### Generated Frontend Invariants | Task scope | Required reference |
|---|---|
| Any substantive analysis, planning, implementation, debugging, review, or documentation work in this repository | `.agent/references/repository-rules.md` |
- Generated applications use TypeScript, React, Next.js, `@kri/common`, shadcn, and the KRI UI Registry contract declared by this repository profile. If a task spans multiple scopes, read every matching reference. Do not assume remembered content is current.
- Install `@kri/common@latest` and record the resolved dependency as an exact version using the existing npm workflow.
- Prefer shadcn and approved KRI UI Registry components over new local primitives when a suitable component exists.
- Do not introduce new frontend type or interface names ending in `Dto` or `DTO`.
- Generate `.agent/profile.yml`, `.agent/project.md`, and harness line-ending policy for every project. Never copy a stale precomposed `AGENTS.md` into the template.
### Harness Integration ## Harness Workflow
- Generated projects default to `requested-project`; allow the supported explicit project-type override without changing the fixed `frontend` layer. - `AGENTS.md` and `CLAUDE.md` are generated outputs. Never edit them directly.
- When the central harness is available, register the project in shared `workspace.yml` by default and run compose followed by verify. Allow an explicit local-registration override, and do not perform Git commits. Central-harness absence must not prevent project creation. - Edit `.agent/project.md` only when routing changes. Store durable project detail in `.agent/references/`.
- `AGENTS.md` and `CLAUDE.md` in this repository are harness-generated outputs. Never edit either file directly; edit `.agent` sources and recompose. - A reference-only content change does not require recomposition when its route is unchanged. Run harness verification to validate routing and UTF-8.
- Do not commit user-specific absolute harness paths or credentials. Explicit paths are runtime inputs only. - Recompose and verify after changing `.agent/project.md`, `.agent/profile.yml`, or another composed instruction source.
### Verification and Publication
- Run `npm.cmd run typecheck` and `npm.cmd run build` on Windows for CLI changes.
- Validate template changes by generating into a disposable directory without network installation first, then inspect unresolved placeholders, encoding, and harness composition.
- Package publication, registry access, and network installation require separate explicit approval.

View File

@@ -0,0 +1,29 @@
## KriCreateNextApp Repository Rules
### Repository Role and Contracts
- This repository provides the Node.js 20 TypeScript CLI `@kri/create-next-app` and the template used to create KRI Next.js frontend applications.
- Treat command names, flags, prompts, defaults, generated paths, dependency policy, template structure, and validation order as public contracts.
- `src` is authoritative. `dist` is ignored build output and must not be edited or committed directly.
- Keep the CLI implementation, help text, README, and templates synchronized whenever generated behavior changes.
### Generated Frontend Invariants
- Generated applications use TypeScript, React, Next.js, `@kri/common`, shadcn, and the KRI UI Registry contract declared by this repository profile.
- Install `@kri/common@latest` and record the resolved dependency as an exact version using the existing npm workflow.
- Prefer shadcn and approved KRI UI Registry components over new local primitives when a suitable component exists.
- Do not introduce new frontend type or interface names ending in `Dto` or `DTO`.
- Generate `.agent/profile.yml`, `.agent/project.md`, and harness line-ending policy for every project. Never copy a stale precomposed `AGENTS.md` into the template.
### Harness Integration
- Generated projects default to `requested-project`; allow the supported explicit project-type override without changing the fixed `frontend` layer.
- When the central harness is available, register the project in shared `workspace.yml` by default and run compose followed by verify. Allow an explicit local-registration override, and do not perform Git commits. Central-harness absence must not prevent project creation.
- `AGENTS.md` and `CLAUDE.md` in this repository are harness-generated outputs. Never edit either file directly; edit `.agent` sources and recompose.
- Do not commit user-specific absolute harness paths or credentials. Explicit paths are runtime inputs only.
### Verification and Publication
- Run `npm.cmd run typecheck` and `npm.cmd run build` on Windows for CLI changes.
- Validate template changes by generating into a disposable directory without network installation first, then inspect unresolved placeholders, encoding, and harness composition.
- Package publication, registry access, and network installation require separate explicit approval.

View File

@@ -0,0 +1,41 @@
---
name: attention-aware-communication
description: Shape substantive answers, progress updates, and completion reports for fast, accurate reading without reducing the underlying work.
---
<!--
GENERATED BY KRI AGENT HARNESS. DO NOT EDIT DIRECTLY.
Source: skills/attention-aware-communication/SKILL.md
-->
# Attention-Aware Communication
This skill changes presentation only. Investigate, implement, and verify as deeply as the task requires.
## Default: Attention-kind
- Put the bottom line in the first sentence and use plain Korean.
- Say the least that fully answers, then stop. Remove preambles, padding, repetition, and closing restatements.
- Never omit a number, scope condition, risk, prerequisite, uncertainty, or other fact that could cause the user to act incorrectly.
- For genuine breadth, explain the one or two most important points first, name the remaining areas, and let the user choose whether to expand them. Do not use this to defer required caveats or a complete focused answer.
- When the user asks for a detailed explanation, walkthrough, rationale, or full picture, suspend brevity and provide the necessary detail in scannable sections.
- When asked for a deliverable such as a command, message, snippet, or commit text, return the deliverable without unnecessary framing unless safety or correctness requires context.
- Ask one blocking question at a time and put it last. Keep working when a non-blocking assumption is safe.
## Progress and Completion: Rundown
Use Rundown formatting when a task has multiple steps or mixed states:
- Start with a one-line outcome that includes any blocker.
- Distinguish verified completion, work in progress, work not started, and unknown state. Omit empty categories.
- Put each blocker or material risk on its own line.
- Report only observed states. Mark an unknown as unknown and state what check would resolve it.
- End with the next action or a small numbered choice only when the user must decide.
## Explicit-Only: Spartan
Use Spartan style only when the user explicitly asks for it:
- Lead with the complete answer in one sentence.
- Be terse, blunt, and direct; remove warmth, hedging, transitions, narration, and summaries.
- Keep all load-bearing facts, warnings, and conditions even when they make the answer longer.
- If the user also asks for depth, provide the full detail in short, separated blocks.

View File

@@ -0,0 +1,37 @@
---
name: karpathy-guidelines
description: Keep implementation, refactoring, and code review assumption-aware, simple, surgical, and tied to verifiable success criteria.
---
<!--
GENERATED BY KRI AGENT HARNESS. DO NOT EDIT DIRECTLY.
Source: skills/karpathy-guidelines/SKILL.md
-->
# Karpathy Guidelines
Use these guidelines while implementing, refactoring, or reviewing code. They refine execution quality but do not expand the approved task scope.
## Think Before Coding
- Inspect the relevant code and repository conventions before choosing a solution.
- Surface an assumption when different choices would materially change behavior, compatibility, data, or scope.
- Ask only when the decision cannot be discovered safely and a reasonable assumption would be risky. Otherwise proceed with the smallest reasonable assumption and report it.
## Simplicity First
- Implement the smallest complete solution that satisfies the observable requirement.
- Do not add speculative abstractions, extension points, configuration, fallback paths, or dependencies for hypothetical future use.
- Prefer an existing repository pattern or standard-library capability over a new local framework.
## Surgical Changes
- Every changed line must trace to the approved objective, required validation, or a necessary compatibility adjustment.
- Preserve existing naming, structure, public behavior, and formatting outside that boundary.
- Do not mix the task with unrelated cleanup. Remove dead code, duplication, or ceremony introduced by the current change before finishing.
## Goal-Driven Execution
- Translate the request into observable success criteria before implementation.
- Choose the narrowest check that can fail for the behavior being changed, then run broader repository checks when appropriate.
- Iterate only within the approved scope until the criteria pass or a concrete blocker is established.
- Before reporting completion, inspect the final diff for unnecessary code and use `verification-before-completion` for fresh evidence.

View File

@@ -0,0 +1,29 @@
---
name: project-reference-loader
description: Load the current project-specific and shared reference documents routed by AGENTS.md before substantive repository analysis, implementation, debugging, review, or planning.
---
<!--
GENERATED BY KRI AGENT HARNESS. DO NOT EDIT DIRECTLY.
Source: skills/project-reference-loader/SKILL.md
-->
# Project Reference Loader
Use the repository's generated `AGENTS.md` as the routing entrypoint.
## Workflow
1. Find the `Required Project References` and shared-contract reference routes that match the current task.
2. Read the current contents of every matching file before relying on remembered project behavior, even when the file was read earlier in the session.
3. If the task crosses multiple scopes, read every matching reference. Do not load unrelated references merely because they exist.
4. Treat routed references as binding project instructions within their stated scope. Resolve conflicts using the precedence rules in `AGENTS.md`.
5. If a required reference is missing, unreadable, outside the repository, or internally inconsistent, stop the affected work and report the exact problem instead of guessing.
## Change Handling
- Edit authored project detail under `.agent/references/` when the durable rule belongs only to that repository.
- Edit the provider's `.agent/consumer-references/` when the rule is part of a shared consumer contract.
- Never edit generated `.agent-harness/references/` copies directly.
- Changing `.agent/references/` does not require recomposing `AGENTS.md` when its route is unchanged; changing routing, `project.md`, `consumer.md`, or shared reference sources does.
Before completion, confirm that the references used still exist and that the result does not contradict them. This skill does not expand authorization to edit, commit, push, deploy, connect to external systems, or perform destructive operations.

View File

@@ -0,0 +1,38 @@
---
name: verification-before-completion
description: Require fresh, claim-specific evidence before reporting work complete, fixed, passing, ready, or safe to commit or publish.
---
<!--
GENERATED BY KRI AGENT HARNESS. DO NOT EDIT DIRECTLY.
Source: skills/verification-before-completion/SKILL.md
-->
# Verification Before Completion
No completion claim without fresh evidence. This workflow verifies status; it does not authorize a commit, push, deployment, database operation, or other protected action.
## Verification Gate
Before making a success claim:
1. State the exact claim internally and identify which observable check can prove or disprove it.
2. Run the relevant command or inspection fresh after the final change. Use repository-defined commands; do not invent a substitute that proves a different property.
3. Read the complete result needed for the claim, including the exit code, failure count, skipped checks, and generated changes.
4. Compare the evidence with the claim and the approved acceptance criteria.
5. Report only the status supported by that evidence.
## Evidence Rules
- A passing lint does not prove compilation, a passing build does not prove runtime behavior, and a passing narrow test does not prove unrelated requirements.
- For a regression test, establish that it is capable of detecting the defect when practical; do not treat an always-passing test as proof.
- Recheck the worktree or final diff after generators, formatters, tests, or builds that may create or alter files.
- Separate verified results, failures, checks not run, and pre-existing failures. Never quietly merge them into a success statement.
- For delegated work, inspect the returned changes and run the relevant verification yourself before accepting the completion claim.
- For absence or universal claims such as “no occurrences” or “all projects,” use a check whose scope actually covers the claim.
## Reporting
- Cite the commands or inspections actually run and summarize their observed results.
- If a required check cannot run, state the actual incomplete or blocked status and the exact reason.
- Do not use “should work,” “probably passes,” “seems correct,” or similar language as a substitute for verification.
- Do not claim completion while a required check is failing or while known correctness, encoding, security, or generated-output drift remains unresolved.

View File

@@ -0,0 +1,41 @@
---
name: attention-aware-communication
description: Shape substantive answers, progress updates, and completion reports for fast, accurate reading without reducing the underlying work.
---
<!--
GENERATED BY KRI AGENT HARNESS. DO NOT EDIT DIRECTLY.
Source: skills/attention-aware-communication/SKILL.md
-->
# Attention-Aware Communication
This skill changes presentation only. Investigate, implement, and verify as deeply as the task requires.
## Default: Attention-kind
- Put the bottom line in the first sentence and use plain Korean.
- Say the least that fully answers, then stop. Remove preambles, padding, repetition, and closing restatements.
- Never omit a number, scope condition, risk, prerequisite, uncertainty, or other fact that could cause the user to act incorrectly.
- For genuine breadth, explain the one or two most important points first, name the remaining areas, and let the user choose whether to expand them. Do not use this to defer required caveats or a complete focused answer.
- When the user asks for a detailed explanation, walkthrough, rationale, or full picture, suspend brevity and provide the necessary detail in scannable sections.
- When asked for a deliverable such as a command, message, snippet, or commit text, return the deliverable without unnecessary framing unless safety or correctness requires context.
- Ask one blocking question at a time and put it last. Keep working when a non-blocking assumption is safe.
## Progress and Completion: Rundown
Use Rundown formatting when a task has multiple steps or mixed states:
- Start with a one-line outcome that includes any blocker.
- Distinguish verified completion, work in progress, work not started, and unknown state. Omit empty categories.
- Put each blocker or material risk on its own line.
- Report only observed states. Mark an unknown as unknown and state what check would resolve it.
- End with the next action or a small numbered choice only when the user must decide.
## Explicit-Only: Spartan
Use Spartan style only when the user explicitly asks for it:
- Lead with the complete answer in one sentence.
- Be terse, blunt, and direct; remove warmth, hedging, transitions, narration, and summaries.
- Keep all load-bearing facts, warnings, and conditions even when they make the answer longer.
- If the user also asks for depth, provide the full detail in short, separated blocks.

View File

@@ -0,0 +1,37 @@
---
name: karpathy-guidelines
description: Keep implementation, refactoring, and code review assumption-aware, simple, surgical, and tied to verifiable success criteria.
---
<!--
GENERATED BY KRI AGENT HARNESS. DO NOT EDIT DIRECTLY.
Source: skills/karpathy-guidelines/SKILL.md
-->
# Karpathy Guidelines
Use these guidelines while implementing, refactoring, or reviewing code. They refine execution quality but do not expand the approved task scope.
## Think Before Coding
- Inspect the relevant code and repository conventions before choosing a solution.
- Surface an assumption when different choices would materially change behavior, compatibility, data, or scope.
- Ask only when the decision cannot be discovered safely and a reasonable assumption would be risky. Otherwise proceed with the smallest reasonable assumption and report it.
## Simplicity First
- Implement the smallest complete solution that satisfies the observable requirement.
- Do not add speculative abstractions, extension points, configuration, fallback paths, or dependencies for hypothetical future use.
- Prefer an existing repository pattern or standard-library capability over a new local framework.
## Surgical Changes
- Every changed line must trace to the approved objective, required validation, or a necessary compatibility adjustment.
- Preserve existing naming, structure, public behavior, and formatting outside that boundary.
- Do not mix the task with unrelated cleanup. Remove dead code, duplication, or ceremony introduced by the current change before finishing.
## Goal-Driven Execution
- Translate the request into observable success criteria before implementation.
- Choose the narrowest check that can fail for the behavior being changed, then run broader repository checks when appropriate.
- Iterate only within the approved scope until the criteria pass or a concrete blocker is established.
- Before reporting completion, inspect the final diff for unnecessary code and use `verification-before-completion` for fresh evidence.

View File

@@ -0,0 +1,29 @@
---
name: project-reference-loader
description: Load the current project-specific and shared reference documents routed by AGENTS.md before substantive repository analysis, implementation, debugging, review, or planning.
---
<!--
GENERATED BY KRI AGENT HARNESS. DO NOT EDIT DIRECTLY.
Source: skills/project-reference-loader/SKILL.md
-->
# Project Reference Loader
Use the repository's generated `AGENTS.md` as the routing entrypoint.
## Workflow
1. Find the `Required Project References` and shared-contract reference routes that match the current task.
2. Read the current contents of every matching file before relying on remembered project behavior, even when the file was read earlier in the session.
3. If the task crosses multiple scopes, read every matching reference. Do not load unrelated references merely because they exist.
4. Treat routed references as binding project instructions within their stated scope. Resolve conflicts using the precedence rules in `AGENTS.md`.
5. If a required reference is missing, unreadable, outside the repository, or internally inconsistent, stop the affected work and report the exact problem instead of guessing.
## Change Handling
- Edit authored project detail under `.agent/references/` when the durable rule belongs only to that repository.
- Edit the provider's `.agent/consumer-references/` when the rule is part of a shared consumer contract.
- Never edit generated `.agent-harness/references/` copies directly.
- Changing `.agent/references/` does not require recomposing `AGENTS.md` when its route is unchanged; changing routing, `project.md`, `consumer.md`, or shared reference sources does.
Before completion, confirm that the references used still exist and that the result does not contradict them. This skill does not expand authorization to edit, commit, push, deploy, connect to external systems, or perform destructive operations.

View File

@@ -0,0 +1,38 @@
---
name: verification-before-completion
description: Require fresh, claim-specific evidence before reporting work complete, fixed, passing, ready, or safe to commit or publish.
---
<!--
GENERATED BY KRI AGENT HARNESS. DO NOT EDIT DIRECTLY.
Source: skills/verification-before-completion/SKILL.md
-->
# Verification Before Completion
No completion claim without fresh evidence. This workflow verifies status; it does not authorize a commit, push, deployment, database operation, or other protected action.
## Verification Gate
Before making a success claim:
1. State the exact claim internally and identify which observable check can prove or disprove it.
2. Run the relevant command or inspection fresh after the final change. Use repository-defined commands; do not invent a substitute that proves a different property.
3. Read the complete result needed for the claim, including the exit code, failure count, skipped checks, and generated changes.
4. Compare the evidence with the claim and the approved acceptance criteria.
5. Report only the status supported by that evidence.
## Evidence Rules
- A passing lint does not prove compilation, a passing build does not prove runtime behavior, and a passing narrow test does not prove unrelated requirements.
- For a regression test, establish that it is capable of detecting the defect when practical; do not treat an always-passing test as proof.
- Recheck the worktree or final diff after generators, formatters, tests, or builds that may create or alter files.
- Separate verified results, failures, checks not run, and pre-existing failures. Never quietly merge them into a success statement.
- For delegated work, inspect the returned changes and run the relevant verification yourself before accepting the completion claim.
- For absence or universal claims such as “no occurrences” or “all projects,” use a check whose scope actually covers the claim.
## Reporting
- Cite the commands or inspections actually run and summarize their observed results.
- If a required check cannot run, state the actual incomplete or blocked status and the exact reason.
- Do not use “should work,” “probably passes,” “seems correct,” or similar language as a substitute for verification.
- Do not claim completion while a required check is failing or while known correctness, encoding, security, or generated-output drift remains unresolved.

153
AGENTS.md
View File

@@ -35,6 +35,13 @@ Later and more specific instructions may override earlier general instructions o
- Lead with the result or decision, then provide only the detail needed to verify it. - Lead with the result or decision, then provide only the detail needed to verify it.
- Do not create or retain a full session transcript. - Do not create or retain a full session transcript.
### Attention-Aware Response Style
- Use `attention-aware-communication` for substantive answers, progress updates, and completion reports.
- Default to concise, bottom-line-first Korean without omitting a condition, risk, number, or uncertainty needed for a correct decision.
- Give full detail when the user requests depth. Use Spartan style only when explicitly requested.
- Presentation rules never reduce investigation, implementation, validation, or reporting obligations.
## Work Authorization ## Work Authorization
- The default workflow is discussion first and explicit execution approval second. - The default workflow is discussion first and explicit execution approval second.
@@ -152,6 +159,13 @@ Preferred human-facing tools:
- If a possible secret is discovered, do not repeat it. Report only its location, type, and recommended containment action. - If a possible secret is discovered, do not repeat it. Report only its location, type, and recommended containment action.
- Do not rotate, revoke, copy, or otherwise modify credentials unless that exact action is explicitly authorized. - Do not rotate, revoke, copy, or otherwise modify credentials unless that exact action is explicitly authorized.
## Workflow Skills
- Use `project-reference-loader` before substantive repository analysis, planning, implementation, debugging, or review. Read only the current project and shared references routed for that task, and reread them for each related task even if they were loaded earlier in the session.
- Use `karpathy-guidelines` when implementing, refactoring, or reviewing code. It keeps assumptions visible, changes surgical, and success criteria verifiable.
- Use `verification-before-completion` before claiming that work is complete, fixed, passing, ready, or safe to commit or publish.
- A skill does not expand task scope or authorize Git publication, database execution, deployment, destructive actions, or external communication.
## Validation ## Validation
- Discover supported build, test, lint, type-check, and formatting commands from repository files and project instructions. Do not invent commands. - Discover supported build, test, lint, type-check, and formatting commands from repository files and project instructions. Do not invent commands.
@@ -216,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.
@@ -235,81 +250,109 @@ When implementation is complete, report in Korean:
## KriFrontCommon Consumer Contract ## KriFrontCommon Consumer Contract
### Package Usage - Consume the published `@kri/common` package only through entry points declared by its `package.json` `exports` map.
- Consume this contract through the published `@kri/common` package and only through entry points declared in its `package.json` `exports` map.
- Use the package root for runtime-neutral object, URL, date, string, and shared type utilities.
- Use a focused subpath such as `@kri/common/http`, `@kri/common/browser`, `@kri/common/server`, `@kri/common/security`, `@kri/common/hooks`, `@kri/common/query`, `@kri/common/config`, `@kri/common/jotai`, or `@kri/common/noti-hub` for the corresponding capability.
- Do not import from `@kri/common/src/*`, `@kri/common/dist/*`, or another undeclared deep path. - Do not import from `@kri/common/src/*`, `@kri/common/dist/*`, or another undeclared deep path.
- Do not copy or fork a shared utility locally merely to avoid using an available public entry point. Propose a backward-compatible library addition when the shared contract is genuinely missing. - Prefer a public shared helper or an approved backward-compatible library addition over copying or forking shared behavior locally.
### Runtime and Optional Integrations
- Keep browser, server, and runtime-neutral imports on their intended side of the application boundary.
- A consumer that uses React hooks, TanStack Query, or Jotai integrations must provide the compatible optional peer dependency required by its selected entry point.
- Preserve the project's established HTTP client, authentication, error-policy, query-client, storage, and environment conventions when adopting a shared helper.
- Validate external data at runtime; a shared TypeScript type alone does not validate an API response or persisted value.
- Prefer named public exports and retain the consumer project's current module system and bundler conventions.
### Change Safety
- Pin or constrain the package version according to the consumer repository's dependency policy and commit its lockfile changes.
- Review release notes and the actual affected API before upgrading. Run the consumer's focused type-check, test, and build commands after an upgrade.
- Do not modify KriFrontCommon or another consumer repository unless it is explicitly included in the approved task scope. - Do not modify KriFrontCommon or another consumer repository unless it is explicitly included in the approved task scope.
## KriUiRegistry Consumer Contract ### Required Shared References
### UI Component Selection Before each related task, read the current contents of every matching reference, even if it was read earlier in the session.
| Task scope | Required reference |
|---|---|
| Package entry points, runtime boundaries, HTTP, authentication, state, storage, environment, or optional peer integrations | `.agent-harness/references/kri-front-common/package-and-runtime.md` |
| React rendering performance, memoization, or React Compiler behavior | `.agent-harness/references/kri-front-common/react-compiler.md` |
| Package upgrade, dependency changes, lockfile, or verification | `.agent-harness/references/kri-front-common/change-and-verification.md` |
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
When implementing or changing frontend UI, use this order: When implementing or changing frontend UI, use this order:
1. Reuse an existing shared component in the project when it already meets the requirement. 1. Reuse an existing shared component in the project when it already meets the requirement.
2. Prefer an approved component from KriUiRegistry. 2. Prefer an approved component from KriUiRegistry.
3. Otherwise, prefer a suitable shadcn/ui component. 3. Otherwise, prefer a suitable shadcn/ui component.
4. Create a new custom component only when the preceding options cannot meet the requirement without an unsafe or misleading adaptation. 4. Create a custom component only when the preceding options cannot meet the requirement safely.
### Installation and Ownership ### KriAutoComplete Search Scroll
- Inspect the registry item and its dependencies before installation. Use the shadcn CLI with the approved registry endpoint under `https://ui-registry.kric.com/r/` instead of copying files from `dist/r` manually. - `kri-auto-complete` exposes `resetScrollOnSearch?: boolean` on `KriSingleSelect`, `KriMultiSelect`, and `MultiSelect`. It defaults to `false`, preserving existing behavior.
- `kri-data-table` uses the TanStack Table v8 API. Keep `@tanstack/react-table` within the supported `^8.21.3` range and do not upgrade it to v9 until KriUiRegistry provides an explicitly migrated component contract. - 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.
- Respect the consumer project's component aliases, target paths, package manager, styling system, React version, and existing design tokens.
- The shadcn workflow copies component source into the consumer repository. After installation, treat that copy as project-owned code; do not assume registry updates propagate automatically.
- Do not overwrite an existing project component without reviewing the diff and confirming that local behavior and accessibility are preserved.
- Keep package and lockfile changes produced by an installation within the approved scope.
### Adaptation and Verification ### KriAutoComplete Option Tooltip
- Adapt business data and application behavior outside the shared component when possible. Avoid embedding project-specific API, route, authentication, or environment logic into a reusable component. - `kri-auto-complete` exposes `optionTooltip?: 'singleLine' | 'wrap'` and `optionTooltipClassName?: string` on `KriSingleSelect`, `KriMultiSelect`, and `MultiSelect`. It is off by default, preserving existing behavior.
- Preserve the installed component's public props, accessibility, keyboard behavior, responsive layout, and loading, empty, error, and disabled states unless the task explicitly changes them. - 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`.
- If the registry lacks a generally reusable capability, propose it in KriUiRegistry; do not modify that repository unless it is explicitly in scope.
- Run the consumer repository's focused type-check, lint, tests, and build after installation or upgrade.
## KriCreateNextApp Repository Rules ### KriAutoComplete Search Match
### Repository Role and Contracts - `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`.
- This repository provides the Node.js 20 TypeScript CLI `@kri/create-next-app` and the template used to create KRI Next.js frontend applications. ### KriEditor SMS Preview
- Treat command names, flags, prompts, defaults, generated paths, dependency policy, template structure, and validation order as public contracts.
- `src` is authoritative. `dist` is ignored build output and must not be edited or committed directly.
- Keep the CLI implementation, help text, README, and templates synchronized whenever generated behavior changes.
### Generated Frontend Invariants - `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.
- Generated applications use TypeScript, React, Next.js, `@kri/common`, shadcn, and the KRI UI Registry contract declared by this repository profile. ### Required Shared References
- Install `@kri/common@latest` and record the resolved dependency as an exact version using the existing npm workflow.
- Prefer shadcn and approved KRI UI Registry components over new local primitives when a suitable component exists.
- Do not introduce new frontend type or interface names ending in `Dto` or `DTO`.
- Generate `.agent/profile.yml`, `.agent/project.md`, and harness line-ending policy for every project. Never copy a stale precomposed `AGENTS.md` into the template.
### Harness Integration Before each related task, read the current contents of every matching reference, even if it was read earlier in the session.
- Generated projects default to `requested-project`; allow the supported explicit project-type override without changing the fixed `frontend` layer. | Task scope | Required reference |
- When the central harness is available, register the project in shared `workspace.yml` by default and run compose followed by verify. Allow an explicit local-registration override, and do not perform Git commits. Central-harness absence must not prevent project creation. |---|---|
- `AGENTS.md` and `CLAUDE.md` in this repository are harness-generated outputs. Never edit either file directly; edit `.agent` sources and recompose. | Installing, upgrading, adapting, or verifying a registry component | `.agent-harness/references/kri-ui-registry/installation-and-adaptation.md` |
- Do not commit user-specific absolute harness paths or credentials. Explicit paths are runtime inputs only. | KriEditor HTML, image-map, sanitizer, or WYSIWYG compatibility | `.agent-harness/references/kri-ui-registry/editor-html-compatibility.md` |
### Verification and Publication If a task spans multiple scopes, read every matching reference. Generated files under `.agent-harness/references/` are read-only copies; edit KriUiRegistry's `.agent/consumer.md` or `.agent/consumer-references/` and recompose instead.
- Run `npm.cmd run typecheck` and `npm.cmd run build` on Windows for CLI changes. # KriCreateNextApp Project Instruction Router
- Validate template changes by generating into a disposable directory without network installation first, then inspect unresolved placeholders, encoding, and harness composition.
- Package publication, registry access, and network installation require separate explicit approval. ## Required Project References
Before each related task, read the current contents of every matching reference below, even if it was read earlier in the session.
| Task scope | Required reference |
|---|---|
| Any substantive analysis, planning, implementation, debugging, review, or documentation work in this repository | `.agent/references/repository-rules.md` |
If a task spans multiple scopes, read every matching reference. Do not assume remembered content is current.
## Harness Workflow
- `AGENTS.md` and `CLAUDE.md` are generated outputs. Never edit them directly.
- Edit `.agent/project.md` only when routing changes. Store durable project detail in `.agent/references/`.
- A reference-only content change does not require recomposition when its route is unchanged. Run harness verification to validate routing and UTF-8.
- Recompose and verify after changing `.agent/project.md`, `.agent/profile.yml`, or another composed instruction source.

View File

@@ -50,18 +50,19 @@ 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`
## Agent Harness ## Agent Harness
생성 프로젝트에는 `.agent/profile.yml`, `.agent/project.md`, `.gitattributes`가 항상 포함됩니다. 생성 프로젝트에는 `.agent/profile.yml`, 라우팅 전용 `.agent/project.md`, 상세 규칙용 `.agent/references/repository-rules.md`, `.gitattributes`가 항상 포함됩니다.
중앙 하네스는 다음 순서로 탐색합니다. 중앙 하네스는 다음 순서로 탐색합니다.
@@ -78,6 +79,10 @@ 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 버전으로 기록합니다.
- Next.js 생태계 호환성을 위해 생성 프로젝트의 TypeScript는 최신 5.x, ESLint는 최신 9.x를 사용합니다. - `cn`은 `@kri/common`이 의존하는 버전을 읽어 같은 exact 버전으로 설치합니다. shadcn 기본 컴포넌트와 `@kri/common/ui`가 같은 `cn`을 사용해 중복 설치되지 않습니다.
- shadcn 기본 컴포넌트가 사용하는 `class-variance-authority`, `clsx`, `tailwind-merge`, `lucide-react`를 기본 의존성에 포함합니다. - Next.js 생태계 호환성을 위해 생성 프로젝트의 TypeScript는 최신 5.x, ESLint는 최신 9.x를 사용합니다. `eslint-config-next`에 포함된 일부 플러그인이 ESLint 10을 지원하지 않아 9.x를 유지합니다.
- `@types/node`는 배포 서버 Node 메이저(24)에 맞춰 최신 24.x를 사용합니다.
- shadcn 기본 컴포넌트가 사용하는 `class-variance-authority`, `lucide-react`를 기본 의존성에 포함합니다. 클래스 병합은 `clsx`·`tailwind-merge` 대신 `cn`을 사용합니다.

4
package-lock.json generated
View File

@@ -1,12 +1,12 @@
{ {
"name": "@kri/create-next-app", "name": "@kri/create-next-app",
"version": "0.1.5", "version": "0.2.2",
"lockfileVersion": 3, "lockfileVersion": 3,
"requires": true, "requires": true,
"packages": { "packages": {
"": { "": {
"name": "@kri/create-next-app", "name": "@kri/create-next-app",
"version": "0.1.5", "version": "0.2.2",
"license": "UNLICENSED", "license": "UNLICENSED",
"bin": { "bin": {
"kri-create-next-app": "dist/cli.js" "kri-create-next-app": "dist/cli.js"

View File

@@ -1,6 +1,6 @@
{ {
"name": "@kri/create-next-app", "name": "@kri/create-next-app",
"version": "0.1.6", "version": "0.3.1",
"description": "Create a KRI standard Next.js application", "description": "Create a KRI standard Next.js application",
"type": "module", "type": "module",
"bin": { "bin": {

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,40 @@ 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",
// 배포 서버 Node 메이저(24)에 맞춘다. 서버에 없는 API 사용을 타입 검사에서 잡기 위함.
"@types/node": "24",
"@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 +54,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 +124,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 +144,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를 생략합니다.");

View File

@@ -38,6 +38,6 @@ npm run build
- 프로젝트 ID: `__AGENT_PROJECT_ID__` - 프로젝트 ID: `__AGENT_PROJECT_ID__`
- 프로젝트 유형: `__AGENT_PROJECT_TYPE__` - 프로젝트 유형: `__AGENT_PROJECT_TYPE__`
- 권위 원본: `.agent/profile.yml`, `.agent/project.md` - 권위 원본: `.agent/profile.yml`, `.agent/project.md`, `.agent/references/*.md`
`AGENTS.md`와 `CLAUDE.md`는 중앙 Agent Harness가 합성합니다. 두 파일을 직접 수정하지 않습니다. `AGENTS.md`와 `CLAUDE.md`는 중앙 Agent Harness가 합성합니다. 두 파일을 직접 수정하지 않습니다.

View File

@@ -1,9 +1,18 @@
## Generated Next.js Repository Rules # __PROJECT_NAME__ Project Instruction Router
- This frontend application was generated by `@kri/create-next-app`. ## Required Project References
- Keep the generated Next.js routing, server/client boundary, authentication, environment, state, query, and application-shell conventions unless an approved task changes them.
- Prefer shadcn and approved KRI UI Registry components over new local primitives when a suitable component exists. Before each related task, read the current contents of every matching reference below, even if it was read earlier in the session.
- Do not create new TypeScript type or interface names ending in `Dto` or `DTO`.
- Consume shared frontend behavior from `@kri/common` and the KRI UI Registry instead of copying provider implementations into this repository. | Task scope | Required reference |
- `AGENTS.md` and `CLAUDE.md` are central-harness generated outputs. Never edit them directly; update `.agent/profile.yml` or `.agent/project.md` and recompose. |---|---|
- Run `npm run typecheck` and `npm run build` after relevant source or configuration changes. | Any substantive analysis, planning, implementation, debugging, review, or documentation work in this repository | `.agent/references/repository-rules.md` |
If a task spans multiple scopes, read every matching reference. Do not assume remembered content is current.
## Harness Workflow
- `AGENTS.md` and `CLAUDE.md` are generated outputs. Never edit them directly.
- Edit `.agent/project.md` only when routing changes. Store durable project detail in `.agent/references/`.
- A reference-only content change does not require recomposition when its route is unchanged. Run harness verification to validate routing and UTF-8.
- Recompose and verify after changing `.agent/project.md`, `.agent/profile.yml`, or another composed instruction source.

View File

@@ -0,0 +1,9 @@
## Generated Next.js Repository Rules
- This frontend application was generated by `@kri/create-next-app`.
- Keep the generated Next.js routing, server/client boundary, authentication, environment, state, query, and application-shell conventions unless an approved task changes them.
- Prefer shadcn and approved KRI UI Registry components over new local primitives when a suitable component exists.
- Do not create new TypeScript type or interface names ending in `Dto` or `DTO`.
- Consume shared frontend behavior from `@kri/common` and the KRI UI Registry instead of copying provider implementations into this repository.
- `AGENTS.md` and `CLAUDE.md` are central-harness generated outputs. Never edit them directly; update `.agent/profile.yml` or `.agent/project.md` and recompose.
- Run `npm run typecheck` and `npm run build` after relevant source or configuration changes.

View File

@@ -1,4 +1,5 @@
/AGENTS.md text eol=lf /AGENTS.md text eol=lf
/CLAUDE.md text eol=lf /CLAUDE.md text eol=lf
/.agent/*.md text eol=lf /.agent/*.md text eol=lf
/.agent/**/*.md text eol=lf
/.agent/*.yml text eol=lf /.agent/*.yml text eol=lf

View File

@@ -14,8 +14,5 @@ npm-debug.log*
yarn-debug.log* yarn-debug.log*
yarn-error.log* yarn-error.log*
.pnpm-debug.log* .pnpm-debug.log*
.env
.env.local
.env.*.local
.idea/ .idea/
*.iml *.iml

View File

@@ -1,6 +1,7 @@
"use client"; "use client";
import { useMemo, useState } from "react"; import type { Route } from "next";
import { useMemo, useState, type ReactNode } from "react";
import { usePathname, useRouter } from "next/navigation"; import { usePathname, useRouter } from "next/navigation";
import { KriMainLayout } from "@/components/layout/KriMainLayout"; import { KriMainLayout } from "@/components/layout/KriMainLayout";
import { AppHeader } from "./AppHeader"; import { AppHeader } from "./AppHeader";
@@ -8,7 +9,7 @@ import { AppSidebar } from "./AppSidebar";
import { sideMenus, topMenus } from "@/config/menu.data"; import { sideMenus, topMenus } from "@/config/menu.data";
import { useAuth } from "@/hooks/useAuth"; import { useAuth } from "@/hooks/useAuth";
export function AppMainLayout({ children }: { children: React.ReactNode }) { export function AppMainLayout({ children }: { children: ReactNode }) {
const pathname = usePathname(); const pathname = usePathname();
const router = useRouter(); const router = useRouter();
const { auth } = useAuth(); const { auth } = useAuth();
@@ -19,7 +20,7 @@ export function AppMainLayout({ children }: { children: React.ReactNode }) {
[pathname], [pathname],
); );
const navigate = (path: string) => router.push(path); const navigate = (path: string) => router.push(path as Route);
const hasSidebar = sideMenus.length > 0; const hasSidebar = sideMenus.length > 0;
return ( return (

View File

@@ -1,35 +1,48 @@
"use client"; "use client";
import { useCallback } from "react"; import { useCallback } from "react";
import { useAtom } from "jotai";
import type { LoginUser } from "@kri/common"; import type { LoginUser } from "@kri/common";
import { createAuthHook, type AuthState as CommonAuthState } from "@kri/common/hooks"; import type { AuthState as CommonAuthState } from "@kri/common/hooks";
import { createPersistentAtom } from "@kri/common/jotai";
import { getLocalStorage, removeLocalStorage, setLocalStorage } from "@/store/storage/secure-storage"; import { getLocalStorage, removeLocalStorage, setLocalStorage } from "@/store/storage/secure-storage";
import { StorageKeys } from "@/store/storage/storage-keys"; import { StorageKeys } from "@/store/storage/storage-keys";
export type AuthState = CommonAuthState<LoginUser>; export type AuthState = CommonAuthState<LoginUser>;
const initialAuthState: AuthState = { user: null }; const initialAuthState: AuthState = { user: null };
const loadInitialAuthState = (): AuthState => { const isRecord = (value: unknown): value is Record<string, unknown> =>
const stored = getLocalStorage(StorageKeys.AuthState); typeof value === "object" && value !== null && !Array.isArray(value);
return stored && typeof stored === "object" && "user" in stored
? { ...initialAuthState, ...(stored as Partial<AuthState>) } const isLoginUser = (value: unknown): value is LoginUser => {
: initialAuthState; if (!isRecord(value)) return false;
return (
typeof value.userId === "string" &&
typeof value.userName === "string" &&
typeof value.userCmpn === "string" &&
typeof value.userTeam === "string" &&
typeof value.userRole === "number"
);
}; };
const { authAtom, useAuth: useCommonAuth } = createAuthHook<LoginUser>({ initialState: loadInitialAuthState() }); const isPersistedAuthState = (value: unknown): value is AuthState =>
export const authStateAtom = authAtom; isRecord(value) && isLoginUser(value.user);
/*
* atom은 서버·클라이언트 최초 렌더 모두 initialAuthState로 시작한다.
* 저장소 값은 onMount(마운트 이후 시점)에만 반영되므로
* 서버 HTML과 클라이언트 최초 렌더가 항상 일치해 하이드레이션 오류가 발생하지 않는다.
*/
export const authStateAtom = createPersistentAtom<AuthState>(StorageKeys.AuthState, initialAuthState, {
storage: { get: getLocalStorage, set: setLocalStorage, remove: removeLocalStorage },
validate: isPersistedAuthState,
shouldRemove: (value) => value.user === null,
debugLabel: "authState",
});
export function useAuth() { export function useAuth() {
const { auth, setAuth: setCommonAuth } = useCommonAuth(); const [auth, setAuth] = useAtom(authStateAtom);
const setAuth = useCallback((next: AuthState | ((previous: AuthState) => AuthState)) => {
setCommonAuth((previous) => {
const resolved = typeof next === "function" ? next(previous) : next;
if (resolved.user === null) removeLocalStorage(StorageKeys.AuthState);
else setLocalStorage(StorageKeys.AuthState, resolved);
return resolved;
});
}, [setCommonAuth]);
const setFromLoginResponse = useCallback((user: LoginUser) => setAuth({ user }), [setAuth]); const setFromLoginResponse = useCallback((user: LoginUser) => setAuth({ user }), [setAuth]);
const logout = useCallback(() => setAuth(initialAuthState), [setAuth]); const logout = useCallback(() => setAuth(initialAuthState), [setAuth]);