From 65090b375b84c0d48272fccbc178f99cf875bd08 Mon Sep 17 00:00:00 2001 From: Chen Asraf Date: Wed, 19 Nov 2025 01:09:07 +0200 Subject: [PATCH] docs: add README.md and LICENSE --- LICENSE | 21 ++++ README.md | 365 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 386 insertions(+) create mode 100644 LICENSE create mode 100644 README.md diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..c6cb317 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright © 2025 Chen Asraf + +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. \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..d907acf --- /dev/null +++ b/README.md @@ -0,0 +1,365 @@ +# Nextcloud Deck Tools + +A collection of Python tools for interacting with Nextcloud Deck via its API. Features a unified +interactive CSV importer and standalone utilities for board and stack management. + +## Features + +- **Interactive CSV Importer** - Unified tool with guided workflow for importing tasks +- **Board Management** - Create and list boards +- **Stack Management** - Create and list stacks/columns +- **CSV Import** - Batch import tasks from CSV files +- **Flexible Authentication** - Support for environment variables, CLI arguments, and interactive + prompts +- **Both Interactive & Non-Interactive Modes** - Choose your workflow + +## Installation + +This project uses Poetry for dependency management. + +```bash +# Install dependencies +poetry install + +# Or if you already have poetry.lock +poetry install --no-root +``` + +## Quick Start + +### Interactive Mode (Recommended) + +Run the unified interactive tool: + +```bash +make +# or +poetry run python main.py +``` + +This will guide you through: + +1. Selecting or creating a board +2. Choosing which column/stack to import to +3. Selecting a CSV file +4. Confirming and importing + +### Non-Interactive Mode + +If you already know your board ID, stack ID, and CSV file: + +```bash +poetry run python main.py \ + --domain https://cloud.example.com \ + --board-id 5 \ + --stack-id 12 \ + --csv-file tasks.csv +``` + +Or use environment variables (see below) and run without arguments. + +## Environment Variables + +The tools support multiple environment variable formats for convenience: + +### Authentication & Connection + +- `NEXTCLOUD_DOMAIN` or `NEXTCLOUD_BASE_URL` - Your Nextcloud instance URL +- `NEXTCLOUD_USERNAME` or `NC_USERNAME` - Username +- `NEXTCLOUD_PASSWORD` or `NC_PASSWORD` - Password or app password + +### Board & Stack IDs + +- `NEXTCLOUD_BOARD_ID` or `BOARD_ID` - Board ID for operations +- `NEXTCLOUD_STACK_ID` or `STACK_ID` - Stack/column ID for import +- `NEXTCLOUD_BOARD_NAME` or `BOARD_NAME` - Board name when creating + +### Import Configuration + +- `IMPORT_CSV_FILE` or `CSV_FILE` - Path to CSV file +- `NEW_BOARD_COLUMNS` - Comma-separated list of column names for new boards + - Example: `NEW_BOARD_COLUMNS="Backlog,To Do,In Progress,Review,Done"` + - If not set, uses defaults: "🐞 Bugs,📋 To Do,🔄 In Progress,✅ Done,📄 Backlog" + +### Setting Up Environment Variables + +Copy `.env.example` to `.env` and fill in your values: + +```bash +export NEXTCLOUD_DOMAIN="https://cloud.example.com" +export NEXTCLOUD_USERNAME="your-username" +export NEXTCLOUD_PASSWORD="your-app-password" +export NEW_BOARD_COLUMNS="Backlog,To Do,In Progress,Done" +``` + +## CSV File Format + +CSV files should have the following format: + +```csv +title,description +"Task Title","Task description with **markdown** support" +"Another Task","Description can be multi-line and supports markdown" +``` + +**Requirements:** + +- Header row with `title` and `description` columns +- Title is required (rows without title are skipped) +- Description is optional +- Markdown formatting is supported in descriptions + +## Individual Scripts + +While `main.py` provides a unified workflow, you can still use individual scripts. + +In each script, the `.env` file may be used in place of the respective CLI arguments. + +### List Boards + +```bash +make list_boards +# or +poetry run python list_boards.py +``` + +**Options:** + +- `--domain` - Nextcloud instance URL +- `--username` - Username +- `--password` - Password +- `--json` - Output raw JSON instead of table + +### Create Board + +```bash +make create_board +# or +poetry run python create_board.py +``` + +**Options:** + +- `--domain` - Nextcloud instance URL +- `--username` - Username +- `--password` - Password +- `--board-name` - Name for the new board +- `--no-default-stacks` - Skip creating default stacks/columns + +**Environment Variables:** + +- Uses `NEW_BOARD_COLUMNS` if set, otherwise creates default stacks + +### List Stacks + +```bash +make list_stacks +# or +poetry run python list_stacks.py +``` + +**Options:** + +- `--domain` - Nextcloud instance URL +- `--board-id` - Board ID to list stacks from +- `--username` - Username +- `--password` - Password +- `--json` - Output raw JSON instead of table + +### Import CSV + +```bash +make import +# or +poetry run python import.py +``` + +**Options:** + +- `--domain` - Nextcloud instance URL +- `--board-id` - Target board ID +- `--stack-id` - Target stack/column ID +- `--username` - Username +- `--password` - Password +- `--csv-file` - Path to CSV file + +## Usage Examples + +### Example 1: Complete Interactive Workflow + +```bash +# Set up authentication once +export NEXTCLOUD_DOMAIN="https://cloud.example.com" +export NEXTCLOUD_USERNAME="john" +export NEXTCLOUD_PASSWORD="app-password-here" + +# Run interactive importer +make all +``` + +The tool will: + +1. Show existing boards and option to create new one +2. If creating new, prompt for name and use `NEW_BOARD_COLUMNS` +3. Show columns in selected/created board +4. List CSV files in current directory +5. Confirm and import + +### Example 2: Automated Import with Environment Variables + +```bash +export NEXTCLOUD_DOMAIN="https://cloud.example.com" +export NEXTCLOUD_USERNAME="john" +export NEXTCLOUD_PASSWORD="app-password" +export BOARD_ID="5" +export STACK_ID="12" +export CSV_FILE="tasks.csv" + +# Runs non-interactively +poetry run python main.py +``` + +### Example 3: Create Board with Custom Columns + +```bash +export NEXTCLOUD_DOMAIN="https://cloud.example.com" +export NEXTCLOUD_USERNAME="john" +export NEXTCLOUD_PASSWORD="app-password" +export NEW_BOARD_COLUMNS="📥 Inbox,🎯 Today,📅 This Week,✅ Done,📦 Archive" + +poetry run python create_board.py --board-name "My Project" +``` + +### Example 4: Quick Board Listing + +```bash +poetry run python list_boards.py \ + --domain https://cloud.example.com \ + --username john +# Will prompt for password securely +``` + +### Example 5: Import with All CLI Arguments + +```bash +poetry run python main.py \ + --domain https://cloud.example.com \ + --username john \ + --password app-password \ + --board-id 5 \ + --stack-id 12 \ + --csv-file ./tasks/project-tasks.csv +``` + +## Project Structure + +``` +nextcloud-deck-tools/ +├── main.py # Unified interactive CSV importer +├── create_board.py # Create boards with stacks +├── list_boards.py # List all boards +├── list_stacks.py # List stacks for a board +├── import.py # Import CSV to specific stack +├── common.py # Shared utilities and functions +├── Makefile # Task shortcuts +├── pyproject.toml # Poetry dependencies +└── README.md # This file +``` + +## Makefile Targets + +- `make all` - Run the unified interactive importer (default) +- `make create_board` - Create a new board +- `make list_boards` - List all boards +- `make list_stacks` - List stacks for a board +- `make import` - Import CSV to a stack + +## Authentication + +For security, it's recommended to use Nextcloud **app passwords** instead of your main account +password: + +1. Go to Nextcloud Settings → Security +2. Create a new app password +3. Use that password in `NEXTCLOUD_PASSWORD` or `--password` + +Passwords can be: + +- Set in environment variables (convenient but less secure) +- Passed via CLI arguments (visible in shell history) +- Entered interactively when prompted (most secure, uses hidden input) + +## Resolution Priority + +When multiple input methods are available, the tools use this priority: + +1. **Environment variables** - Checked first +2. **CLI arguments** - Override environment variables +3. **Interactive prompts** - Final fallback if nothing else provided + +This allows flexible workflows: set common values in ENV, override specific values with CLI args, or +use fully interactive mode. + +## Requirements + +- Python 3.11+ +- Poetry +- Nextcloud instance with Deck app installed +- Valid Nextcloud account credentials + +## Dependencies + +- `requests` - HTTP client for API calls +- `inquirer` - Interactive CLI prompts (for main.py) + +## License + +This project is licensed under the [MIT License](LICENSE). + +## Contributing + +I am developing this package on my free time, so any support, whether code, issues, or just stars is +very helpful to sustaining its life. If you are feeling incredibly generous and would like to donate +just a small amount to help sustain this project, I would be very very thankful! + + + Buy Me a Coffee at ko-fi.com + + +I welcome any issues or pull requests on GitHub. If you find a bug, or would like a new feature, +don't hesitate to open an appropriate issue and I will do my best to reply promptly. + +## Tips + +- Use `--json` flag with list commands to pipe output to `jq` or other tools +- Store credentials in `.envrc` and use `direnv` for automatic loading +- Create different `.envrc` files for different Nextcloud instances +- CSV files support markdown in descriptions - great for formatted task details +- All scripts support `--help` for detailed usage information + +## Troubleshooting + +**Authentication fails:** + +- Verify your Nextcloud URL includes the protocol (`https://`) +- Check that your username/password are correct +- Consider using an app password instead of account password + +**Board/Stack not found:** + +- Use `list_boards.py` and `list_stacks.py` to find correct IDs +- Board and stack IDs are integers, not names + +**CSV import skips rows:** + +- Ensure CSV has `title` and `description` header row +- Check that titles are not empty +- Verify file encoding is UTF-8 + +**Interactive mode not working:** + +- Ensure `inquirer` is installed: `poetry install` +- Check terminal supports interactive input (some CI environments don't) +- Try non-interactive mode with full CLI arguments instead