Metadata-Version: 2.4
Name: dossier-tools
Version: 0.1.4
Summary: Frontmatter schema, signing, and validation tools for .ds.md workflow files
Project-URL: Homepage, https://github.com/liberioai/dossier-tools
Project-URL: Repository, https://github.com/liberioai/dossier-tools
Project-URL: Issues, https://github.com/liberioai/dossier-tools/issues
Author-email: Liberio AI <team@liberio.ai>
License: MIT License
        
        Copyright (c) 2025 Liberio AI
        
        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
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: click>=8.0.0
Requires-Dist: cryptography>=42.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: jsonschema>=4.0.0
Requires-Dist: python-frontmatter>=1.0.0
Provides-Extra: dev
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: respx>=0.21.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# dossier-tools

**CLI and library for validating, signing, and running Dossier workflow files (`.ds.md`).**

## What is a Dossier?

A **Dossier** is a markdown file with structured frontmatter that AI agents can execute. Think of it as a recipe for automation—clear instructions that LLMs like Claude Code can follow intelligently.

**Why use Dossiers instead of scripts?**
- **Adaptive**: LLMs understand context and handle edge cases naturally
- **Portable**: Same dossier works across different projects and environments
- **Verifiable**: Built-in checksums and signatures ensure integrity
- **Human-readable**: Plain markdown that anyone can read and modify

```markdown
---
schema_version: "1.0.0"
title: Setup Development Environment
version: "1.0.0"
status: stable
objective: Configure dev environment with proper tooling
authors:
  - name: Alice
checksum:
  algorithm: sha256
  hash: a3b5c8d9...
---

# Setup Development Environment

## Objective
Configure a development environment with linting, testing, and git hooks.

## Steps
1. Detect project type (Node.js, Python, etc.)
2. Install appropriate dev dependencies
3. Configure pre-commit hooks
4. Verify setup works

## Validation
- All linters pass
- Tests run successfully
- Git hooks are installed
```

📖 **Learn more**: [What is a Dossier?](./docs/what-is-a-dossier.md)

## Installation

```bash
pip install dossier-tools
```

Or with uv:

```bash
uv add dossier-tools
```

## Quick Start

### Run a Dossier from the Registry

```bash
# Run a workflow (starts interactive Claude Code session)
dossier run myorg/setup-dev

# Preview without executing
dossier run myorg/setup-dev --print-only
```

> **Note**: Currently only [Claude Code](https://claude.ai/code) is supported as an execution agent.

### Create a New Dossier

```bash
# Create with AI assistance (interactive)
dossier new

# Or from an existing markdown file
dossier from-file workflow.md \
  --name "my-workflow" \
  --title "My Workflow" \
  --objective "Automate something useful" \
  --author "you"
```

### Sign and Verify

```bash
# Initialize and generate signing keys
dossier init
dossier generate-keys

# Validate and sign
dossier validate workflow.ds.md
dossier sign workflow.ds.md --signed-by "you"
dossier verify workflow.ds.md
```

## Registry

Browse and download dossiers from the public registry:

```bash
# List available dossiers
dossier list

# Get metadata
dossier get myorg/deploy

# Download locally
dossier pull myorg/deploy
```

Publish your own (requires GitHub authentication):

```bash
dossier login
dossier publish workflow.ds.md --namespace myorg/tools
```

## Commands

| Command | Description |
|---------|-------------|
| `new` | Create a new dossier with AI assistance |
| `run` | Pull and execute a dossier with Claude Code |
| `from-file` | Create a dossier from an existing markdown file |
| `validate` | Validate frontmatter schema |
| `checksum` | Verify or update checksum |
| `sign` | Sign a dossier |
| `verify` | Verify checksum and signature |
| `list` | List dossiers from the registry |
| `pull` | Download a dossier |
| `get` | Get dossier metadata |
| `publish` | Publish to the registry |
| `login` / `logout` | Manage authentication |

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `DOSSIER_REGISTRY_URL` | Registry API URL | `https://dossier-registry-mvp-ten.vercel.app` |
| `DOSSIER_SIGNING_KEY` | Default signing key name | `default` |
| `DOSSIER_LOG_LEVEL` | Log level (DEBUG, INFO, WARNING, ERROR) | `WARNING` |

## Documentation

- [What is a Dossier?](./docs/what-is-a-dossier.md) — Concept, use cases, and comparisons
- [CLI Reference](./docs/cli.md) — All commands and options
- [Python API](./docs/api.md) — Using dossier-tools as a library
- [Schema Reference](./docs/schema.md) — Frontmatter field reference
- [Signing Guide](./docs/signing.md) — Signing and verification workflow

## Development

```bash
git clone https://github.com/liberioai/dossier-tools.git
cd dossier-tools
make setup    # Install dependencies
make test     # Run tests
make format   # Format code
```

## License

MIT
