Skip to content

Commit 6fff4c4

Browse files
AdrianRomanskiAdrianRomanski
committed
docs(wiki-cli): add main readme
1 parent 831004d commit 6fff4c4

2 files changed

Lines changed: 183 additions & 17 deletions

File tree

‎apps/wiki-cli/README.md‎

Lines changed: 106 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,113 @@
1-
# wiki-cli
1+
# Wiki CLI (`apps/wiki-cli`)
22

3-
## `src/index.ts`
3+
`wiki-cli` is the centralized command-line interface application for the LLM Wiki Knowledge Monorepo. Built as a single bundled Node.js application, it exposes workspace maintenance tasks—manifest generation, index generation, tag distribution validation, and directory scaffolding—as native Nx targets.
44

5-
CLI entry point. Reads the subcommand from `process.argv`, resolves the workspace root, and dispatches to the matching command module:
5+
---
66

7-
- `generate-manifest` → `runGenerateManifest`
8-
- `generate-index` → `runGenerateIndex`
9-
- `validate-tags` → `runValidateTags`
10-
- `init` → `runInit`
7+
## Architectural Role
118

12-
Sets `process.exitCode` to `1` for unknown commands or unhandled errors.
9+
`wiki-cli` serves as the **Presentation / Driver Layer** in the system's Clean (Hexagonal) Architecture:
1310

14-
## `src/commands`
11+
```text
12+
┌────────────────────────┐
13+
│ apps/wiki-cli │ (Driver / Presentation Layer)
14+
│ - src/index.ts │ Command CLI Router
15+
│ - src/commands/*.ts │ Composition Roots
16+
└───────────┬────────────┘
17+
│ Wires & Injects
18+
▼
19+
┌──────────────────────────────────────┐
20+
│ libs/application-* │ (Application Layer)
21+
│ - application-index-manager │ Use Cases (Pure Domain Logic)
22+
│ - application-tag-validation │
23+
│ - application-scaffolding │
24+
└──────────────────▲───────────────────┘
25+
│ Depends on Interfaces
26+
┌──────────────────┴───────────────────┐
27+
│ libs/infrastructure-* │ (Infrastructure Layer)
28+
│ - infrastructure-filesystem │ Adapters (FS, YAML, Markdown)
29+
│ - infrastructure-frontmatter │
30+
│ - infrastructure-markdown │
31+
└──────────────────────────────────────┘
32+
```
1533

16-
Each file is a thin composition root: it wires Infrastructure adapters into an Application use case and prints the result. No business logic lives here.
34+
- **Composition Roots Only**: Code inside `wiki-cli` contains no business logic. Its sole responsibility is parsing CLI arguments, instantiating concrete Infrastructure adapters, passing them to Application use cases, and rendering formatted outputs to `stdout`.
35+
- **Decoupled Business Rules**: Features such as threshold validation, markdown index formatting, manifest scanning, and directory scaffolding live entirely within pure `@wiki/application-*` libraries.
1736

