Metadata-Version: 2.4
Name: freshstate
Version: 0.2.1
Summary: Keep your AI workspace docs fresh. Track document freshness, enforce cross-file consistency, and prevent stale docs in AI-assisted codebases.
Project-URL: Homepage, https://github.com/sly-the-fox/freshstate
Project-URL: Repository, https://github.com/sly-the-fox/freshstate
Project-URL: Issues, https://github.com/sly-the-fox/freshstate/issues
Author: Chadd Harrison
License-Expression: MIT
License-File: LICENSE
Keywords: ai,cli,documentation,freshness,git,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.12
Requires-Dist: click>=8.1
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Description-Content-Type: text/markdown

# freshstate

**Keep your AI workspace docs fresh.**

Track document freshness, enforce cross-file consistency, and prevent stale docs in AI-assisted codebases.

## The Problem

AI coding tools (Claude Code, Cursor, Copilot Workspace) maintain persistent context files: `CLAUDE.md`, `.cursor/rules/`, state files, decision logs, changelogs. As projects grow, these files drift out of sync. A decision gets recorded but the timeline doesn't update. A README describes features that were removed three sprints ago. Nobody notices until the AI agent gives stale advice.

**freshstate** catches this before it becomes a problem.

## Quick Start

```bash
pip install freshstate

# Create a starter config
freshstate init

# Run checks
freshstate check
```

## Configuration

Create a `.freshstate.yml` in your project root:

```yaml
files:
  - path: README.md
    max_age: 30d
    severity: warning

  - path: "docs/*.md"
    max_age: 14d
    severity: error

rules:
  - name: decision-sync
    when: decisions.md
    then_also:
      - timeline.md
      - current-state.md
    within: same_commit
    severity: error

  - name: readme-sync
    when: "src/**/*.py"
    then_also: README.md
    within: 5_commits
    severity: warning

owners:
  - files: ["docs/*.md"]
    owner: docs-team
    checklist:
      - "Updated table of contents"
      - "Checked for broken links"
```

### File Freshness

Track how old files are based on their last git commit. Set thresholds with human-readable durations:

- `Nh` (hours): `24h`, `48h`
- `Nd` (days): `7d`, `30d`
- `Nw` (weeks): `2w`, `4w`

Severity levels: `info`, `warning`, `error`, `critical`

### Cross-Reference Rules (the killer feature)

Enforce that related files stay in sync:

- **`same_commit`**: Files must be modified in the same commit. Perfect for multi-file updates that should be atomic (e.g., a decision log + timeline + state snapshot).
- **`N_commits`**: Files must be modified within N commits of each other. Good for looser coupling (e.g., source code changes should update docs within a few commits). Maximum value: 1000.

### Ownership Declarations

Document who owns what and what their update checklist includes. Currently informational; future versions will integrate with CI to enforce checklists.

## Output Modes

### Text (default)

```bash
freshstate check
```

Color-coded terminal output with freshness status and rule results.

### JSON

```bash
freshstate check --json
```

Machine-readable output for dashboards and integrations.

### CI Mode

```bash
freshstate check --ci
```

GitHub Actions annotations format. Exit code 1 if any `error` or `critical` severity findings.

## CI Integration

### GitHub Actions

```yaml
name: Docs Freshness
on: [push, pull_request]

jobs:
  freshstate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Full history needed for git timestamps

      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - run: pip install freshstate

      - run: freshstate check --ci
```

## CLI Reference

```
freshstate check [OPTIONS]
  --config, -c PATH    Config file path (default: .freshstate.yml)
  --ci                 CI mode with GitHub annotations and exit codes
  --json               JSON output
  --repo PATH          Git repository root (default: current directory)

freshstate init [OPTIONS]
  --path PATH          Output path (default: .freshstate.yml)
  --force              Overwrite existing config
```

## Roadmap

- **v0.2.0**: MCP server for AI agent integration
- **v0.3.0**: Auto-fix suggestions
- **v0.4.0**: GitHub Action (no Python install needed)
- Cursor/Windsurf integration guides
- Dashboard web UI

## License

MIT
