learnchain 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 David Norman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,126 @@
+# LearnChain
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**LearnChain** is a terminal-based learning tool that helps you learn to code while using generative AI to build projects. It analyzes your Codex or Claude session logs and surfaces interactive quizzes in a beautiful terminal UI, reinforcing concepts as you work.
+
+## Features
+
+- **Session Log Analysis**: Parse and learn from your AI-assisted coding sessions
+- **Quiz Generation**: AI-powered quiz creation based on your actual coding patterns
+- **Configuration Management**: Persistent settings stored in `config/app_config.toml`
+- **Multi-platform Support**: Distributed via npm for easy installation across platforms
+- **Interactive TUI**: Built with [Ratatui](https://ratatui.rs) for a polished terminal experience
+
+## Installation
+
+### Via npm (Recommended)
+
+```bash
+npm install -g learnchain
+npx learnchain --help
+```
+
+### From Source
+
+```bash
+git clone https://github.com/yourusername/learnchain.git
+cd learnchain
+cargo build --release
+./target/release/learnchain
+```
+
+## Quick Start
+
+1. **Configure your OpenAI API key** (required for quiz generation):
+   ```bash
+   npx learnchain --set-openai-key sk-...
+   ```
+
+   Or configure it directly in the TUI: Config view → "OpenAI API key" → press Enter to edit
+
+2. **Launch the terminal UI**:
+   ```bash
+   cargo run
+   # or if installed via npm:
+   npx learnchain
+   ```
+
+3. Navigate the menu to load session logs, configure defaults, and start learning!
+
+## Development
+
+### Prerequisites
+
+- Rust (edition 2024)
+- Node.js >= 16 (for npm distribution)
+- Cargo
+
+### Build Commands
+
+```bash
+# Compile the TUI
+cargo build
+
+# Run the application
+cargo run
+
+# Run tests with output
+cargo test -- --nocapture
+
+# Format and lint
+cargo fmt
+cargo clippy --all-targets --all-features
+
+# Build release binary for npm distribution
+npm run build
+```
+
+### Project Structure
+
+```
+learnchain/
+├── src/
+│   ├── main.rs              # Entry point and app state
+│   ├── ai_manager.rs        # AI/LLM integration
+│   ├── config.rs            # Configuration management
+│   ├── session_manager.rs   # AI coding tool (Claude/Codex) log processing
+│   ├── ui_renderer.rs       # Terminal UI rendering
+│   └── view_managers/       # View-specific logic
+├── config/                  # Runtime configuration
+├── test_fixtures/           # Test fixtures
+├── scripts/                 # Build and install helpers
+└── dist/                    # npm distribution files
+```
+
+See [AGENTS.md](AGENTS.md) for detailed development guidelines.
+
+## Configuration
+
+LearnChain stores configuration in `config/app_config.toml`. Key settings include:
+
+- OpenAI API key (required for quiz generation)
+- Default session log paths
+- UI preferences
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+See [AGENTS.md](AGENTS.md) for coding standards and testing guidelines.
+
+## License
+
+Copyright (c) Dave Norman <david.norman.w@gmail.com>
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Acknowledgments
+
+- Built with [Ratatui](https://ratatui.rs) - Rust TUI framework

package/dist/learnchain.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const platform = process.platform;
+const arch = process.arch;
+
+// Map Node.js platform/arch to binary names
+const getBinaryName = () => {
+  const platformMap = {
+    'darwin': 'darwin',
+    'linux': 'linux',
+    'win32': 'win32'
+  };
+
+  const archMap = {
+    'arm64': 'arm64',
+    'x64': 'x64'
+  };
+
+  const mappedPlatform = platformMap[platform];
+  const mappedArch = archMap[arch];
+
+  if (!mappedPlatform || !mappedArch) {
+    console.error(`Unsupported platform: ${platform}-${arch}`);
+    console.error('Supported: macOS (arm64/x64), Linux (x64), Windows (x64)');
+    process.exit(1);
+  }
+
+  const ext = platform === 'win32' ? '.exe' : '';
+  return `learnchain-${mappedPlatform}-${mappedArch}${ext}`;
+};
+
+const binaryName = getBinaryName();
+const binPath = path.join(__dirname, binaryName);
+
+if (!fs.existsSync(binPath)) {
+  console.error(`Binary not found for your platform: ${binaryName}`);
+  console.error(`Expected at: ${binPath}`);
+  console.error(`\nYour platform: ${platform}-${arch}`);
+  console.error('Supported platforms: darwin-arm64, darwin-x64, linux-x64, win32-x64');
+  process.exit(1);
+}
+
+// Spawn the binary with all arguments
+const child = spawn(binPath, process.argv.slice(2), { stdio: 'inherit' });
+child.on('close', (code) => process.exit(code ?? 0));

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "learnchain",
+  "version": "0.1.0",
+  "description": "Terminal-based learning tool that analyzes AI coding sessions and generates interactive quizzes",
+  "license": "MIT",
+  "author": "Dave Norman <david.norman.w@gmail.com>",
+  "bin": {
+    "learnchain": "dist/learnchain.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/normand1/learnchain"
+  },
+  "scripts": {
+    "build": "cargo build --release",
+    "build:all": "echo 'Use GitHub Actions workflow to build all platform binaries'",
+    "postinstall": "node scripts/install.js",
+    "prepublishOnly": "node scripts/generate-launcher.js"
+  },
+  "files": [
+    "dist/",
+    "scripts/install.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "learnchain",
+    "tui",
+    "terminal",
+    "cli",
+    "learning",
+    "quiz",
+    "ai",
+    "codex",
+    "claude",
+    "education",
+    "rust"
+  ],
+  "engines": {
+    "node": ">=16"
+  }
+}

package/scripts/install.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+const { existsSync, chmodSync } = require('fs');
+const path = require('path');
+
+const projectRoot = path.join(__dirname, '..');
+const platform = process.platform;
+const arch = process.arch;
+
+// Map Node.js platform/arch to our binary naming convention
+const getBinaryName = () => {
+  const platformMap = {
+    'darwin': 'darwin',
+    'linux': 'linux',
+    'win32': 'win32'
+  };
+
+  const archMap = {
+    'arm64': 'arm64',
+    'x64': 'x64'
+  };
+
+  const mappedPlatform = platformMap[platform];
+  const mappedArch = archMap[arch];
+
+  if (!mappedPlatform || !mappedArch) {
+    console.error(`Unsupported platform: ${platform}-${arch}`);
+    console.error('Supported platforms: macOS (arm64/x64), Linux (x64), Windows (x64)');
+    process.exit(1);
+  }
+
+  const ext = platform === 'win32' ? '.exe' : '';
+  return `learnchain-${mappedPlatform}-${mappedArch}${ext}`;
+};
+
+const binaryName = getBinaryName();
+const binaryPath = path.join(projectRoot, 'dist', binaryName);
+
+// Verify the pre-compiled binary exists
+if (!existsSync(binaryPath)) {
+  console.error(`Pre-compiled binary not found: ${binaryName}`);
+  console.error(`Expected at: ${binaryPath}`);
+  console.error('\nThis might mean:');
+  console.error('1. Your platform is not supported');
+  console.error('2. The package was not built correctly');
+  console.error(`\nSupported: darwin-arm64, darwin-x64, linux-x64, win32-x64`);
+  console.error(`Your platform: ${platform}-${arch}`);
+  process.exit(1);
+}
+
+// Make binary executable (Unix systems)
+if (platform !== 'win32') {
+  try {
+    chmodSync(binaryPath, 0o755);
+  } catch (err) {
+    console.warn(`Warning: Could not make binary executable: ${err.message}`);
+  }
+}
+
+console.log(`✓ learnchain installed successfully for ${platform}-${arch}`);
+console.log('\nRun: npx learnchain --help');
+console.log('Tip: Run `npx learnchain --set-openai-key <your-key>` to configure your OpenAI API key.');