18-
- **`generate-manifest.command.ts`** Wires `FileSystemAdapter` into `GenerateManifestUseCase`.
19-
<br> Writes `wiki/manifest.json` and prints the list of files it contains.
20-
- **`generate-index.command.ts`** Wires `FileSystemAdapter`, `FrontmatterAdapter`, and `MarkdownAdapter` into `GenerateIndexUseCase`.
21-
<br> Regenerates `wiki/index.md` and prints the entity/concept/source counts.
22-
- **`validate-tags.command.ts`** Wires `FileSystemAdapter` and `FrontmatterAdapter` into `ValidateTagDistributionUseCase`.
23-
<br> Prints a formatted tag frequency table plus any threshold violations (60% max), and returns `0` (pass) or `1` (fail) as the process exit code.
24-
- **`init.command.ts`** Checks for an existing Angular project (informational only) then wires `FileSystemAdapter` into `ScaffoldWikiUseCase` to create the initial `wiki/`/`raw/` directory structure, logging created vs. existing directories.
37+
---
38+
39+
## Workspace Subcommands & Nx Targets
40+
41+
You can execute commands via Nx targets from the workspace root:
42+
43+
| Nx Target | Subcommand | Description |
44+
|---|---|---|
45+
| `nx run wiki-cli:generate-manifest` | `generate-manifest` | Scans `wiki/` pages and generates `wiki/manifest.json`. |
46+
| `nx run wiki-cli:generate-index` | `generate-index` | Re-indexes entities, concepts, and sources into `wiki/index.md`. |
47+
| `nx run wiki-cli:validate-tags` | `validate-tags` | Validates tag frequency distribution against the 60% threshold. Returns exit code 0 or 1. |
48+
| `nx run wiki-cli:init` | `init` | Scaffolds the initial `wiki/` and `raw/` directory structure. |
49+
50+
### Direct Binary Execution
51+
52+
After running `nx run wiki-cli:build`, the compiled bundle resides at `dist/apps/wiki-cli/index.cjs` and can be invoked directly:
53+
54+
```bash
55+
node dist/apps/wiki-cli/index.cjs generate-manifest
56+
node dist/apps/wiki-cli/index.cjs generate-index
57+
node dist/apps/wiki-cli/index.cjs validate-tags
58+
node dist/apps/wiki-cli/index.cjs init
59+
```
60+
61+
---
62+
63+
## Directory Structure
64+
65+
```text
66+
apps/wiki-cli/
67+
├── project.json # Nx project configuration & targets
68+
├── package.json # App package definition
69+
├── tsconfig.json # TypeScript base configuration
70+
├── tsconfig.app.json # Build-specific TS configuration
71+
├── tsconfig.spec.json # Test TS configuration
72+
├── vitest.config.ts # Vitest test runner setup
73+
├── README.md # Module documentation
74+
└── src/
75+
├── index.ts # CLI Entry Point & command router
76+
├── wrappers.smoke.spec.ts # Smoke tests for CLI binary & contract
77+
└── commands/ # Subcommand composition roots
78+
├── generate-manifest.command.ts
79+
├── generate-index.command.ts
80+
├── validate-tags.command.ts
81+
├── init.command.ts
82+
└── README.md # Commands documentation
83+
```
84+
85+
---
86+
87+
## Entry Point & Command Dispatcher (`src/index.ts`)
88+
89+
- **Workspace Root Resolution**: Resolves the monorepo root dynamically using `path.resolve(__dirname, '..', '..', '..')` so paths remain consistent regardless of working directory.
90+
- **CLI Dispatching**: Extracts `process.argv[2]`, matches it to handler functions in `src/commands/`, and sets `process.exitCode` appropriately.
91+
- **Exit Code Contract**:
92+
- `0`: Successful execution or passing validation.
93+
- `1`: Unknown command, thrown error, or failed validation (e.g., tag frequency > 60%).
94+
95+
---
96+
97+
## Build & Test
98+
99+
### Building
100+
101+
The build target uses `@nx/esbuild:esbuild` to bundle `wiki-cli` into a single CommonJS executable (`dist/apps/wiki-cli/index.cjs`) with a Node hashbang banner (`#!/usr/bin/env node`):
102+
103+
```bash
104+
npx nx run wiki-cli:build
105+
```
106+
107+
### Testing
108+
109+
Smoke tests verify that the compiled binary executes properly and adheres to output and exit-code contracts:
110+
111+
```bash
112+
npx nx run wiki-cli:test
113+
```

