Metadata-Version: 2.4
Name: zotero-project-manager
Version: 0.5.0
Summary: Export Zotero collections into clean, incremental research workspaces.
Project-URL: Homepage, https://github.com/sbilmis/zotero-project-manager
Project-URL: Documentation, https://github.com/sbilmis/zotero-project-manager#readme
Project-URL: Issues, https://github.com/sbilmis/zotero-project-manager/issues
Project-URL: Changelog, https://github.com/sbilmis/zotero-project-manager/blob/main/CHANGELOG.md
Author: Zotero Project Manager contributors
License: MIT License
        
        Copyright (c) 2026 Zotero Project Manager contributors
        
        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.
License-File: LICENSE
Keywords: cli,pdf,research,zotero
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: typer<1,>=0.12
Provides-Extra: dev
Requires-Dist: pytest<9,>=8; extra == 'dev'
Description-Content-Type: text/markdown

# Zotero Project Manager (`zpm`)

`zpm` creates clean, ordinary project folders from Zotero collections. Zotero
remains the source of truth; `zpm` only reads its database and attachments and
writes into a separate output directory.

The current release supports recursive collection export, multiple collections,
portable metadata-based filenames, incremental updates, SHA-256 verification,
safe pruning, DOI/tag metadata, Markdown indexes, dry runs, diagnostics, and a
versioned JSON manifest.

## Quick start: export `My-AI`

On this Mac, `zpm` is installed as a user-local command and can be run from any
directory. Export `My-AI` with:

```bash
zpm export "My-AI" --output ~/ResearchProjects
```

The files are written to:

```text
~/ResearchProjects/My-AI/
```

Preview the export without writing anything:

```bash
zpm export "My-AI" --output ~/ResearchProjects --dry-run --verbose
```

Run the same `zpm export` command whenever the Zotero collection changes. The
manifest makes the update incremental: new or changed PDFs are copied and
unchanged PDFs are left alone.

Inspect changes without writing anything:

```bash
zpm status "My-AI" --output ~/ResearchProjects
```

Preview files removed from Zotero that can be safely pruned:

```bash
zpm status "My-AI" --output ~/ResearchProjects --prune
```

After reviewing the preview, apply safe pruning:

```bash
zpm export "My-AI" --output ~/ResearchProjects --prune
```

Only manifest-owned files whose SHA-256 still matches are deleted. Files changed
outside `zpm`, files without a trusted hash, and unsafe paths are protected.

Other useful global commands:

```bash
zpm list
zpm doctor --output ~/ResearchProjects
zpm export --help
zpm --version
```

## Configuration and named projects

Set global defaults once:

```bash
zpm config set --zotero-dir ~/Zotero --output ~/ResearchProjects
zpm config show
```

The default configuration file is `~/.config/zpm/config.toml`. Override it with
the global `--config PATH` option or the `ZPM_CONFIG` environment variable.

Create a named project from one or more collections:

```bash
zpm project add ai "My-AI" "Claude"
zpm project list
zpm project show ai
```

Synchronize it from any directory:

```bash
zpm sync ai
zpm sync ai --dry-run
```

A named project can save recursive traversal, non-PDF inclusion, pruning, full
hash verification, metadata generation, and its own output directory. Use `--force` with
`zpm project add` to replace an existing project definition.

## Metadata and research index

Exports generate two additional workspace files by default:

- `metadata.json` contains collection keys, Zotero item and attachment keys,
  titles, dates, creators, DOI, tags, source and destination paths, state, and SHA-256.
- `INDEX.md` provides a human-readable table with DOI links and relative PDF links.

Disable these generated artifacts when needed:

```bash
zpm export "My-AI" --output ~/ResearchProjects --no-metadata
```

For safety, `zpm` refuses to overwrite an existing `metadata.json` or `INDEX.md`
unless that file was previously generated by `zpm`.

## Safety model

- The Zotero database is opened with SQLite `mode=ro` and `PRAGMA query_only`.
- Queries run in a consistent read-only SQLite transaction. Optional
  `--snapshot` mode uses the SQLite backup API when an isolated copy is useful.
- `zpm` never renames, moves, or edits Zotero files.
- Output paths inside the Zotero data directory are rejected.
- Existing directories without a `zpm` manifest are rejected unless explicitly
  adopted with `--overwrite`.

Always keep independent backups of important research data.

## Requirements and installation

- Python 3.11 or newer

Install the current GitHub release globally with `pipx`:

```bash
brew install pipx
pipx install git+https://github.com/sbilmis/zotero-project-manager.git
```

After the first PyPI release is published, the shorter command is:

