# ArtifactGuard

![CI](https://github.com/ekta-chaudhry/artifact-guard/actions/workflows/ci.yml/badge.svg)
![npm version](https://img.shields.io/npm/v/artifact-guard)
![npm downloads](https://img.shields.io/npm/dw/artifact-guard)
![license](https://img.shields.io/npm/l/artifact-guard)

ArtifactGuard is a privacy-aware CLI for AI-assisted development workflows. It snapshots your workspace, detects agent-created artifacts, classifies source/temporary/sensitive files, safely deletes disposable artifacts, and generates end-of-session cleanup reports.

## Problem

AI coding agents often create temporary files while solving tasks: downloaded documents, extracted archives, debug logs, scratch scripts, JSON dumps, and one-off reports. These artifacts can clutter workspaces and may create privacy risk when sensitive files are left behind.

ArtifactGuard provides a lightweight artifact lifecycle layer for these sessions.

## Install

From npm:

```bash
npm install -g artifact-guard
```

From source:

```bash
git clone https://github.com/ekta-chaudhry/artifact-guard.git
cd artifact-guard
pnpm install
pnpm build
pnpm link --global
```

Then run from any workspace:

```bash
artifact-guard --help
```

## Commands

```bash
artifact-guard start                 # Capture a baseline workspace snapshot
artifact-guard status                # Show files changed since the snapshot
artifact-guard finish                # Classify artifacts and print a cleanup report
artifact-guard finish --delete-safe  # Delete created files classified as safe temporary artifacts
artifact-guard finish --interactive  # Review safe temporary artifacts before deleting
artifact-guard finish --report       # Write .artifact-guard/report.md
artifact-guard finish --clean-state  # Remove .artifact-guard/session.json after finish
```

Flags can be combined:

```bash
artifact-guard finish --interactive --report --clean-state
artifact-guard finish --delete-safe --report --clean-state
```

`--delete-safe` and `--interactive` are mutually exclusive.

## Example Workflow

```bash
artifact-guard start

# Simulate agent work
echo "debug" > debug.log
echo "SECRET=value" > .env.test
echo "# Notes" > notes.md

artifact-guard status
artifact-guard finish --delete-safe --report
```

Example report categories:

- **Source changes**: Git-tracked files, code, docs, config, and deleted tracked files
- **Temporary artifacts**: logs, archives, scratch/debug files
- **Sensitive / needs review**: env files, credentials, resumes, patient/customer exports
- **Deliverables**: reports or document outputs
- **Unknown / needs review**: untracked files not matched by current rules

## Safe Deletion Policy

`finish --delete-safe` deletes only files classified as both:

- `temporary`
- `created`

`finish --interactive` uses the same safety boundary, but asks before deleting each safe candidate.

ArtifactGuard does **not** auto-delete or offer interactive deletion for:

- modified files
- source changes
- sensitive files
- deliverables
- unknown files
- deleted-file records

## Git-Aware Classification

When run inside a Git repository, ArtifactGuard uses `git ls-files` to identify tracked files.

This means:

- modified Git-tracked files are classified as source-impacting changes even if their extension is unknown
- untracked files are still classified by sensitive, temporary, deliverable, source-extension, or unknown rules
- sensitive patterns take priority over Git tracking for privacy-first reporting

If Git is unavailable or the workspace is not a Git repository, ArtifactGuard falls back to pattern and extension-based classification.

## ArtifactGuard State

ArtifactGuard creates its own state directory in the workspace:

```text
.artifact-guard/
├── session.json   # created by `artifact-guard start`
└── report.md      # created/updated only when `--report` is used
```

By default, `finish` keeps this state so you can inspect the session and report afterwards.

Use `--clean-state` to remove the session snapshot after `finish` completes:

```bash
artifact-guard finish --report --clean-state
```

Behavior:

- removes `.artifact-guard/session.json`
- keeps `.artifact-guard/report.md` when `--report` is used
- removes the empty `.artifact-guard/` directory if no report or other state files remain

## Markdown Reports

Use `--report` to write a session report:

```bash
artifact-guard finish --report
```

Output:

```text
.artifact-guard/report.md
```

The report includes:

- summary counts
- safe-to-delete bytes
- deleted bytes when cleanup runs
- preserved source/sensitive/deliverable/unknown counts
- grouped artifact categories
- classifier reasons
- cleanup policy
- deleted/skipped files when `--delete-safe` is used

## Configuration

Add `.artifactguardrc.json` to customize project rules:

```json
{
  "ignore": ["coverage/**", "tmp/**"],
  "sourceExtensions": [".toml"],
  "temporaryPatterns": ["*.debug.json", "scratch/**"],
  "sensitivePatterns": ["*resume*", "*patient*", "*secret*"],
  "deliverablePatterns": ["reports/**", "deliverables/**"]
}
```

See `.artifactguardrc.example.json` for a starter config.

Pattern values support simple glob-like `*` / `**` matching. Regex strings are also supported with `/pattern/flags` syntax.

## AI Agent Integration

Integration examples are included for common agent workflows:

```text
integrations/pi-skill/SKILL.md
integrations/claude-code/CLAUDE.md
integrations/codex/AGENTS.md
integrations/generic-agent/ARTIFACTGUARD.md
```

They show how AI coding agents can run ArtifactGuard at the start and end of artifact-producing tasks.

## CI

GitHub Actions runs on pushes and pull requests to `main`:

```bash
pnpm install --frozen-lockfile
pnpm build
pnpm test
```

Workflow file:

```text
.github/workflows/ci.yml
```

## Current Behavior

- `start` stores a baseline snapshot in `.artifact-guard/session.json`
- `status` shows created, modified, and deleted files since the baseline
- `finish` classifies changes and prints cleanup recommendations
- Git-tracked files are classified as source-impacting changes
- `finish --delete-safe` deletes only created temporary artifacts
- `finish --interactive` prompts before deleting safe temporary artifacts
- `finish --report` writes `.artifact-guard/report.md`
- `finish --clean-state` removes `.artifact-guard/session.json` after finishing

## Planned Features

- Multi-session history

## Development

```bash
pnpm install
pnpm build
pnpm test
pnpm dev -- start
pnpm dev -- status
pnpm dev -- finish
```