@akanjs/cli 0.0.145 → 0.0.146

package/cjs/src/guidelines/docPageRule/docPageRule.instruction.md

@@ -0,0 +1,382 @@
+# Akan.js Documentation Page Creation Guide
+
+## Purpose of Documentation Pages in Akan.js
+
+Documentation pages serve as the comprehensive knowledge base for Akan.js framework developers. They:
+- Provide clear explanations of framework concepts, architecture, and components
+- Offer technical reference for APIs, modules, and system functionalities
+- Present implementation examples with real-world code snippets
+- Establish consistent standards for documentation across the framework
+- Support multi-language access for international developers
+- Serve as onboarding resources for new team members
+- Document best practices and common patterns for framework usage
+
+## How to Create a Documentation Page
+
+### 1. File Location and Structure
+
+Documentation pages should be created in the following location:
+```
+apps/angelo/app/[lang]/akanjs/(docs)/docs/[category]/[pageName]/page.tsx
+```
+
+Where:
+- `[lang]`: Language code (e.g., `en`, `ko`)
+- `[category]`: Main documentation category (e.g., `systemArch`, `module`, `api`)
+- `[pageName]`: Specific page name (e.g., `frontend`, `signal`, `authentication`)
+
+Example path:
+`apps/angelo/app/en/akanjs/(docs)/docs/module/signal/page.tsx`
+
+### 2. Basic Page Structure
+
+Each documentation page follows this basic structure:
+
+```tsx
+import { usePage } from "@angelo/client";
+import { Docs } from "@/ui/Docs";
+
+export default function Page() {
+  const { l } = usePage(); // For internationalization
+  
+  return (
+    <>
+      <Docs.Title>
+        {l.trans({
+          en: "Main Page Title",
+          ko: "메인 페이지 제목"
+        })}
+      </Docs.Title>
+      
+      <Docs.Description>
+        {l.trans({
+          en: "Introduction paragraph that explains the concept...",
+          ko: "개념을 설명하는 소개 문단..."
+        })}
+      </Docs.Description>
+      
+      <div className="divider"></div>
+      
+      <Docs.SubTitle>
+        {l.trans({
+          en: "Section Title",
+          ko: "섹션 제목"
+        })}
+      </Docs.SubTitle>
+      
+      <Docs.Description>
+        {l.trans({
+          en: "Detailed explanation of this section...",
+          ko: "이 섹션에 대한 자세한 설명..."
+        })}
+      </Docs.Description>
+      
+      <Docs.CodeSnippet
+        language="typescript"
+        code={`
+// Code example
+const example = "Hello Akan.js";
+`}
+      />
+      
+      {/* Additional sections and components */}
+    </>
+  );
+}
+```
+
+### 3. Page Organization
+
+Documentation pages should be organized in a hierarchical structure:
+
+1. **Title**: Main page title (`<Docs.Title>`)
+2. **Introduction**: Brief overview (`<Docs.Description>`)
+3. **Sections**: Main content sections
+   - Section title (`<Docs.SubTitle>`)
+   - Section content (`<Docs.Description>`)
+   - Code examples (`<Docs.CodeSnippet>`)
+   - Subsections (`<Docs.SubSubTitle>`)
+   - Tables (`<Docs.OptionTable>`, `<Docs.IntroTable>`)
+4. **Related Content**: Links to related documentation pages
+
+### 4. Internationalization
+
+All user-facing text must support multiple languages using the translation hook:
+
+```tsx
+const { l } = usePage();
+
+<Docs.Title>
+  {l.trans({
+    en: "English Title",
+    ko: "한국어 제목"
+    // Add other languages as needed
+  })}
+</Docs.Title>
+```
+
+## Utility Components
+
+The `Docs` namespace provides specialized components for creating consistent documentation pages. Always import and use them with the `Docs` prefix:
+
+```tsx
+import { Docs } from "@/ui/Docs";
+// Correct usage: <Docs.Title>, NOT import { Title } from "@/ui/Docs";
+```
+
+### 1. Title Components
+
+```tsx
+<Docs.Title>Main Page Title</Docs.Title>             // H1 equivalent
+<Docs.SubTitle>Section Title</Docs.SubTitle>         // H2 equivalent
+<Docs.SubSubTitle>Subsection Title</Docs.SubSubTitle> // H3 equivalent
+```
+
+### 2. Content Components
+
+**Description Block:**
+```tsx
+<Docs.Description>
+  Detailed explanatory text that supports:
+  - Markdown-style formatting
+  - Multi-paragraph content
+  - HTML elements
+  - Internationalization via l.trans()
+</Docs.Description>
+```
+
+**Code Snippet:**
+```tsx
+<Docs.CodeSnippet
+  language="typescript" // Supported: typescript, bash, and others
+  code={`
+    // Your code example with syntax highlighting
+    const example = "Hello Akan.js";
+    function demo() {
+      return example;
+    }
+  `}
+/>
+```
+
+### 3. Table Components
+
+**Option Table:** For displaying configuration options, parameters, or properties
+```tsx
+<Docs.OptionTable
+  items={[
+    {
+      key: "optionName",     // Option identifier
+      type: "string",        // Data type
+      default: "defaultVal", // Default value
+      desc: "Description",   // Explanation (can use l.trans())
+      example: "example()"   // Usage example
+    },
+    // Additional items...
+  ]}
+/>
+```
+
+**Introduction Table:** For listing and describing related items
+```tsx
+<Docs.IntroTable
+  type="conceptName"  // Table category identifier
+  items={[
+    {
+      name: "itemName",    // Item name
+      desc: "Description", // Explanation (can use l.trans())
+      example: "example()" // Usage example
+    },
+    // Additional items...
+  ]}
+/>
+```
+
+### 4. Code Display Components
+
+**Inline Code:**
+```tsx
+<Docs.Code language="typescript">inlineCodeExample</Docs.Code>
+```
+
+**Custom Code Block:**
+```tsx
+<Docs.CodeView>
+  <Docs.Code prefix="1">// First line with line number</Docs.Code>
+  <Docs.Code prefix="2">// Second line with line number</Docs.Code>
+</Docs.CodeView>
+```
+
+### 5. Layout Components
+
+The document layout is automatically applied through the parent layout.tsx file, so you don't need to use `<Docs.Layout>` in your page component.
+
+**Header and Footer:**
+```tsx
+<Docs.Header>Header content</Docs.Header>
+<Docs.Footer>Footer content</Docs.Footer>
+```
+
+## Best Practices
+
+### 1. Content Organization
+
+- Begin with a clear, concise introduction that explains the purpose and importance of the topic
+- Use a logical hierarchy of headings (Title → SubTitle → SubSubTitle)
+- Structure content to flow from basic concepts to advanced usage
+- Include a "Getting Started" or "Basic Usage" section near the beginning
+- Group related information under appropriate section headings
+- Maintain consistent terminology throughout the document
+
+### 2. Code Examples
+
+- Include complete, working code examples that can be copied and used directly
+- Provide context for each code example to explain what it demonstrates
+- Use realistic, practical examples rather than overly simplified ones
+- Include comments in code examples to explain key points
+- Specify the correct language for proper syntax highlighting
+- Show both basic and advanced usage patterns
+
+### 3. Formatting and Style
+
+- Use sentence case for all headings (e.g., "How to use signals" not "How To Use Signals")
+- Keep paragraphs focused on a single concept
+- Use lists for sequential steps or related items
+- Include whitespace (dividers, margins) to separate sections visually
+- Apply consistent formatting across all documentation pages
+
+### 4. Internationalization
+
+- Wrap all user-facing text in `l.trans()` calls with at least English and Korean translations
+- Maintain parallel structure and meaning across languages
+- Keep translations concise but complete
+- Use descriptive keys for translation objects
+
+### 5. Performance and Accessibility
+
+- Use lazy-loading for heavy components when appropriate
+- Ensure documentation is responsive for both desktop and mobile viewing
+- Include anchor links to specific sections for easy reference
+- Provide alt text for images and diagrams
+- Avoid overly complex or deeply nested components
+
+## Complete Example
+
+```tsx
+import { usePage } from "@angelo/client";
+import { Docs, type IntroItem, type OptionItem } from "@/ui/Docs";
+
+export default function SignalDocsPage() {
+  const { l } = usePage();
+  
+  // Define configuration options
+  const signalOptions: OptionItem[] = [
+    {
+      key: "initialValue",
+      type: "T",
+      default: "undefined",
+      desc: l.trans({
+        en: "Initial value of the signal",
+        ko: "시그널의 초기값"
+      }),
+      example: "signal(0)"
+    },
+    // Additional options...
+  ];
+  
+  // Define feature list
+  const signalFeatures: IntroItem[] = [
+    {
+      name: "createSignal",
+      desc: l.trans({
+        en: "Creates a new reactive signal",
+        ko: "새로운 반응형 시그널을 생성"
+      }),
+      example: "const [value, setValue] = createSignal(0)"
+    },
+    // Additional features...
+  ];
+
+  return (
+    <>
+      <Docs.Title>
+        {l.trans({
+          en: "Signal Module",
+          ko: "시그널 모듈"
+        })}
+      </Docs.Title>
+      
+      <Docs.Description>
+        {l.trans({
+          en: "The Signal module provides reactive state management capabilities for Akan.js applications. Signals allow components to efficiently respond to state changes without unnecessary re-renders.",
+          ko: "시그널 모듈은 Akan.js 애플리케이션을 위한 반응형 상태 관리 기능을 제공합니다. 시그널을 통해 컴포넌트는 불필요한 재렌더링 없이 상태 변화에 효율적으로 반응할 수 있습니다."
+        })}
+      </Docs.Description>
+      
+      <div className="divider"></div>
+      
+      <Docs.SubTitle>
+        {l.trans({
+          en: "Basic Usage",
+          ko: "기본 사용법"
+        })}
+      </Docs.SubTitle>
+      
+      <Docs.Description>
+        {l.trans({
+          en: "Creating and using signals is straightforward:",
+          ko: "시그널 생성 및 사용은 간단합니다:"
+        })}
+      </Docs.Description>
+      
+      <Docs.CodeSnippet
+        language="typescript"
+        code={`
+// Create a signal with an initial value
+const count = signal(0);
+
+// Read the signal value
+console.log(count()); // 0
+
+// Update the signal value
+count(1);
+console.log(count()); // 1
+
+// Use in a component
+function Counter() {
+  return <div>{count()}</div>;
+}`}
+      />
+      
+      <Docs.SubTitle>
+        {l.trans({
+          en: "Configuration Options",
+          ko: "설정 옵션"
+        })}
+      </Docs.SubTitle>
+      
+      <Docs.OptionTable items={signalOptions} />
+      
+      <Docs.SubTitle>
+        {l.trans({
+          en: "API Reference",
+          ko: "API 참조"
+        })}
+      </Docs.SubTitle>
+      
+      <Docs.IntroTable type="function" items={signalFeatures} />
+    </>
+  );
+}
+```
+
+## Troubleshooting
+
+1. **Layout Issues**: Do not manually add `<Docs.Layout>` as it's automatically applied at the layout level
+2. **Component Import**: Always use the namespace import `import { Docs } from "@/ui/Docs"` and reference components as `<Docs.ComponentName>`
+3. **Translation Issues**: Ensure all user-facing text uses `l.trans()` with complete translations for all supported languages
+4. **Code Highlighting**: Verify the correct language is specified for `<Docs.CodeSnippet>` and `<Docs.Code>` components
+5. **Style Consistency**: If your documentation looks different from others, compare with existing pages to identify styling discrepancies
+6. **Navigation Anchors**: For long pages, include anchor links by adding hidden divs with IDs
+
+For additional assistance, refer to existing documentation pages or contact the framework documentation team.

