dorky 4.1.4 → 4.1.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +139 -0
- package/package.json +1 -1
package/AGENTS.md
ADDED
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
# AGENTS.md
|
|
2
|
+
|
|
3
|
+
Context for LLMs and coding agents working in this repository.
|
|
4
|
+
|
|
5
|
+
## Project Overview
|
|
6
|
+
|
|
7
|
+
**dorky** — "DevOps Records Keeper". A CLI tool that stores sensitive project files (`.env`, configs, API keys) on remote storage (AWS S3 or Google Drive) instead of committing them to version control. Modeled loosely on `git` semantics: `add` / `rm` / `push` / `pull` / `log` / `checkout`.
|
|
8
|
+
|
|
9
|
+
- Package name: `dorky` (npm)
|
|
10
|
+
- Language: JavaScript (CommonJS, Node.js)
|
|
11
|
+
- License: ISC
|
|
12
|
+
- Homepage: https://dorky.trishantpahwa.me/
|
|
13
|
+
- Repository: https://github.com/trishantpahwa/dorky
|
|
14
|
+
|
|
15
|
+
## Repository Layout
|
|
16
|
+
|
|
17
|
+
```
|
|
18
|
+
dorky/
|
|
19
|
+
├── bin/
|
|
20
|
+
│ ├── index.js # Main CLI entrypoint (`dorky` binary)
|
|
21
|
+
│ └── mcp.js # MCP server entrypoint (`dorky-mcp` binary)
|
|
22
|
+
├── extension/
|
|
23
|
+
│ └── dorky-extension/ # VS Code extension (separate package, separate version)
|
|
24
|
+
├── web-app/ # Marketing/docs React site (CRA + Tailwind)
|
|
25
|
+
├── tests/
|
|
26
|
+
│ ├── e2e/cli.test.js # End-to-end CLI tests (Vitest)
|
|
27
|
+
│ └── helpers/ # Test fixtures + CLI runner helpers
|
|
28
|
+
├── .dorky/ # Local dorky state (metadata, credentials, history)
|
|
29
|
+
├── .dorkyignore # Files dorky should skip when scanning
|
|
30
|
+
├── .mcp.json # MCP server config for local dev
|
|
31
|
+
├── vitest.config.js
|
|
32
|
+
└── package.json
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
The three main artifacts (`dorky` CLI, `dorky-mcp` server, `dorky-extension`) are versioned independently — keep that in mind before bumping versions.
|
|
36
|
+
|
|
37
|
+
## Binaries / Entrypoints
|
|
38
|
+
|
|
39
|
+
| Binary | File | Purpose |
|
|
40
|
+
| ----------- | -------------- | ------------------------------------------------------ |
|
|
41
|
+
| `dorky` | `bin/index.js` | CLI tool — `yargs`-driven, handles all user commands |
|
|
42
|
+
| `dorky-mcp` | `bin/mcp.js` | MCP stdio server exposing dorky commands as MCP tools |
|
|
43
|
+
|
|
44
|
+
Both files share substantial logic (constants, helpers, S3 + Google Drive clients). Changes to one usually need mirroring in the other — there is no shared library yet.
|
|
45
|
+
|
|
46
|
+
## Key Constants (in both `bin/index.js` and `bin/mcp.js`)
|
|
47
|
+
|
|
48
|
+
- `DORKY_DIR = ".dorky"`
|
|
49
|
+
- `METADATA_PATH = .dorky/metadata.json` — tracks `stage-1-files` and `uploaded-files` (path → md5 hash)
|
|
50
|
+
- `CREDENTIALS_PATH = .dorky/credentials.json` — storage credentials, git-ignored
|
|
51
|
+
- `HISTORY_PATH = .dorky/history.json` — push commit log
|
|
52
|
+
- `GD_CREDENTIALS_PATH = ../google-drive-credentials.json` — relative to `bin/`
|
|
53
|
+
- `SCOPES = ['https://www.googleapis.com/auth/drive']`
|
|
54
|
+
|
|
55
|
+
Remote history snapshots live at `<project>/.dorky-history/<commit-id>/` in the remote bucket/folder.
|
|
56
|
+
|
|
57
|
+
## Commands (CLI)
|
|
58
|
+
|
|
59
|
+
| Flag | Alias | Purpose |
|
|
60
|
+
| -------------------- | ----- | --------------------------------------------- |
|
|
61
|
+
| `--init <provider>` | `-i` | Initialize project (`aws` or `google-drive`) |
|
|
62
|
+
| `--list [remote]` | `-l` | List local stageable / remote files |
|
|
63
|
+
| `--add <files...>` | `-a` | Stage files |
|
|
64
|
+
| `--rm <files...>` | `-r` | Unstage files |
|
|
65
|
+
| `--push` | `-ph` | Upload staged files, commit snapshot |
|
|
66
|
+
| `--pull` | `-pl` | Download all tracked files |
|
|
67
|
+
| `--log` | `-lg` | Show push history |
|
|
68
|
+
| `--checkout <id>` | `-co` | Restore files from a commit (prefix match OK) |
|
|
69
|
+
| `--migrate <target>` | `-m` | Migrate to another storage (partial) |
|
|
70
|
+
| `--destroy` | `-d` | Delete local state + remote files |
|
|
71
|
+
|
|
72
|
+
## MCP Tools (exposed by `dorky-mcp`)
|
|
73
|
+
|
|
74
|
+
`init`, `list`, `add`, `remove`, `push`, `pull`, `log`, `checkout`, `destroy` — names match CLI flags. MCP server expects storage credentials via env vars (`AWS_ACCESS_KEY`, `AWS_SECRET_KEY`, `AWS_REGION`, `BUCKET_NAME` for S3).
|
|
75
|
+
|
|
76
|
+
## Conventions
|
|
77
|
+
|
|
78
|
+
- **CommonJS only** in `bin/` — `require` / `module.exports`, no ESM there.
|
|
79
|
+
- **Vitest config is ESM** (`vitest.config.js` uses `import`/`export`).
|
|
80
|
+
- **Path normalization**: paths are stored POSIX-style in metadata/history. Use the `toPosix()` helper before writing to JSON and `normalizeKeys()` when reading.
|
|
81
|
+
- **File identity** is MD5 hash of contents (`md5` package) — used to skip unchanged files on push.
|
|
82
|
+
- **EOL**: Code uses `\r\n` on Darwin, `\n` elsewhere — see top of `bin/index.js`. Be careful when editing files dorky writes.
|
|
83
|
+
- **No TypeScript** in source despite `typescript` being a devDependency.
|
|
84
|
+
- **Error UX**: CLI uses `chalk` for colored output; MCP throws/returns structured errors instead of `process.exit`.
|
|
85
|
+
|
|
86
|
+
## Running & Testing
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
# Run CLI locally
|
|
90
|
+
node bin/index.js --help
|
|
91
|
+
# or
|
|
92
|
+
npm start
|
|
93
|
+
|
|
94
|
+
# Run MCP server
|
|
95
|
+
node bin/mcp.js
|
|
96
|
+
|
|
97
|
+
# Tests
|
|
98
|
+
npm test # vitest run
|
|
99
|
+
npm run test:watch
|
|
100
|
+
npm run test:unit
|
|
101
|
+
npm run test:e2e
|
|
102
|
+
npm run test:coverage # uses c8
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
E2E tests spawn the CLI as a subprocess via `tests/helpers/runCli.js` and use fixtures from `tests/helpers/fixtures.js`. They are slow — `testTimeout` is 60s. Vitest is configured with `threads: false` so subprocess handling stays sane.
|
|
106
|
+
|
|
107
|
+
## Environment Variables
|
|
108
|
+
|
|
109
|
+
For AWS S3 workflows (CLI, MCP, and extension all read these):
|
|
110
|
+
|
|
111
|
+
- `AWS_ACCESS_KEY`
|
|
112
|
+
- `AWS_SECRET_KEY`
|
|
113
|
+
- `AWS_REGION`
|
|
114
|
+
- `BUCKET_NAME`
|
|
115
|
+
|
|
116
|
+
For Google Drive: `google-drive-credentials.json` (OAuth client) must exist at the repo root, alongside `package.json`. Per-project user tokens are written to `.dorky/credentials.json` after `dorky --init google-drive`.
|
|
117
|
+
|
|
118
|
+
## Things to Watch Out For
|
|
119
|
+
|
|
120
|
+
- **Never commit** `.dorky/credentials.json`, `google-drive-credentials.json`, or `.env`. The CLI auto-appends these patterns to `.gitignore` on init — don't undo that.
|
|
121
|
+
- **`bin/index.js` and `bin/mcp.js` are intentionally duplicated.** Until they are refactored to share a module, mirror logic changes between them or behavior will drift.
|
|
122
|
+
- **The `extension/dorky-extension/` subproject has its own `node_modules` and its own version.** Don't bump it implicitly when bumping the root package.
|
|
123
|
+
- **Versioning history** (from recent commits): root `dorky` is at `4.1.4`, extension at `0.0.10` — they are bumped separately, often in the same commit but with separate intent.
|
|
124
|
+
- **`--migrate` is partially implemented.** Don't assume it works end-to-end.
|
|
125
|
+
- **Push is hash-aware**: if staged state matches the latest commit, push is a no-op. Tests need to account for this.
|
|
126
|
+
- **History entries** are mutated through `normalizeKeys` on read — if you bypass `readHistory()`, you risk Windows-style backslash keys leaking in.
|
|
127
|
+
|
|
128
|
+
## Out-of-Scope for Most Tasks
|
|
129
|
+
|
|
130
|
+
- `web-app/` is a separate React marketing site (CRA + Tailwind). Unrelated to the CLI; don't touch unless explicitly asked.
|
|
131
|
+
- `coverage/` is generated; never edit.
|
|
132
|
+
- `node_modules/` — never edit; reinstall instead.
|
|
133
|
+
|
|
134
|
+
## Where to Add Things
|
|
135
|
+
|
|
136
|
+
- New CLI flag → `bin/index.js` (yargs block near the top) + mirror as an MCP tool in `bin/mcp.js`.
|
|
137
|
+
- New storage provider → both `bin/index.js` and `bin/mcp.js` need provider branches; update `--init` validation and the metadata `provider` field.
|
|
138
|
+
- New tests → `tests/e2e/` (subprocess style) using helpers in `tests/helpers/`.
|
|
139
|
+
- README updates for user-facing changes; this file (AGENTS.md) for agent/dev-facing context.
|