@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/snippets/vue/useAsync.ts

@@ -0,0 +1,96 @@
+import { ref, type Ref, shallowRef } from "vue";
+
+interface UseAsyncOptions<T> {
+  immediate?: boolean;
+  initialData?: T;
+  onSuccess?: (data: T) => void;
+  onError?: (error: Error) => void;
+}
+
+interface UseAsyncReturn<T, P extends unknown[]> {
+  data: Ref<T | undefined>;
+  error: Ref<Error | null>;
+  loading: Ref<boolean>;
+  execute: (...args: P) => Promise<T>;
+  reset: () => void;
+}
+
+/**
+ * Vue composable for async operations with loading/error states
+ */
+export function useAsync<T, P extends unknown[] = []>(
+  asyncFn: (...args: P) => Promise<T>,
+  options: UseAsyncOptions<T> = {},
+): UseAsyncReturn<T, P> {
+  const { immediate = false, initialData, onSuccess, onError } = options;
+
+  const data = shallowRef<T | undefined>(initialData);
+  const error = ref<Error | null>(null);
+  const loading = ref(false);
+
+  async function execute(...args: P): Promise<T> {
+    loading.value = true;
+    error.value = null;
+
+    try {
+      const result = await asyncFn(...args);
+      data.value = result;
+      onSuccess?.(result);
+      return result;
+    } catch (e) {
+      const err = e instanceof Error ? e : new Error(String(e));
+      error.value = err;
+      onError?.(err);
+      throw err;
+    } finally {
+      loading.value = false;
+    }
+  }
+
+  function reset(): void {
+    data.value = initialData;
+    error.value = null;
+    loading.value = false;
+  }
+
+  // Execute immediately if option is set
+  if (immediate) {
+    execute(...([] as unknown as P));
+  }
+
+  return {
+    data: data as Ref<T | undefined>,
+    error,
+    loading,
+    execute,
+    reset,
+  };
+}
+
+/**
+ * Simplified version that returns tuple
+ */
+export function useAsyncFn<T, P extends unknown[] = []>(
+  asyncFn: (...args: P) => Promise<T>,
+): [Ref<boolean>, (...args: P) => Promise<T | undefined>, Ref<Error | null>] {
+  const loading = ref(false);
+  const error = ref<Error | null>(null);
+
+  async function execute(...args: P): Promise<T | undefined> {
+    loading.value = true;
+    error.value = null;
+
+    try {
+      return await asyncFn(...args);
+    } catch (e) {
+      error.value = e instanceof Error ? e : new Error(String(e));
+      return undefined;
+    } finally {
+      loading.value = false;
+    }
+  }
+
+  return [loading, execute, error];
+}
+
+export default useAsync;

package/dist/resources/snippets/vue/usePagination.ts