‎apps/wiki-cli/src/commands/README.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Wiki CLI Commands (`src/commands`)
2+
3+
This directory contains the **thin composition roots** (drivers) for each subcommand supported by `wiki-cli`.
4+
5+
## Architectural Role
6+
7+
Following Clean / Hexagonal Architecture principles:
8+
- **Zero Business Logic**: No business rules, file parsing logic, tag calculations, or directory creation algorithms are defined here.
9+
- **Dependency Injection**: Each module instantiates concrete Infrastructure adapters (e.g., `FileSystemAdapter`, `FrontmatterAdapter`, `MarkdownAdapter`) and injects them into pure Application use cases.
10+
- **I/O & Reporting**: Commands run use cases, log progress or summary metrics to `stdout`, and return process exit codes where required.
11+
12+
---
13+
14+
## Command Reference
15+
16+
### `generate-manifest.command.ts`
17+
18+
- **Function**: `runGenerateManifest(workspaceRoot: string): Promise<void>`
19+
- **Wired Adapters**:
20+
- `FileSystemAdapter` (from `@wiki/infrastructure-filesystem`)
21+
- **Use Case**: `GenerateManifestUseCase` (from `@wiki/application-index-manager`)
22+
- **Target Command**: `nx run wiki-cli:generate-manifest`
23+
- **Behavior**:
24+
1. Scans `wiki/entities/`, `wiki/concepts/`, and `wiki/sources/`.
25+
2. Generates and writes `wiki/manifest.json`.
26+
3. Logs the total count and list of indexed files to standard output.
27+
28+
---
29+
30+
### `generate-index.command.ts`
31+
32+
- **Function**: `runGenerateIndex(workspaceRoot: string): Promise<void>`
33+
- **Wired Adapters**:
34+
- `FileSystemAdapter` (from `@wiki/infrastructure-filesystem`)
35+
- `FrontmatterAdapter` (from `@wiki/infrastructure-frontmatter`)
36+
- `MarkdownAdapter` (from `@wiki/infrastructure-markdown`)
37+
- **Use Case**: `GenerateIndexUseCase` (from `@wiki/application-index-manager`)
38+
- **Target Command**: `nx run wiki-cli:generate-index`
39+
- **Behavior**:
40+
1. Scans `wiki/` pages and parses YAML frontmatter and markdown headings.
41+
2. Builds categorized lists of entities, concepts, and sources.
42+
3. Rewrites `wiki/index.md` with structured links and descriptions.
43+
4. Reports counts for each page category.
44+
45+
---
46+
47+
### `validate-tags.command.ts`
48+
49+
- **Function**: `runValidateTags(workspaceRoot: string): Promise<number>`
50+
- **Wired Adapters**:
51+
- `FileSystemAdapter` (from `@wiki/infrastructure-filesystem`)
52+
- `FrontmatterAdapter` (from `@wiki/infrastructure-frontmatter`)
53+
- **Use Case**: `ValidateTagDistributionUseCase` (from `@wiki/application-tag-validation`)
54+
- **Target Command**: `nx run wiki-cli:validate-tags`
55+
- **Behavior**:
56+
1. Scans all wiki pages to compute tag frequencies across the corpus.
57+
2. Evaluates each tag against a **60% maximum frequency threshold**.
58+
3. Displays a formatted table listing the top 20 most frequent tags, counts, frequencies, and PASS/FAIL statuses.
59+
4. Outputs actionable recommendations if threshold violations exist.
60+
- **Return Code**:
61+
- `0`: Validation passed (no tags exceed 60%).
62+
- `1`: Validation failed (one or more tags exceed 60%).
63+
64+
---
65+
66+
### `init.command.ts`
67+
68+
- **Function**: `runInit(workspaceRoot: string): Promise<void>`
69+
- **Wired Adapters**:
70+
- `FileSystemAdapter` (from `@wiki/infrastructure-filesystem`)
71+
- **Use Case**: `ScaffoldWikiUseCase` (from `@wiki/application-scaffolding`)
72+
- **Target Command**: `nx run wiki-cli:init`
73+
- **Behavior**:
74+
1. Performs informational checks for existing Angular project markers (`apps/`, `libs/`, `.kiro/`, `angular.json`).
75+
2. Invokes `ScaffoldWikiUseCase` to ensure `wiki/` and `raw/` directory hierarchies exist.
76+
3. Reports created vs. existing directories.
77+
4. Displays helpful next steps for workspace setup.

0 commit comments

Comments
 (0)