From 211d46cd62ce4f63c7a1d4bf09d5488412e687f0 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 30 Apr 2026 14:35:37 +0000 Subject: [PATCH 1/2] Initial plan From 62e2a70ca298367284951129e5502b36d2e33133 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 30 Apr 2026 14:39:24 +0000 Subject: [PATCH 2/2] docs: Update README with Phase 1 CLI and Phase 2 API usage labels Agent-Logs-Url: https://github.com/ShockaHolmes/NoteForge/sessions/2bf0a9a5-6952-4a25-b670-331e4244f788 Co-authored-by: ShockaHolmes <78627489+ShockaHolmes@users.noreply.github.com> --- README.md | 189 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 157 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index c49e045..6b6841b 100644 --- a/README.md +++ b/README.md @@ -150,6 +150,46 @@ There a few sample note files in [test-notes/](./test-notes) ## Phase 1: CLI Implementation +### Running the CLI + +All CLI commands are run from the `python/` directory using the package-based entry point. +The notes directory (`~/.notes/notes/`) is created automatically on first run. + +```bash +# Navigate to the Python implementation directory +cd python + +# Display help +PYTHONPATH=src python3 -m notes_app.cli.main help + +# Create a new note +PYTHONPATH=src python3 -m notes_app.cli.main create "My First Note" "This is the note content." + +# List all notes +PYTHONPATH=src python3 -m notes_app.cli.main list + +# Read a specific note (replace with the ID shown in the list output) +PYTHONPATH=src python3 -m notes_app.cli.main read + +# Update a note's title, tags, or content +PYTHONPATH=src python3 -m notes_app.cli.main update --title "Updated Title" +PYTHONPATH=src python3 -m notes_app.cli.main update --tags "work,important" +PYTHONPATH=src python3 -m notes_app.cli.main update --content "Revised content here." + +# Delete a note +PYTHONPATH=src python3 -m notes_app.cli.main delete + +# Search notes by keyword (searches title, tags, and body) +PYTHONPATH=src python3 -m notes_app.cli.main search "keyword" +``` + +**PROTIP:** Seed your notes directory with the sample notes to have something to work with right away: + +```bash +mkdir -p ~/.notes/notes +cp test-notes/*.md ~/.notes/notes/ +``` + ### Command Reference These commands can all be run from "anywhere" in your file system, and they are manipulating @@ -170,15 +210,6 @@ notes search "query" # Search notes for text (title, tags, content) notes stats # Display statistics about your notes ``` -And PROTIP: You might want to - -``` -mkdir -p ~/.notes/notes -cp test-notes/*.md ~/.notes/notes/ -``` - -So you have some notes to play with right away, and to test your search and listing features. - ### Technical Requirements - Java 11+ or Python 3.11+ @@ -187,31 +218,121 @@ So you have some notes to play with right away, and to test your search and list - Text editor integration (nano?) - Extra Credit: github integration for the notes storage - Extra Credit: note encryption (and key management) - + ## Phase 2: REST Server Implementation Maybe instead of Phase 2? Maybe this week, maybe in the future. What is this stuff anyway? Well, Ask your friendly, globe-girdling AI. +### Starting the API Server + +```bash +# Navigate to the Python implementation directory +cd python + +# Install dependencies (FastAPI + Uvicorn) +pip install fastapi uvicorn pyyaml + +# Start the API server (auto-reloads on code changes) +PYTHONPATH=src uvicorn notes_app.api.app:app --reload --port 8000 +``` + +Once running, visit: +- **Interactive docs (Swagger UI):** http://localhost:8000/docs +- **Alternative docs (ReDoc):** http://localhost:8000/redoc +- **Health check:** http://localhost:8000/health + +### Managing Notes via the API + +```bash +# List all notes +curl http://localhost:8000/api/notes + +# Create a note +curl -X POST http://localhost:8000/api/notes \ + -H "Content-Type: application/json" \ + -d '{"title": "My API Note", "content": "Hello from the API.", "tags": ["example", "api"]}' + +# Read a specific note (replace with the ID returned from create/list) +curl http://localhost:8000/api/notes/ + +# Update a note (PATCH supports partial updates) +curl -X PATCH http://localhost:8000/api/notes/ \ + -H "Content-Type: application/json" \ + -d '{"title": "Updated Title", "tags": ["updated"]}' + +# Replace a note fully (PUT) +curl -X PUT http://localhost:8000/api/notes/ \ + -H "Content-Type: application/json" \ + -d '{"title": "Replaced Note", "content": "Completely new content.", "tags": []}' + +# Delete a note +curl -X DELETE http://localhost:8000/api/notes/ + +# Search notes by keyword +curl "http://localhost:8000/api/search?q=example" +``` + +### Uploading and Managing Datasets via the API + +Datasets (CSV or JSON files) are uploaded via multipart form-data and stored in `~/.notes/datasets/`. +Each upload automatically creates a sidecar YAML metadata file alongside the data file. + +```bash +# Upload a CSV dataset +curl -X POST http://localhost:8000/api/datasets \ + -F "title=Sales Q1 2026" \ + -F "author=Zip Coder" \ + -F "tags=sales,finance,quarterly" \ + -F "file=@sales-2026-q1.csv" + +# Upload a JSON dataset +curl -X POST http://localhost:8000/api/datasets \ + -F "title=Customer Events" \ + -F "author=Zip Coder" \ + -F "tags=events,customers" \ + -F "file=@customer-events.json" + +# List all datasets +curl http://localhost:8000/api/datasets + +# Get dataset metadata +curl http://localhost:8000/api/datasets/ + +# Preview the first N rows of a dataset +curl "http://localhost:8000/api/datasets//preview?limit=10" + +# Profile a dataset (column stats, inferred types, null counts) +curl http://localhost:8000/api/datasets//profile + +# Update dataset metadata (title, tags, status, priority) +curl -X PATCH http://localhost:8000/api/datasets/ \ + -H "Content-Type: application/json" \ + -d '{"title": "Sales Q1 2026 (Revised)", "tags": ["sales", "finance"]}' + +# Delete a dataset and its sidecar metadata +curl -X DELETE http://localhost:8000/api/datasets/ +``` + ### API Endpoints ``` -GET /api/notes # List all notes -POST /api/notes # Create a new note -GET /api/notes/:id # Retrieve a specific note -PUT /api/notes/:id # Update a specific note -DELETE /api/notes/:id # Delete a specific note -GET /api/tags # List all tags -GET /api/notes/tag/:tagid # List all notes with tag tagid -GET /api/search?q=query # Search notes and datasets - -GET /api/datasets # List datasets -POST /api/datasets # Upload dataset (CSV/JSON) -GET /api/datasets/:id # Retrieve dataset metadata -DELETE /api/datasets/:id # Delete dataset and sidecar metadata -GET /api/datasets/:id/preview # Preview first N rows -GET /api/datasets/:id/profile # Column stats, inferred types, null counts +GET /api/notes # List all notes +POST /api/notes # Create a new note +GET /api/notes/:id # Retrieve a specific note +PUT /api/notes/:id # Replace a specific note +PATCH /api/notes/:id # Partially update a specific note +DELETE /api/notes/:id # Delete a specific note +GET /api/search?q=query # Search notes and datasets + +GET /api/datasets # List datasets +POST /api/datasets # Upload dataset (CSV/JSON) +GET /api/datasets/:id # Retrieve dataset metadata +PATCH /api/datasets/:id # Update dataset metadata +DELETE /api/datasets/:id # Delete dataset and sidecar metadata +GET /api/datasets/:id/preview # Preview first N rows +GET /api/datasets/:id/profile # Column stats, inferred types, null counts ``` ### Phase 2 Integration Notes @@ -271,23 +392,27 @@ Students will gain experience with: ### Prerequisites -- [List required software/libraries] +- Python 3.11+ (for the Python implementation) +- Java 11+ (for the Java implementation) +- `pip` for installing Python dependencies - Basic understanding of Java or Python -- Knowledge of [relevant concepts] ### Installation ```bash # Clone the repository # CHOOSE your Project's Name NOW.... _don't use future-proof_. **See Below for Suggested Names** -git clone https://github.com/yourusername/future-proof.git `yournotesnamehere` +git clone https://github.com/yourusername/future-proof.git yournotesnamehere -# Navigate to the project directory or whatever you named it in the clone. -cd `yournotesnamehere` +# Navigate to the project directory +cd yournotesnamehere -# Install dependencies -(if you need them) +# (Python) Install dependencies +pip install fastapi uvicorn pyyaml +# Seed your notes directory with the sample notes so you have something to work with +mkdir -p ~/.notes/notes +cp test-notes/*.md ~/.notes/notes/ ``` ## Lab notes