@@ -0,0 +1,102 @@
+import { ref, computed, type Ref, type ComputedRef } from "vue";
+
+interface UsePaginationOptions {
+  page?: number;
+  pageSize?: number;
+  total?: number;
+}
+
+interface UsePaginationReturn {
+  page: Ref<number>;
+  pageSize: Ref<number>;
+  total: Ref<number>;
+  pageCount: ComputedRef<number>;
+  isFirstPage: ComputedRef<boolean>;
+  isLastPage: ComputedRef<boolean>;
+  offset: ComputedRef<number>;
+  prev: () => void;
+  next: () => void;
+  goTo: (page: number) => void;
+  setPageSize: (size: number) => void;
+  setTotal: (total: number) => void;
+  reset: () => void;
+}
+
+/**
+ * Vue composable for pagination logic
+ */
+export function usePagination(options: UsePaginationOptions = {}): UsePaginationReturn {
+  const {
+    page: initialPage = 1,
+    pageSize: initialPageSize = 10,
+    total: initialTotal = 0,
+  } = options;
+
+  const page = ref(initialPage);
+  const pageSize = ref(initialPageSize);
+  const total = ref(initialTotal);
+
+  const pageCount = computed(() => Math.ceil(total.value / pageSize.value) || 1);
+
+  const isFirstPage = computed(() => page.value === 1);
+
+  const isLastPage = computed(() => page.value >= pageCount.value);
+
+  const offset = computed(() => (page.value - 1) * pageSize.value);
+
+  function prev(): void {
+    if (!isFirstPage.value) {
+      page.value--;
+    }
+  }
+
+  function next(): void {
+    if (!isLastPage.value) {
+      page.value++;
+    }
+  }
+
+  function goTo(targetPage: number): void {
+    const validPage = Math.max(1, Math.min(targetPage, pageCount.value));
+    page.value = validPage;
+  }
+
+  function setPageSize(size: number): void {
+    pageSize.value = size;
+    // Reset to first page when page size changes
+    page.value = 1;
+  }
+
+  function setTotal(newTotal: number): void {
+    total.value = newTotal;
+    // Adjust current page if it exceeds new page count
+    const newPageCount = Math.ceil(newTotal / pageSize.value) || 1;
+    if (page.value > newPageCount) {
+      page.value = newPageCount;
+    }
+  }
+
+  function reset(): void {
+    page.value = initialPage;
+    pageSize.value = initialPageSize;
+    total.value = initialTotal;
+  }
+
+  return {
+    page,
+    pageSize,
+    total,
+    pageCount,
+    isFirstPage,
+    isLastPage,
+    offset,
+    prev,
+    next,
+    goTo,
+    setPageSize,
+    setTotal,
+    reset,
+  };
+}
+
+export default usePagination;

package/dist/resources/templates/base/.claude/docs/architecture-template.md

