Build a Complete Wikipedia CLI Application
This capstone project combines every concept from the course into a single, production‑ready command‑line tool. You'll create a multi‑package workspace with a polished CLI, robust error handling, structured logging, and unit tests.
🎯 Project Overview
Create a CLI tool called Wiki Explorer Pro that allows users to:
Search Wikipedia articles and display results with URLsGet a summary of any article by titleView article extracts in plain text or HTMLCompare two articles side‑by‑sideExport search results or summaries to a JSON fileLog all requests and errors to daily log filesRun in interactive mode with a menu, or accept direct commands
🏗️ Architecture Requirements
Your project must use a multi‑package workspace with at least three packages:
command_runner – A reusable CLI framework (commands, arguments, help)wikipedia – API client with model classes and JSON parsingcli – The main application entry point and concrete commands
Each package should have its own pubspec.yaml and be linked via a root workspace.
📋 Detailed Requirements
1. Command Runner Package
Abstract Command class with name, description, run()
Support for flags and options (e.g., --verbose, --output)
Built‑in HelpCommand that displays usage for all commands
Custom ArgumentException for invalid user input
CommandRunner class that parses input and dispatches commands
2. Wikipedia Package
Model classes: SearchResult, ArticleSummary, Article
Use pattern matching in fromJson() factories
Methods: search(), getSummary(), getArticle()
Simulated API calls with realistic delays (use Future.delayed)
Throw custom exceptions (ArticleNotFoundException, ApiException)
3. CLI Application
Commands: search, summary, compare, export
Interactive mode when no arguments given (menu loop)
Accept command‑line arguments for direct execution
Logging : create a logger that writes to logs/YYYY_MM_DD_wiki.logLog all searches, errors, and API response times
Graceful error handling with user‑friendly messages
4. Testing
Unit tests for Wikipedia model classes (valid JSON, invalid JSON, missing fields)
Tests for CommandRunner argument parsing
At least 10 test cases total
📺 Expected Behavior
$ dart run bin/cli.dart search Dart programming
🔍 Searching for "Dart programming"...
1. Dart (programming language) - https://en.wikipedia.org/wiki/Dart_(programming_language)
2. Dartmoor - https://en.wikipedia.org/wiki/Dartmoor
3. Dartford - https://en.wikipedia.org/wiki/Dartford
✅ Search completed in 1.2s
$ dart run bin/cli.dart summary Dart
📖 Dart (programming language)
──────────────────────────────────────
Dart is a programming language designed by Lars Bak and Kasper Lund and developed by Google. It can be used to develop web and mobile apps as well as server and desktop applications.
──────────────────────────────────────
🔗 https://en.wikipedia.org/wiki/Dart_(programming_language)
$ dart run bin/cli.dart compare Dart Flutter
📊 Comparing Articles
──────────────────────────────────────
Dart | Flutter
──────────────────────────────────────
Programming language | UI toolkit
Developed by Google | Developed by Google
First appeared 2011 | First appeared 2017
──────────────────────────────────────
🔒 Click to reveal the complete solution (build it yourself first!)
name: _
publish_to: none
environment:
sdk: ^3.12.0
workspace:
- cli
- command_runner
- wikipedia
name: command_runner
description: A reusable CLI command framework.
version: 1.0.0
resolution: workspace
environment:
sdk: ^3.12.0
library command_runner;
export 'src/command.dart';
export 'src/command_runner_base.dart';
export 'src/exceptions.dart';
abstract class Command {
final String name;
final String description;
final List
options = [];
CommandRunner? runner;
Command(this.name, this.description);
void addOption(Option option) {
options.add(option);
}
Future run(ArgResults args);
String get usage {
final buffer = StringBuffer('$name - $description');
if (options.isNotEmpty) {
buffer.write('\nOptions:');
for (var opt in options) {
buffer.write('\n --${opt.name.padRight(15)} ${opt.help}');
}
}
return buffer.toString();
}
}
class Option {
final String name;
final String help;
final bool isFlag;
Option(this.name, this.help, {this.isFlag = false});
}
class ArgResults {
String? commandArg;
final Map flags = {};
final Map options = {};
}
import 'command.dart';
import 'exceptions.dart';
class CommandRunner {
final Map _commands = {};
void Function(String)? onOutput;
void Function(Object)? onError;
void addCommand(Command command) {
_commands[command.name] = command;
command.runner = this;
}
List get commands => _commands.values.toList();
Future run(List input) async {
try {
final results = parse(input);
if (results.command != null) {
String? output = await results.command!.run(results);
if (output != null) {
if (onOutput != null) {
onOutput!(output);
} else {
print(output);
}
}
}
} on Exception catch (e) {
if (onError != null) {
onError!(e);
} else {
rethrow;
}
}
}
ArgResults parse(List input) {
final results = ArgResults();
if (input.isEmpty) return results;
if (_commands.containsKey(input.first)) {
results.command = _commands[input.first];
input = input.sublist(1);
} else {
throw ArgumentException('Unknown command: ${input.first}');
}
// Parse remaining arguments
for (int i = 0; i < input.length; i++) {
if (input[i].startsWith('--')) {
final flagName = input[i].substring(2);
results.flags[flagName] = true;
} else if (input[i].startsWith('-')) {
final optName = input[i].substring(1);
if (i + 1 < input.length && !input[i + 1].startsWith('-')) {
results.options[optName] = input[i + 1];
i++;
} else {
results.flags[optName] = true;
}
} else {
if (results.commandArg == null) {
results.commandArg = input[i];
}
}
}
return results;
}
}
class ArgumentException implements Exception {
final String message;
ArgumentException(this.message);
@override
String toString() => 'ArgumentException: $message';
}
name: wikipedia
description: Wikipedia API client.
version: 1.0.0
resolution: workspace
environment:
sdk: ^3.12.0
dependencies:
http: ^1.3.0
library wikipedia;
export 'src/models.dart';
export 'src/api_client.dart';
export 'src/exceptions.dart';
class SearchResult {
final String title;
final String url;
SearchResult({required this.title, required this.url});
factory SearchResult.fromJson(Map json) {
return SearchResult(
title: json['title'] as String,
url: json['url'] as String,
);
}
}
class ArticleSummary {
final String title;
final String extract;
final String? description;
final String? url;
ArticleSummary({
required this.title,
required this.extract,
this.description,
this.url,
});
factory ArticleSummary.fromJson(Map json) => switch (json) {
{
'title': final String title,
'extract': final String extract,
} => ArticleSummary(
title: title,
extract: extract,
description: json['description'] as String?,
url: json['content_urls']?['desktop']?['page'] as String?,
),
_ => throw FormatException('Invalid summary JSON'),
};
}
class Article {
final String title;
final String extractHtml;
Article({required this.title, required this.extractHtml});
factory Article.fromJson(Map json) {
return Article(
title: json['title'] as String,
extractHtml: json['extract_html'] as String,
);
}
}
import 'dart:convert';
import 'dart:math';
import 'package:http/http.dart' as http;
import 'models.dart';
import 'exceptions.dart';
class WikipediaClient {
final Random _random = Random();
final String _baseUrl = 'https://en.wikipedia.org';
Future> search(String query) async {
await _simulateDelay();
final url = Uri.parse(
'$_baseUrl/w/api.php?action=opensearch&format=json&search=${Uri.encodeComponent(query)}&limit=5'
);
final response = await http.get(url);
if (response.statusCode != 200) {
throw ApiException('Search failed with status ${response.statusCode}');
}
final data = jsonDecode(response.body);
if (data is! List || data.length < 4) {
throw ApiException('Unexpected response format');
}
final titles = data[1] as List;
final urls = data[3] as List;
return List.generate(
titles.length,
(i) => SearchResult(title: titles[i].toString(), url: urls[i].toString()),
);
}
Future getSummary(String title) async {
await _simulateDelay();
final url = Uri.parse(
'$_baseUrl/api/rest_v1/page/summary/${Uri.encodeComponent(title)}',
);
final response = await http.get(url);
if (response.statusCode == 404) {
throw ArticleNotFoundException(title);
} else if (response.statusCode != 200) {
throw ApiException('Failed to fetch summary: ${response.statusCode}');
}
return ArticleSummary.fromJson(jsonDecode(response.body));
}
Future getArticle(String title) async {
await _simulateDelay();
final url = Uri.parse(
'$_baseUrl/api/rest_v1/page/html/${Uri.encodeComponent(title)}',
);
final response = await http.get(url);
if (response.statusCode == 404) {
throw ArticleNotFoundException(title);
} else if (response.statusCode != 200) {
throw ApiException('Failed to fetch article: ${response.statusCode}');
}
return Article.fromJson(jsonDecode(response.body));
}
Future _simulateDelay() async {
await Future.delayed(Duration(milliseconds: 200 + _random.nextInt(300)));
}
}
class ApiException implements Exception {
final String message;
ApiException(this.message);
@override
String toString() => 'ApiException: $message';
}
class ArticleNotFoundException implements Exception {
final String title;
ArticleNotFoundException(this.title);
@override
String toString() => 'Article not found: $title';
}
name: cli
description: Wiki Explorer Pro CLI.
version: 1.0.0
resolution: workspace
environment:
sdk: ^3.12.0
dependencies:
command_runner:
path: ../command_runner
wikipedia:
path: ../wikipedia
logging: ^1.2.0
import 'dart:io';
import 'package:logging/logging.dart';
Logger setupLogger(String name) {
hierarchicalLoggingEnabled = true;
final logger = Logger(name);
logger.level = Level.ALL;
final now = DateTime.now();
final dir = Directory('logs');
if (!dir.existsSync()) dir.createSync();
final logFile = File('${dir.path}/${now.year}_${now.month}_${now.day}_$name.log');
logger.onRecord.listen((record) {
final msg = '[${record.time}] ${record.level.name}: ${record.loggerName}: ${record.message}';
logFile.writeAsStringSync('$msg\n', mode: FileMode.append);
if (record.level >= Level.WARNING) print(msg);
});
return logger;
}
import 'dart:async';
import 'package:command_runner/command_runner.dart';
import 'package:wikipedia/wikipedia.dart';
import 'package:logging/logging.dart';
class SearchCommand extends Command {
final WikipediaClient client;
final Logger logger;
SearchCommand(this.client, this.logger) : super('search', 'Search Wikipedia articles') {
addOption(Option('limit', 'Max results (1-10)', isFlag: false));
}
@override
Future run(ArgResults args) async {
if (args.commandArg == null || args.commandArg!.isEmpty) {
return 'Usage: search [--limit N]';
}
int limit = int.tryParse(args.options['limit'] ?? '5') ?? 5;
limit = limit.clamp(1, 10);
logger.info('Searching for: ${args.commandArg}');
final stopwatch = Stopwatch()..start();
try {
final results = await client.search(args.commandArg!);
stopwatch.stop();
final buffer = StringBuffer('🔍 Search results for "${args.commandArg}":\n');
final display = results.take(limit).toList();
for (int i = 0; i < display.length; i++) {
buffer.writeln('${i + 1}. ${display[i].title} - ${display[i].url}');
}
buffer.writeln('✅ Search completed in ${stopwatch.elapsedMilliseconds}ms');
return buffer.toString();
} catch (e) {
logger.severe('Search failed: $e');
return '❌ Search error: $e';
}
}
}
class SummaryCommand extends Command {
final WikipediaClient client;
final Logger logger;
SummaryCommand(this.client, this.logger) : super('summary', 'Get article summary');
@override
Future run(ArgResults args) async {
if (args.commandArg == null || args.commandArg!.isEmpty) {
return 'Usage: summary ';
}
try {
final summary = await client.getSummary(args.commandArg!);
logger.info('Fetched summary for: ${summary.title}');
final buffer = StringBuffer('📖 ${summary.title}\n');
buffer.writeln('─' * 50);
buffer.writeln(summary.extract);
buffer.writeln('─' * 50);
if (summary.url != null) buffer.writeln('🔗 ${summary.url}');
return buffer.toString();
} on ArticleNotFoundException {
return '❌ Article not found: ${args.commandArg}';
} catch (e) {
logger.severe('Summary error: $e');
return '❌ Error: $e';
}
}
}
<!-- ============================================ -->
<!-- cli/lib/src/commands/compare_command.dart -->
<!-- ============================================ -->
class CompareCommand extends Command {
final WikipediaClient client;
final Logger logger;
CompareCommand(this.client, this.logger) : super('compare', 'Compare two articles');
@override
Future<String> run(ArgResults args) async {
final titles = args.commandArg?.split(',') ?? [];
if (titles.length != 2) {
return 'Usage: compare <title1>,<title2>';
}
try {
final results = await Future.wait([
client.getSummary(titles[0].trim()),
client.getSummary(titles[1].trim()),
]);
final a = results[0], b = results[1];
final buffer = StringBuffer('📊 Comparing "${a.title}" vs "${b.title}"\n');
buffer.writeln('─' * 50);
buffer.writeln('${a.title.padRight(20)} | ${b.title}');
buffer.writeln('─' * 50);
buffer.writeln('${(a.description ?? 'N/A').padRight(20)} | ${b.description ?? 'N/A'}');
buffer.writeln('Extract length: ${a.extract.length.toString().padRight(20)} | ${b.extract.length}');
return buffer.toString();
} catch (e) {
logger.severe('Compare error: $e');
return '❌ Compare error: $e';
}
}
}
<!-- ============================================ -->
<!-- cli/lib/src/commands/export_command.dart -->
<!-- ============================================ -->
import 'dart:convert';
import 'dart:io';
class ExportCommand extends Command {
final WikipediaClient client;
final Logger logger;
ExportCommand(this.client, this.logger) : super('export', 'Export article to JSON');
@override
Future<String> run(ArgResults args) async {
if (args.commandArg == null || args.commandArg!.isEmpty) {
return 'Usage: export <title>';
}
try {
final summary = await client.getSummary(args.commandArg!);
final json = jsonEncode({
'title': summary.title,
'extract': summary.extract,
'description': summary.description,
'url': summary.url,
});
final filename = '${args.commandArg!.replaceAll(' ', '_')}.json';
File(filename).writeAsStringSync(json);
logger.info('Exported to $filename');
return '✅ Exported to $filename';
} catch (e) {
logger.severe('Export error: $e');
return '❌ Export error: $e';
}
}
}
<!-- ============================================ -->
<!-- cli/bin/cli.dart (Entry Point) -->
<!-- ============================================ -->
import 'dart:io';
import 'package:cli/cli.dart';
import 'package:command_runner/command_runner.dart';
import 'package:wikipedia/wikipedia.dart';
void main(List<String> arguments) async {
final logger = setupLogger('wiki_cli');
final client = WikipediaClient();
final runner = CommandRunner()
..addCommand(SearchCommand(client, logger))
..addCommand(SummaryCommand(client, logger))
..addCommand(CompareCommand(client, logger))
..addCommand(ExportCommand(client, logger));
if (arguments.isEmpty) {
// Interactive mode
print('🏆 Wiki Explorer Pro (type "help" for commands, "exit" to quit)');
while (true) {
stdout.write('\nwiki> ');
final line = stdin.readLineSync();
if (line == null || line.trim().toLowerCase() == 'exit') break;
await runner.run(line.trim().split(' '));
}
} else {
await runner.run(arguments);
}
}
</div>
</div>
<h2>🧪 Testing Requirements</h2>
<p>Create at least these tests in the <code>wikipedia/test</code> folder:</p>
<div class="code-block">
<div class="code-header"><span class="code-lang">Dart (test/models_test.dart)</span></div>
<pre><code>import 'package:test/test.dart';
import 'package:wikipedia/wikipedia.dart';
void main() {
group('SearchResult', () {
test('fromJson parses correctly', () {
final json = {'title': 'Dart', 'url': 'https://en.wikipedia.org/wiki/Dart'};
final result = SearchResult.fromJson(json);
expect(result.title, equals('Dart'));
expect(result.url, contains('wikipedia.org'));
});
});
group('ArticleSummary', () {
test('fromJson with all fields', () {
final json = {
'title': 'Dart',
'extract': 'Dart is a programming language',
'description': 'Programming language',
'content_urls': {'desktop': {'page': 'https://en.wikipedia.org/wiki/Dart'}},
};
final summary = ArticleSummary.fromJson(json);
expect(summary.title, 'Dart');
expect(summary.description, 'Programming language');
});
test('throws FormatException on invalid JSON', () {
expect(() => ArticleSummary.fromJson({}), throwsFormatException);
});
});
}</code></pre>
</div>
<div class="info-card tip" style="margin-top:2rem;">
<div class="info-card-title">🎉 Congratulations!</div>
<p>Completing this capstone project means you can design, structure, and implement a real‑world Dart application from scratch. You've mastered packages, async programming, JSON handling, error management, logging, and testing – skills that directly transfer to Flutter and backend Dart development.</p>
</div>
<div class="lesson-navigation">
<div>
<a href="../lessons/12-logging.html" class="btn-secondary">← Back to Lesson 12</a>
</div>
<div>
<a href="../index.html" class="btn-primary">🏠 Back to Home</a>
</div>
</div>
</div>
</main>
</div>
<script src="../js/main.js"></script>
<script>
function toggleMobileMenu() {
document.getElementById('mobileMenu').classList.toggle('active');
}
</script>
</body>
</html>