```bash
pipx install zotero-project-manager
```

Upgrade an existing `pipx` installation with:

```bash
pipx upgrade zotero-project-manager
```

Install from a checkout:

```bash
python -m pip install .
```

For development:

```bash
python -m pip install -e '.[dev]'
pytest
```

## Usage

### Optional shell helpers

For a checkout at `~/zotero-collection-mirror`, create its environment once:

```bash
cd ~/zotero-collection-mirror
python -m venv .venv
.venv/bin/pip install -e .
```

Load the convenience functions in the current shell:

```bash
source ~/zotero-collection-mirror/scripts/zpm-helper.sh
```

Then use:

```bash
zpm_collections
zpm_my_ai
zpm_export "My-AI" "Claude"
zpm_export "My-AI" --dry-run --verbose
```

The helpers default to `~/Zotero` and `~/ResearchProjects`. Override these
locations before sourcing the file when needed:

```bash
export ZPM_ZOTERO_DIR="/path/to/Zotero"
export ZPM_OUTPUT_DIR="/path/to/ResearchProjects"
source ~/zotero-collection-mirror/scripts/zpm-helper.sh
```

List collections, including the keys needed to disambiguate duplicate names:

```bash
zpm list
zpm list --zotero-dir ~/Zotero
```

Export one collection to the current directory:

```bash
zpm export "My-AI"
```

Export several collections beneath a chosen parent directory:

```bash
zpm export "My-AI" "Claude" "Image_Processing" --output ~/ResearchProjects
```

Useful options:

```text
--recursive / --no-recursive       Include descendants (default: recursive)
--pdf-only / --include-non-pdf     Attachment filter (default: PDF only)
--dry-run                          Show counts without writing
--prune                            Safely remove hash-verified stale exports
--verify                           Fully recompute source and destination hashes
--metadata / --no-metadata        Enable or disable metadata and index generation
--overwrite                        Adopt an unmanaged destination
--verbose                          Enable diagnostic messages
--linked-attachment-base-dir PATH  Resolve Zotero relative linked files
--snapshot                         Query an isolated temporary database copy
```

Collection selectors are matched first by exact Zotero key, then by
case-insensitive full collection name. Ambiguous names produce an error listing
the usable keys.

## Incremental behavior

Each workspace contains `manifest.json` and `README.md`. On later runs, `zpm`
uses recorded source and destination metadata plus SHA-256 digests to:

- leave unchanged files alone;
- replace changed managed files;
- copy newly discovered files;
- report missing source attachments without deleting an earlier export.
- reconcile identical files re-added under a new Zotero attachment key;
- track files removed from the collection until they are safely pruned.

`--overwrite` is not needed for normal updates. It is the explicit opt-in for
adopting an existing directory or replacing an unmanaged filename conflict.
Use `--verify` for a full content audit even when file metadata appears unchanged.

Manifest v1 workspaces are read automatically. The next successful export adds
hashes and upgrades the manifest to v2; `status` and `--dry-run` never rewrite it.

## Troubleshooting

### Zotero database is locked

Zotero can normally remain open because `zpm` uses read-only SQLite access and
waits briefly for transient locks. An export may still be blocked while Zotero
is syncing, upgrading its database, or performing maintenance.

If `zpm` reports that the database is locked:

1. Wait for Zotero synchronization or maintenance to finish, then retry.
2. If it remains locked, close Zotero completely and run the command again.
3. Use `zpm doctor --output ~/ResearchProjects` to check the configuration.

`zpm` does not modify Zotero when a lock occurs. A lock error happens before the
collection can be read or any export changes are applied.

## Attachment paths

Stored Zotero attachments (`storage:...`), absolute linked paths, and `file://`
paths are resolved automatically. Zotero's `attachments:...` relative paths
require `--linked-attachment-base-dir` because that preference is not stored in
`zotero.sqlite`.

## Development layout

```text
src/zotero_project_manager/
    cli.py          CLI parsing and presentation
    zotero.py       read-only SQLite and attachment path resolution
    collections.py hierarchy, lookup, and traversal
    exporter.py     safe incremental export orchestration
    filenames.py    portable filename generation and collisions
    manifest.py     versioned manifest serialization
    metadata.py     JSON metadata and Markdown research indexes
    models.py       shared domain dataclasses
    diagnostics.py  read-only doctor checks
    config.py       TOML defaults and named projects
    utils.py        logging and path safety helpers
```

## Non-goals for v0.2

Better BibTeX, annotation export, DEVONthink or NotebookLM automation, watch mode,
a GUI, and symlink mode are not implemented yet.