@@ -0,0 +1,459 @@
+# Architecture Document Template
+
+> Architecture designs follow this complete skeleton. Root semantic-impact rules determine depth; non-applicable sections require an explicit ownership reason, not silent deletion.
+> After completing a new module's design document, archive it at `docs/designs/{module}-architecture.md`.
+
+---
+
+## Level A: New Module / Major Architecture Change
+
+Complete architecture document, must include all of the following sections. Refer to existing documents in `docs/designs/`.
+
+### Mandatory Skeleton
+
+# {Module Name} Architecture Design Document
+
+> **Version**: 1.0
+> **Module Complexity**: Domain state machine / Service and adapter / Pure transformation
+> **Tech Stack**: Node.js + TypeScript + installed Nuxt or MCP stack
+> **Design Reference**: {Industry reference, e.g. Stripe API, Shopify Order}
+
+---
+
+## 1. Architecture Overview
+
+### 1.1 Module Position in the System
+
+[ASCII diagram: Browser/MCP Host → Route/Tool → This Module → Service Adapter → Owning External Service]
+
+### 1.2 Core Capabilities
+
+| Capability     | Description            |
+| -------------- | ---------------------- |
+| {Capability 1} | {One-line description} |
+
+### 1.3 Design Principles
+
+| Principle   | Application in This Module |
+| ----------- | -------------------------- |
+| {Principle} | {Specific application}     |
+
+### 1.4 Module Complexity Assessment
+
+{Answer the complexity decision tree: Does it have a state machine? → Does it have complex domain logic? → Which Tier?}
+
+---
+
+## 2. Core Concept Definitions
+
+### 2.1 Concept Relationship Diagram
+
+[ASCII diagram: Relationships between entities (1:N, N:M, reference)]
+
+### 2.2 Concept Description Table
+
+| Concept  | Definition            | TypeScript Type | Persistence          |
+| -------- | --------------------- | --------------- | -------------------- |
+| {Entity} | {One-line definition} | `Resource`      | `{module}_resources` |
+
+---
+
+## 3. Persistence and State Design
+
+### 3.1 Authoritative State and Storage Overview
+
+| Table Name           | Description | Row Volume |
+| -------------------- | ----------- | ---------- |
+| `{module}_resources` | {Purpose}   | {Estimate} |
+
+### 3.2 Detailed Table Definitions
+
+For persistent server-owned tables, include the fields below. If this module owns no database, record that boundary and specify the upstream contract, cache identity and invalidation instead. Client state never substitutes for authoritative persistence.
+
+| Column | Type        | Nullable | Default | Comment     |
+| ------ | ----------- | -------- | ------- | ----------- |
+| `id`   | `bigserial` | NO       | —       | Primary key |
+| ...    | ...         | ...      | ...     | ...         |
+
+Index definitions:
+
+| Index | Columns | Type             | Purpose |
+| ----- | ------- | ---------------- | ------- |
+| ...   | ...     | unique/btree/gin | ...     |
+
+### 3.3 Migration Files
+
+```sql
+-- Complete SQL, ready to execute
+CREATE TABLE {module}_resources (
+    ...
+);
+```
+
+---
+
+## 4. Directory Structure Design
+
+### 4.1 Complete Directory Tree
+
+```
+src/ or app/
+├── {feature}/
+│   ├── types.ts           # Public inputs, outputs and errors
+│   ├── service.ts         # Application use cases
+│   ├── adapter.ts         # External protocol translation
+│   └── state.ts           # Owned state and transitions
+└── entry or plugin        # Dependency assembly and lifetime
+
+Choose concrete paths from the actual stack document. Nuxt pages belong in
+app/pages and server handlers in server/api; MCP tool registrations belong in
+src/tools.ts. This diagram is a design structure, not a claim that every
+application already contains these modules.
+```
+
+### 4.2 Package Split Decision
+
+{Answer the package split rules from CLAUDE.md: Which owner has two real consumers? Which types remain feature-private? Does a shared contract avoid framework or provider leakage?}
+
+---
+
+## 5. Domain Model Design
+
+### 5.1 Aggregate Root
+
+```typescript
+interface Resource {
+  id: string;
+  status: ResourceStatus;
+  createdAt: string;
+}
+type ResourceStatus = "pending" | "processing" | "completed" | "failed" | "cancelled";
+```
+
+### 5.2 State Machine (if applicable)
+
+```
+State transition diagram:
+  pending → processing, cancelled
+  processing → completed, failed
+  completed (terminal)
+  cancelled (terminal)
+  failed (terminal)
+```
+
+```typescript
+const transitions: Record<ResourceStatus, readonly ResourceStatus[]> = {
+  pending: ["processing", "cancelled"],
+  processing: ["completed", "failed"],
+  completed: [],
+  failed: [],
+  cancelled: [],
+};
+```
+
+### 5.3 Behavior Methods
+
+| Method Signature                             | Purpose                     | Caller  |
+| -------------------------------------------- | --------------------------- | ------- |
+| `isEligible(resource): boolean`              | {Condition check}           | Service |
+| `canTransitionTo(resource, target): boolean` | {State transition validity} | Service |
+| `transitionTo(resource, target): Resource`   | {Execute state transition}  | Service |
+
+### 5.4 Repository Interface
+
+```typescript
+interface ResourceRepository {
+  findById(id: string, signal: AbortSignal): Promise<Resource | null>;
+  save(resource: Resource, signal: AbortSignal): Promise<Resource>;
+}
+```
+
+### 5.5 Domain Events
+
+| Event             | Trigger                   | Consumer          |
+| ----------------- | ------------------------- | ----------------- |
+| `XxxCreatedEvent` | After successful creation | {module} Listener |
+
+---
+
+## 6. Application Service Design
+
+### 6.1 Service Method List
+
+| Method                          | Parameters         | Return                      | Business Rules |
+| ------------------------------- | ------------------ | --------------------------- | -------------- |
+| `createResource(input, signal)` | `CreateXxxRequest` | `Promise<ResourceResponse>` | {Key logic}    |
+
+### 6.2 Key Workflows
+
+{Describe main business flows in steps:}
+
+```
+CreateXxx:
+  1. Validate input
+  2. Check business rules (call model methods)
+  3. Persist
+  4. Publish event
+  5. Record safe correlation and audit metadata through the owning adapter
+  6. Return VO
+```
+
+---
+
+## 7. API Interface Design
+
+HTTP endpoints use the following tables. For MCP, specify tool/resource name, input schema, result content, protocol/execution error and authorization scope in the same contract section; do not invent HTTP status codes for stdio calls.
+
+### 7.1 Endpoint List
+
+| Method | Path              | Auth          | Handler     | Description |
+| ------ | ----------------- | ------------- | ----------- | ----------- |
+| POST   | `/api/v1/xxx`     | authenticated | `CreateXxx` | Create      |
+| GET    | `/api/v1/xxx/:id` | authenticated | `GetXxx`    | Query       |
+
+### 7.2 Request/Response Examples
+
+**POST /api/v1/xxx**
+
+Request:
+
+```json
+{
+  "name": "example",
+  "type": "standard"
+}
+```
+
+Response (201):
+
+```json
+{
+  "id": 1,
+  "name": "example",
+  "type": "standard",
+  "status": "pending",
+  "created_at": "2026-01-01T00:00:00Z"
+}
+```
+
+Error (422):
+
+```json
+{
+  "error": {
+    "type": "business_error",
+    "code": "xxx_limit_exceeded",
+    "message": "Cannot create more than 10 items"
+  }
+}
+```
+
+---
+
+## 8. Event-Driven Integration (if cross-module interaction exists)
+
+### 8.1 Published Events
+
+| Event             | Definition Location   | Trigger                   |
+| ----------------- | --------------------- | ------------------------- |
+| `XxxCreatedEvent` | `{feature}/events.ts` | After successful creation |
+
+### 8.2 Consumed Events
+
+| Event                  | Source Module  | Handling Logic             |
+| ---------------------- | -------------- | -------------------------- |
+| `ResourceChangedEvent` | owning service | Invalidate dependent state |
+
+---
+
+## 9. Composition and Lifecycle Design
+
+### 9.1 Typed Dependency Assembly
+
+```typescript
+interface Dependencies {
+  repository: ResourceRepository;
+  signal: AbortSignal;
+}
+interface ResourceService {
+  findById(id: string): Promise<Resource | null>;
+}
+function createResourceService(deps: Dependencies): ResourceService {
+  return {
+    findById: (id) => deps.repository.findById(id, deps.signal),
+  };
+}
+```
+
+### 9.2 Assembly per Runtime
+
+| Runtime             | Injected Content                     | Notes                                          |
+| ------------------- | ------------------------------------ | ---------------------------------------------- |
+| Nuxt request/plugin | Request/application-scoped services  | Never share identity state across SSR requests |
+| MCP stdio process   | Tool/resource services and transport | Explicit close/cancellation ownership          |
+
+---
+
+## 10. Design Decisions
+
+| Decision     | Choice   | Alternatives  | Rationale |
+| ------------ | -------- | ------------- | --------- |
+| {Decision 1} | {Choice} | {Alternative} | {Reason}  |
+
+---
+
+## 11. Implementation Plan
+
+### Wave 1: Foundation
+
+| File                 | Change                             |
+| -------------------- | ---------------------------------- |
+| `{feature}/types.ts` | Create entities + behavior methods |
+| `{feature}/state.ts` | Status enums + transition rules    |
+
+### Wave 2: Infrastructure
+
+| File | Change |
+| ---- | ------ |
+
+### Wave 3: Application
+
+| File | Change |
+| ---- | ------ |
+
+### Wave 4: Assembly
+
+| File | Change |
+| ---- | ------ |
+
+### Wave 5: Verification
+
+- `pnpm typecheck`
+- `pnpm build`
+- Declared stack behavior/transport checks
+- Quantitative verification (grep counts)
+
+---
+
+## 12. P1-P11 Verification
+
+| Principle                      | Status       | Notes            |
+| ------------------------------ | ------------ | ---------------- |
+| P1 Domain model has behavior   | {Pass / N/A} | {Specific notes} |
+| P2 Service uses model methods  | {Pass / N/A} |                  |
+| P3 Module is self-registering  | {Pass / N/A} |                  |
+| P4 Handler has zero logic      | {Pass / N/A} |                  |
+| P5 Inject minimum dependencies | {Pass / N/A} |                  |
+| P6 File placement              | {Pass / N/A} |                  |
+| P7 Entity never exposed        | {Pass / N/A} |                  |
+| P8 End-to-end traceability     | {Pass / N/A} |                  |
+| P9 Correct status codes        | {Pass / N/A} |                  |
+| P10 No deferred code           | {Pass / N/A} |                  |
+| P11 Audit on writes            | {Pass / N/A} |                  |
+
+### Optional Sections (add as needed)
+
+Include the following sections based on module characteristics:
+
+| Section                                | When Needed                                      | Reference                              |
+| -------------------------------------- | ------------------------------------------------ | -------------------------------------- |
+| Security Design                        | Involves authentication, encryption, permissions | Trust and credential boundary          |
+| Caching Strategy                       | Has Redis caching requirements                   | Cache ownership and invalidation       |
+| Strategy Engine / Provider Abstraction | Multi-channel/multi-vendor integration           | Interface/configuration/adapter design |
+| Privacy Compliance (GDPR)              | Stores personal data                             | Personal-data retention and deletion   |
+| Monitoring & Operations                | Prometheus metrics / alerting                    | Bounded operational metrics            |
+| Internationalization                   | i18n requirements                                | Locale and fallback contract           |
+
+---
+
+## Level B: Feature Addition / Significant Change
+
+Adding features to an existing module or making significant changes. Does not require a full architecture document, but must produce all of the following sections:
+
+# {Feature Name} Design Document
+
+## 1. Change Scope
+
+| Dimension       | Impact                                                 |
+| --------------- | ------------------------------------------------------ |
+| Modules         | {List of affected modules}                             |
+| Database Tables | {List of affected tables}                              |
+| API Endpoints   | {New/modified endpoints}                               |
+| Events          | {New/modified events}                                  |
+| Composition     | {Affected plugins, server handlers or MCP entrypoints} |
+
+## 2. Industry Reference
+
+{How does the industry solve this problem? Who was referenced?}
+
+## 3. Database Changes
+
+For each new/modified field:
+| Column | Type | Nullable | Default | Comment | Table |
+|--------|------|----------|---------|---------|-------|
+
+Migration SQL:
+
+```sql
+ALTER TABLE ...
+```
+
+## 4. Domain Model Changes
+
+New/modified entity fields and behavior methods.
+Include state machine changes (if any).
+
+## 5. API Changes
+
+Complete request/response contracts for new/modified endpoints.
+
+## 6. Data Flow
+
+For each new field, trace the full path:
+Source → Parsed input → Service → Adapter → Typed result → State → Presentation/protocol result
+
+## 7. Implementation Plan
+
+File change list organized by Wave.
+
+## 8. P1-P11 Verification
+
+Confirm each affected principle one by one.
+
+---
+
+## Level C: Bug Fix / Minor Change
+
+Small-scope fixes or adjustments. Must produce:
+
+# {Bug/Change} Fix Design
+
+## 1. Root Cause Analysis
+
+{What is the problem, why it happens, scope of impact}
+
+## 2. Fix Design
+
+{Specific approach, not just "fix the bug"}
+
+## 3. Affected Files
+
+| File | Change |
+| ---- | ------ |
+| ...  | ...    |
+
+## 4. Verification Method
+
+{How to confirm the fix works and doesn't introduce new issues}
+
+---
+
+## Task Level Decision
+
+```
+Is this a new module or major architecture change?
+  → YES: Level A (full architecture document)
+  → NO: Does it change an existing contract, security or lifecycle boundary?
+    → YES: Level B (focused design document)
+    → NO: Level C (fix design)
+```