# Story 1.1: Repository Setup and Project Structure

## Status

Ready for Review

## Story

**As a** developer,
**I want** a properly structured Python project with minimal dependencies,
**so that** I can build and distribute the NUU Core CLI tool

## Acceptance Criteria

1. Python project structure follows modern best practices (pyproject.toml based)
2. Minimal dependencies installed (typer, pyperclip, pyyaml)
3. Basic CLI entry point that prints version
4. README with installation instructions
5. .gitignore for Python projects
6. MIT License file

## Tasks / Subtasks

- [x] Initialize Python project structure (AC: 1)
  - [x] Create pyproject.toml with project metadata
  - [x] Set up nuu package directory with **init**.py
  - [x] Configure Python 3.11+ requirement
  - [x] Add [project.scripts] entry point for CLI
- [x] Install and configure dependencies (AC: 2)
  - [x] Add typer ~= 0.12.0 to dependencies
  - [x] Add pyperclip ~= 1.8.2 to dependencies
  - [x] Add pyyaml ~= 6.0 to dependencies
  - [x] Add development dependencies (ruff, pyright, pytest)
  - [x] Run uv sync to create lock file
- [x] Create basic CLI entry point (AC: 3)
  - [x] Create nuu/cli.py with typer app
  - [x] Create nuu/**main**.py for python -m nuu execution
  - [x] Add version command that prints "nuu version 0.1.0"
  - [x] Verify CLI runs with both `nuu` and `python -m nuu`
- [x] Create project documentation (AC: 4, 5, 6)
  - [x] Write README.md with installation and usage instructions
  - [x] Create .gitignore from Python template
  - [x] Add MIT LICENSE file
  - [x] Create docs/ directory structure

## Dev Notes

### Project Structure

Based on [Source: architecture/unified-project-structure.md]:

- Main package directory: `nuu/`
- Entry points: `nuu/__main__.py` and `nuu/cli.py`
- Test directory: `tests/` with pytest
- Documentation: `docs/` with subdirectories for architecture, prd, stories

### Technology Stack

Based on [Source: architecture/tech-stack.md]:

- **Python 3.11+** with type hints
- **typer** for CLI framework (modern, type-hint based)
- **pyperclip** for clipboard operations
- **pyyaml** for future configuration support
- **uv** as package manager (fast, deterministic)
- **ruff** for linting/formatting
- **pyright** for type checking
- **pytest** for testing

### File Locations

```
nuu-core/
├── nuu/
│   ├── __init__.py      # Package marker, exports version
│   ├── __main__.py      # Entry point for python -m nuu
│   └── cli.py          # Typer app and command definitions
├── tests/
│   └── __init__.py     # Test package marker
├── .gitignore         # Python gitignore template
├── LICENSE           # MIT License text
├── README.md        # Installation and usage guide
├── pyproject.toml  # Project configuration
└── uv.lock        # Lock file (generated)
```

### pyproject.toml Structure

```toml
[project]
name = "nuu-core"
version = "0.1.0"
description = "A CLI tool for fetching markdown content with linked documents"
readme = "README.md"
requires-python = ">= 3.11"
dependencies = [
    "typer~=0.12.0",
    "pyperclip~=1.8.2",
    "pyyaml~=6.0",
]

[project.scripts]
nuu = "nuu.cli:app"

[tool.uv]
dev-dependencies = [
    "ruff~=0.7.0",
    "pyright~=1.1.0",
    "pytest~=8.0.0",
]
```

### Testing

Based on [Source: architecture/coding-standards.md#testing-standards]:

- Test file location: `tests/` directory
- Use pytest framework
- Minimum 80% code coverage target
- Test files prefix with `test_`
- Use fixtures in `tests/fixtures/` for test markdown files

## Change Log

| Date       | Version | Description            | Author       |
| ---------- | ------- | ---------------------- | ------------ |
| 2025-01-30 | 1.0     | Initial story creation | Scrum Master |

## Dev Agent Record

### Agent Model Used

claude-opus-4-20250514

### Debug Log References

No debug log entries required - all implementations successful.

### Completion Notes List

- Successfully created Python project structure with pyproject.toml
- Installed all dependencies using uv package manager
- Created CLI with typer supporting both `nuu version` and `--version` flag
- Added comprehensive tests for all functionality
- Created documentation files (README.md, LICENSE, .gitignore)
- All tests passing (14 tests)
- All linting and type checking passing

### File List

- pyproject.toml (created)
- nuu/__init__.py (created)
- nuu/__main__.py (created)
- nuu/cli.py (created)
- tests/__init__.py (created)
- tests/test_init.py (created)
- tests/test_dependencies.py (created)
- tests/test_cli.py (created)
- tests/test_project_files.py (created)
- README.md (modified)
- LICENSE (created)
- .gitignore (created)
- uv.lock (created by uv)

## QA Results

_To be filled by QA agent_
