dsh-file-checksum

Readme

# dsh-file-checksum

A small, read-only [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin that computes SHA-256 or SHA-512 for a file through the active Harness filesystem provider.

Unlike text-hashing tools, `file_checksum` reads the file's raw bytes without placing its contents in the model conversation. It works with the filesystem mounted by the current DSH profile, including compatible remote providers.

## Install

Install directly from GitHub into a profile:

```sh
dsh plugin --profile web add github:yan9651688/dsh-file-checksum
```

For reproducible installs, pin a commit:

```sh
dsh plugin --profile web add github:yan9651688/dsh-file-checksum#<commit-sha>
```

Then start that profile as usual:

```sh
dsh --profile web --dump-config
dsh --profile web
```

This repository ships plain ESM JavaScript, so a GitHub install does not need a `prepare` build or pnpm `allowBuilds` entry.

## Tool

`file_checksum` accepts:

| Parameter | Required | Description |
| --- | --- | --- |
| `file_path` | yes | Absolute path, or a path relative to the current agent session workspace. |
| `algorithm` | no | `sha256` (default) or `sha512`. |
| `expected` | no | Expected hexadecimal digest. The tool returns `match` or `mismatch`. |

Example prompt:

```text
Use file_checksum to verify dist/app.tgz against this SHA-256: <digest>
```

The canonical result is structured for Native and Code Mode callers:

```json
{
  "path": "/workspace/dist/app.tgz",
  "algorithm": "sha256",
  "digest": "...",
  "bytes": 12345,
  "verification": "match"
}
```

A checksum mismatch is a successful tool result with `verification: "mismatch"`; missing, non-regular, oversized, or unreadable files are tool errors.

## Configuration

The bundle defaults to a 64 MiB whole-file limit:

```yaml
- insert:
    - id: file-checksum
      name: dsh-file-checksum
      config:
        maxBytes: 67108864
```

Override the row in a later profile patch to choose a different positive integer, up to 256 MiB. The limit exists because the current DSH raw-byte filesystem API returns a complete bounded file rather than a byte stream.

## Data and safety

- Reads through `ctx.fs`; it does not invoke a shell or bypass the active filesystem provider.
- Reads one regular file and never writes or deletes files.
- Declares checksum calls exclusive so one Native or Code Mode batch cannot multiply the configured whole-file memory limit.
- Does not access environment variables, credentials, or the network.
- Returns the digest, byte count, display path, and verification status; it does not return file contents.
- Records the successful or missing read through DSH's `fs/observed` event, matching the built-in file-read behavior.
- A digest identifies content integrity. It is not encryption and does not make sensitive data safe to share.

## Known limitations

- One file per call; directories and Git tree hashes are not supported.
- Files larger than `maxBytes` are rejected rather than streamed or truncated.
- Separate agents or sessions may still run calls concurrently; each call can buffer up to `maxBytes`.
- The plugin is intended for DSH `0.1.0-rc.6` and later compatible `0.1.x` releases. DeepSeek Harness is still in developer preview, so breaking upstream changes may require a plugin update.

## Development

```sh
npm install
npm test
npm pack --dry-run
```

The tests mount the real Cordis context, tool registry, and local DSH filesystem provider. They cover standard hash vectors, binary bytes, expected-digest comparison, session-relative paths, filesystem observations, error cases, and lifecycle cleanup.

## License

[MIT](LICENSE)