package/cjs/src/guidelines/modelStore/modelStore.instruction.md

@@ -24,7 +24,7 @@ Model stores follow a consistent architecture pattern:
          ▼
 ┌─────────────────┐     ┌─────────────────┐
 │    st.ts        │ ──→ │   Components    │
-│ (Store Registry) │     │  (React/UI)     │
+│(Store Registry) │     │   (React/UI)    │
 └─────────────────┘     └─────────────────┘
 ```
 
@@ -466,6 +466,7 @@ initProductChat(productId: string) {
    - Implement retry logic for critical operations
 
 5. **Testing**:
+
    - Mock stores with initial state for unit tests
 
      ```typescript

package/esm/index.js

@@ -5554,26 +5554,32 @@ ${guideJson.update.rules.map((rule) => `- ${rule}`).join("\n")}
     const instruction = await Prompter.getInstruction(this.name);
     const pageContent = this.workspace.getLocalFile(writePath);
     const request = `
-\uB098\uB294 Akan.js \uD504\uB808\uC784\uC6CC\uD06C\uC5D0 \uB300\uD55C documentation \uC6F9\uC0AC\uC774\uD2B8\uB97C \uB9CC\uB4E4\uACE0 \uC788\uC5B4.
+I'm creating a documentation website for the Akan.js framework.
 
-1. Akan.js \uD504\uB808\uC784\uC6CC\uD06C\uC5D0 \uB300\uD55C \uAC1C\uC694
+1. Overview of the Akan.js framework
 ${await this.getDocumentation("framework")}
 
-\uB098\uB294 ${writePath}\uC5D0 \uC788\uB294 Next.js \uC11C\uBC84\uC0AC\uC774\uB4DC \uD398\uC774\uC9C0\uB97C \uC5C5\uB370\uC774\uD2B8\uD558\uB824\uACE0 \uD574.
-\uC544\uB798\uB294 \uD604\uC7AC \uC791\uC131\uB41C \uD398\uC774\uC9C0\uC758 \uB0B4\uC6A9\uC774\uC57C.
+2. Documentation page writing method
+${await this.getDocumentation("docPageRule")}
+
+3. CSS rule with TailwindCSS and DaisyUI
+${await this.getDocumentation("cssRule")}
+
+I want to update the Next.js server-side page located at ${writePath}.
+Below is the content of the currently written page.
 \`\`\`tsx
 // File: ${writePath}
 ${pageContent.content}
 \`\`\`
 
-\uD574\uB2F9 \uD398\uC774\uC9C0\uC5D0 \uC544\uB798 \uB0B4\uC6A9\uC744 \uCD5C\uC2E0\uD654 \uD574\uC11C \uC5C5\uB370\uC774\uD2B8\uD574\uC918. \uADFC\uC0AC\uD55C \uB514\uC790\uC778\uC73C\uB85C \uC801\uC6A9\uC774 \uD544\uC694\uD574.
+Please update this page with the latest content below. A great design application is needed.
 ${instruction}
 
-CSS\uADDC\uCE59\uC740 \uB2E4\uC74C\uC744 \uB530\uB77C\uC11C \uC791\uC131\uD574\uC918.
-- tailwindcss\uB97C \uC0AC\uC6A9\uD560 \uAC83
-- daisyui \uB77C\uC774\uBE0C\uB7EC\uB9AC\uC758 className\uC744 \uC0AC\uC6A9\uD560 \uAC83
+Please follow these CSS rules when writing:
+- Use tailwindcss
+- Use className from the daisyui library
 
-\uD30C\uC2F1\uD558\uAE30 \uC27D\uAC8C \uD30C\uC77C \uACB0\uACFC\uB9CC \uB2E4\uC74C\uACFC \uAC19\uC740 \uD615\uC2DD\uC73C\uB85C \uBC18\uD658\uD574\uC918.
+Please return only the file result in the following format for easy parsing.
 \`\`\`tsx
 // File: ${writePath}
 ...pageContent
@@ -5592,14 +5598,14 @@ var GuidelineRunner = class {
     const guidelineContent = await session.editMarkdown(request);
     workspace.writeFile(writePath, guidelineContent);
   }
-  async deployDocPages(workspace, guideName) {
+  async deployDocPage(workspace, guideName) {
     const session = new AiSession("deployDocPages", { workspace, cacheKey: guideName });
     const guideJson = await Prompter.getGuideJson(guideName);
     const prompt = new GuidelinePrompt(workspace, guideName);
-    const { request, writePath } = await prompt.requestUpdateDocumentPage(guideJson.page);
-    const guidelineContent = await session.editMarkdown(request);
-    workspace.writeFile(writePath, guidelineContent);
-    return Promise.resolve({});
+    if (!guideJson.page)
+      return Promise.resolve({});
+    const { request } = await prompt.requestUpdateDocumentPage(guideJson.page);
+    await session.writeTypescripts(request, workspace);
   }
 };
 
@@ -5610,9 +5616,9 @@ var GuidelineScript = class {
     const guideName = name ?? await Prompter.selectGuideline();
     await this.#runner.generateInstruction(workspace, guideName);
   }
-  async deployDocPages(workspace, name = null) {
+  async deployDocPage(workspace, name = null) {
     const guideName = name ?? await Prompter.selectGuideline();
-    await this.#runner.deployDocPages(workspace, guideName);
+    await this.#runner.deployDocPage(workspace, guideName);
   }
 };
 
@@ -5622,8 +5628,8 @@ var GuidelineCommand = class {
   async generateInstruction(name, workspace) {
     await this.guidelineScript.generateInstruction(workspace, name);
   }
-  async deployDocs(name, workspace) {
-    await this.guidelineScript.deployDocPages(workspace, name);
+  async deployDoc(name, workspace) {
+    await this.guidelineScript.deployDocPage(workspace, name);
   }
 };
 __decorateClass([
@@ -5635,7 +5641,7 @@ __decorateClass([
   Target.Public(),
   __decorateParam(0, Argument("name", { ask: "name of the instruction", nullable: true })),
   __decorateParam(1, Workspace())
-], GuidelineCommand.prototype, "deployDocs", 1);
+], GuidelineCommand.prototype, "deployDoc", 1);
 GuidelineCommand = __decorateClass([
   Commands()
 ], GuidelineCommand);

package/esm/src/guidelines/componentRule/componentRule.instruction.md

@@ -5,10 +5,9 @@
 1. [Component Architecture](#component-architecture)
 2. [Component Types](#component-types)
 3. [File Naming Conventions](#file-naming-conventions)
-4. [CSS Rule with TailwindCSS and DaisyUI](#css-rule-with-tailwindcss-and-daisyui)
-5. [Utility Functions](#utility-functions)
-6. [Best Practices](#best-practices)
-7. [Complete Examples](#complete-examples)
+4. [Utility Functions](#utility-functions)
+5. [Best Practices](#best-practices)
+6. [Complete Examples](#complete-examples)
 
 ---
 
@@ -248,83 +247,6 @@ Akan.js uses a strict naming convention to maintain consistency:
 
 ---
 
-## CSS Rule with TailwindCSS and DaisyUI
-
-Akan.js uses TailwindCSS with DaisyUI for styling. Follow these guidelines:
-
-### 1. Class Management
-
-Always use `clsx` for conditional and composite classes:
-
-```tsx
-import { clsx } from "@akanjs/client";
-
-className={clsx(
-  "base-classes",
-  condition && "conditional-class",
-  variant === "primary" ? "primary-class" : "secondary-class",
-  className // Always include passed className for composition
-)}
-```
-
-### 2. Color System
-
-Use DaisyUI's theme colors instead of hardcoded values. This ensures theme consistency and dark/light mode compatibility:
-
-```tsx
-// Good - uses theme colors
-className = "bg-primary text-base-100";
-
-// Bad - uses hardcoded colors
-className = "bg-[#C33C32] text-[#FFFFFF]";
-```
-
-DaisyUI provides semantic colors:
-
-- `primary`, `secondary`, `accent` - Brand colors
-- `base-100` through `base-900` - Background/text variants
-- `info`, `success`, `warning`, `error` - Status colors
-
-### 3. Responsive Design
-
-Use Tailwind's responsive prefixes:
-
-```tsx
-<div className="flex-col md:flex-row">
-  <div className="w-full md:w-1/2 lg:w-1/3">Responsive width</div>
-  <div className="hidden lg:block">Only visible on large screens</div>
-</div>
-```
-
-### 4. Animation
-
-Use Tailwind animation classes with transitions:
-
-```tsx
-<div className="transition-all duration-300 hover:scale-105">
-  Hover effect
-</div>
-
-<div className="animate-pulse">Loading indicator</div>
-```
-
-### 5. Component Styling
-
-Use DaisyUI components for consistent UIs:
-
-```tsx
-<button className="btn btn-primary btn-sm">Primary Button</button>
-
-<div className="card bg-base-200 shadow-md">
-  <div className="card-body">
-    <h2 className="card-title">Card Title</h2>
-    <p>Card content</p>
-  </div>
-</div>
-```
-
----
-
 ## Utility Functions
 
 Akan.js provides several utility modules for common frontend tasks: