@utilarium/dreadcabinet 0.0.16-dev.0
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/.nvmrc +2 -0
- package/LICENSE +190 -0
- package/README.md +95 -0
- package/dist/configure.d.ts +5 -0
- package/dist/configure.js +44 -0
- package/dist/configure.js.map +1 -0
- package/dist/constants.d.ts +36 -0
- package/dist/constants.js +53 -0
- package/dist/constants.js.map +1 -0
- package/dist/defaults.d.ts +2 -0
- package/dist/defaults.js +32 -0
- package/dist/defaults.js.map +1 -0
- package/dist/dreadcabinet.cjs +1793 -0
- package/dist/dreadcabinet.cjs.map +1 -0
- package/dist/dreadcabinet.d.ts +131 -0
- package/dist/dreadcabinet.js +111 -0
- package/dist/dreadcabinet.js.map +1 -0
- package/dist/error/ArgumentError.d.ts +5 -0
- package/dist/error/ArgumentError.js +26 -0
- package/dist/error/ArgumentError.js.map +1 -0
- package/dist/input/input.d.ts +7 -0
- package/dist/input/input.js +13 -0
- package/dist/input/input.js.map +1 -0
- package/dist/input/process.d.ts +5 -0
- package/dist/input/process.js +36 -0
- package/dist/input/process.js.map +1 -0
- package/dist/input/structured.d.ts +15 -0
- package/dist/input/structured.js +324 -0
- package/dist/input/structured.js.map +1 -0
- package/dist/input/unstructured.d.ts +2 -0
- package/dist/input/unstructured.js +45 -0
- package/dist/input/unstructured.js.map +1 -0
- package/dist/logger.d.ts +2 -0
- package/dist/logger.js +19 -0
- package/dist/logger.js.map +1 -0
- package/dist/operate.d.ts +2 -0
- package/dist/operate.js +27 -0
- package/dist/operate.js.map +1 -0
- package/dist/output.d.ts +7 -0
- package/dist/output.js +99 -0
- package/dist/output.js.map +1 -0
- package/dist/read.d.ts +4 -0
- package/dist/read.js +30 -0
- package/dist/read.js.map +1 -0
- package/dist/util/dates.d.ts +60 -0
- package/dist/util/dates.js +699 -0
- package/dist/util/dates.js.map +1 -0
- package/dist/util/storage.d.ts +33 -0
- package/dist/util/storage.js +140 -0
- package/dist/util/storage.js.map +1 -0
- package/dist/validate.d.ts +4 -0
- package/dist/validate.js +134 -0
- package/dist/validate.js.map +1 -0
- package/guide/architecture.md +60 -0
- package/guide/configuration.md +132 -0
- package/guide/development.md +110 -0
- package/guide/index.md +62 -0
- package/guide/usage.md +166 -0
- package/output/kodrdriv/250703-0645-commit-message.md +21 -0
- package/output/kodrdriv/250703-0653-commit-message.md +1 -0
- package/output/kodrdriv/250703-0654-commit-message.md +1 -0
- package/output/kodrdriv/250703-0655-release-notes.md +51 -0
- package/output/kodrdriv/250703-0700-commit-message.md +1 -0
- package/output/kodrdriv/250703-0700-release-notes.md +8 -0
- package/output/kodrdriv/250703-0706-commit-message.md +1 -0
- package/output/kodrdriv/250703-0706-release-notes.md +11 -0
- package/output/kodrdriv/250703-0717-commit-message.md +1 -0
- package/output/kodrdriv/250703-0719-commit-message.md +1 -0
- package/output/kodrdriv/250703-0719-release-notes.md +17 -0
- package/output/kodrdriv/250703-0730-commit-message.md +1 -0
- package/output/kodrdriv/250703-0730-release-notes.md +11 -0
- package/output/kodrdriv/250703-1510-commit-message.md +1 -0
- package/output/kodrdriv/250710-0805-commit-message.md +3 -0
- package/output/kodrdriv/250710-0815-commit-message.md +1 -0
- package/output/kodrdriv/250710-0815-release-notes.md +39 -0
- package/output/kodrdriv/260107-2021-commit-message.md +37 -0
- package/output/kodrdriv/260108-0432-commit-message.md +6 -0
- package/output/kodrdriv/260108-0435-commit-message.md +3 -0
- package/output/kodrdriv/260108-0436-commit-message.md +4 -0
- package/output/kodrdriv/260108-0439-release-notes.md +63 -0
- package/output/kodrdriv/260108-0543-commit-message.md +19 -0
- package/output/kodrdriv/260108-0550-commit-message.md +3 -0
- package/output/kodrdriv/260108-0550-release-notes.md +19 -0
- package/output/kodrdriv/260108-0600-commit-message.md +3 -0
- package/output/kodrdriv/260110-0717-commit-message.md +4 -0
- package/output/kodrdriv/260110-1152-commit-message.md +1 -0
- package/output/kodrdriv/260110-1850-commit-message.md +1 -0
- package/output/kodrdriv/260110-1852-release-notes.md +33 -0
- package/output/kodrdriv/260112-2257-commit-message.md +5 -0
- package/output/kodrdriv/260112-2317-commit-message.md +1 -0
- package/output/kodrdriv/260112-2318-release-notes.md +42 -0
- package/output/kodrdriv/260113-0053-commit-message.md +1 -0
- package/output/kodrdriv/260113-0054-commit-message.md +1 -0
- package/output/kodrdriv/260113-0054-release-notes.md +49 -0
- package/output/kodrdriv/260130-1132-commit-message.md +1 -0
- package/output/kodrdriv/260130-1135-commit-message.md +1 -0
- package/output/kodrdriv/260130-1335-commit-message.md +10 -0
- package/output/kodrdriv/RELEASE_NOTES.md +47 -0
- package/output/kodrdriv/RELEASE_TITLE.md +1 -0
- package/output/kodrdriv/agentic-reflection-commit-2026-01-08T04-21-54-623Z.md +372 -0
- package/output/kodrdriv/agentic-reflection-commit-2026-01-08T12-32-36-513Z.md +55 -0
- package/output/kodrdriv/agentic-reflection-commit-2026-01-08T12-35-58-580Z.md +105 -0
- package/output/kodrdriv/agentic-reflection-commit-2026-01-08T12-36-05-658Z.md +53 -0
- package/output/kodrdriv/agentic-reflection-commit-2026-01-08T13-43-55-498Z.md +178 -0
- package/output/kodrdriv/agentic-reflection-commit-2026-01-08T13-50-10-230Z.md +53 -0
- package/output/kodrdriv/agentic-reflection-commit-2026-01-08T13-50-35-136Z.md +52 -0
- package/output/kodrdriv/agentic-reflection-commit-2026-01-08T14-00-30-772Z.md +52 -0
- package/output/kodrdriv/agentic-reflection-commit-2026-01-10T15-17-43-324Z.md +53 -0
- package/output/kodrdriv/agentic-reflection-commit-2026-01-10T19-52-47-424Z.md +97 -0
- package/output/kodrdriv/agentic-reflection-commit-2026-01-11T02-50-23-123Z.md +138 -0
- package/output/kodrdriv/agentic-reflection-commit-2026-01-11T02-50-45-038Z.md +114 -0
- package/output/kodrdriv/agentic-reflection-commit-2026-01-11T02-50-49-467Z.md +114 -0
- package/output/kodrdriv/agentic-reflection-commit-2026-01-13T06-57-00-384Z.md +169 -0
- package/output/kodrdriv/agentic-reflection-commit-2026-01-13T07-17-29-292Z.md +114 -0
- package/output/kodrdriv/agentic-reflection-commit-2026-01-13T07-17-47-579Z.md +114 -0
- package/output/kodrdriv/agentic-reflection-commit-2026-01-13T08-48-55-599Z.md +144 -0
- package/output/kodrdriv/agentic-reflection-commit-2026-01-13T08-53-53-725Z.md +114 -0
- package/output/kodrdriv/agentic-reflection-commit-2026-01-13T08-54-11-600Z.md +97 -0
- package/output/kodrdriv/agentic-reflection-commit-2026-01-30T19-32-17-053Z.md +174 -0
- package/output/kodrdriv/agentic-reflection-commit-2026-01-30T19-35-00-887Z.md +152 -0
- package/output/kodrdriv/agentic-reflection-commit-2026-01-30T21-02-16-553Z.md +236 -0
- package/output/kodrdriv/agentic-reflection-commit-2026-01-30T21-17-22-227Z.md +347 -0
- package/output/kodrdriv/agentic-reflection-release-2026-01-08T12-39-08-279Z.md +507 -0
- package/output/kodrdriv/agentic-reflection-release-2026-01-08T13-50-57-683Z.md +183 -0
- package/output/kodrdriv/agentic-reflection-release-2026-01-11T02-52-39-082Z.md +347 -0
- package/output/kodrdriv/agentic-reflection-release-2026-01-13T07-18-21-218Z.md +315 -0
- package/output/kodrdriv/agentic-reflection-release-2026-01-13T08-54-59-340Z.md +354 -0
- package/package.json +80 -0
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
# Configuration Reference
|
|
2
|
+
|
|
3
|
+
**Purpose**: Detailed guide on configuring `dreadcabinet` instances and understanding available options.
|
|
4
|
+
|
|
5
|
+
## Instance Configuration (`create`)
|
|
6
|
+
|
|
7
|
+
The `create` function accepts an options object that controls behavior:
|
|
8
|
+
|
|
9
|
+
### Options
|
|
10
|
+
|
|
11
|
+
| Option | Type | Required | Description |
|
|
12
|
+
| :--- | :--- | :--- | :--- |
|
|
13
|
+
| `defaults` | `DefaultOptions` | No | Default values for configuration. |
|
|
14
|
+
| `allowed` | `AllowedOptions` | No | Restrict valid values for options. |
|
|
15
|
+
| `features` | `Feature[]` | No | Array of enabled features. |
|
|
16
|
+
| `addDefaults` | `boolean` | No | Whether to add defaults to CLI help text. |
|
|
17
|
+
| `logger` | `Logger` | No | Custom logger implementation. |
|
|
18
|
+
|
|
19
|
+
### Default Options
|
|
20
|
+
|
|
21
|
+
```typescript
|
|
22
|
+
interface DefaultOptions {
|
|
23
|
+
timezone?: string; // Default: 'Etc/UTC'
|
|
24
|
+
recursive?: boolean; // Default: false
|
|
25
|
+
inputDirectory?: string; // Default: './'
|
|
26
|
+
inputStructure?: FilesystemStructure; // Default: 'month'
|
|
27
|
+
inputFilenameOptions?: FilenameOption[]; // Default: ['date', 'subject']
|
|
28
|
+
outputDirectory?: string; // Default: './'
|
|
29
|
+
outputStructure?: FilesystemStructure; // Default: 'month'
|
|
30
|
+
outputFilenameOptions?: FilenameOption[];// Default: ['date', 'subject']
|
|
31
|
+
extensions?: string[]; // Default: ['md']
|
|
32
|
+
startDate?: string; // Optional date filter
|
|
33
|
+
endDate?: string; // Optional date filter
|
|
34
|
+
limit?: number; // Limit files processed
|
|
35
|
+
concurrency?: number; // Default: 1
|
|
36
|
+
}
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
### Allowed Options
|
|
40
|
+
|
|
41
|
+
Restrict which values users can specify:
|
|
42
|
+
|
|
43
|
+
```typescript
|
|
44
|
+
interface AllowedOptions {
|
|
45
|
+
inputStructures?: FilesystemStructure[]; // Default: ['none', 'year', 'month', 'day']
|
|
46
|
+
inputFilenameOptions?: FilenameOption[]; // Default: ['date', 'time', 'subject']
|
|
47
|
+
outputStructures?: FilesystemStructure[]; // Default: ['none', 'year', 'month', 'day']
|
|
48
|
+
outputFilenameOptions?: FilenameOption[]; // Default: ['date', 'time', 'subject']
|
|
49
|
+
extensions?: string[]; // Default: ['md', 'txt']
|
|
50
|
+
}
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## Features
|
|
54
|
+
|
|
55
|
+
Features control which CLI options are exposed:
|
|
56
|
+
|
|
57
|
+
| Feature | CLI Options Added |
|
|
58
|
+
| :--- | :--- |
|
|
59
|
+
| `input` | `-r/--recursive`, `-i/--input-directory`, `--limit`, `--concurrency` |
|
|
60
|
+
| `output` | `-o/--output-directory` |
|
|
61
|
+
| `structured-output` | `--output-structure`, `--output-filename-options` |
|
|
62
|
+
| `structured-input` | `--input-structure`, `--input-filename-options`, `--start`, `--end` |
|
|
63
|
+
| `extensions` | `--extensions` |
|
|
64
|
+
|
|
65
|
+
Default features: `['output', 'structured-output', 'input', 'extensions']`
|
|
66
|
+
|
|
67
|
+
## Filesystem Structures
|
|
68
|
+
|
|
69
|
+
Controls how files are organized into directories:
|
|
70
|
+
|
|
71
|
+
| Structure | Directory Pattern | Example |
|
|
72
|
+
| :--- | :--- | :--- |
|
|
73
|
+
| `none` | Flat | `./output/` |
|
|
74
|
+
| `year` | By year | `./output/2025/` |
|
|
75
|
+
| `month` | By year/month | `./output/2025/1/` |
|
|
76
|
+
| `day` | By year/month/day | `./output/2025/1/15/` |
|
|
77
|
+
|
|
78
|
+
## Filename Options
|
|
79
|
+
|
|
80
|
+
Controls components included in generated filenames:
|
|
81
|
+
|
|
82
|
+
| Option | Description | Example Component |
|
|
83
|
+
| :--- | :--- | :--- |
|
|
84
|
+
| `date` | Include date (format depends on structure) | `1-15` (if month structure) |
|
|
85
|
+
| `time` | Include time (HHmm format) | `1430` |
|
|
86
|
+
| `subject` | Include sanitized subject | `meeting_notes` |
|
|
87
|
+
|
|
88
|
+
Example filename with `['date', 'time', 'subject']`: `1-15-1430-abc123-md-meeting_notes`
|
|
89
|
+
|
|
90
|
+
## Example Configurations
|
|
91
|
+
|
|
92
|
+
### Simple File Organizer
|
|
93
|
+
|
|
94
|
+
```typescript
|
|
95
|
+
const instance = DreadCabinet.create({
|
|
96
|
+
defaults: {
|
|
97
|
+
inputDirectory: './inbox',
|
|
98
|
+
outputDirectory: './archive',
|
|
99
|
+
outputStructure: 'month',
|
|
100
|
+
extensions: ['md', 'txt'],
|
|
101
|
+
},
|
|
102
|
+
features: ['input', 'output', 'structured-output', 'extensions']
|
|
103
|
+
});
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
### High-Performance Batch Processor
|
|
107
|
+
|
|
108
|
+
```typescript
|
|
109
|
+
const instance = DreadCabinet.create({
|
|
110
|
+
defaults: {
|
|
111
|
+
concurrency: 10,
|
|
112
|
+
recursive: true,
|
|
113
|
+
extensions: ['jpg', 'png', 'gif'],
|
|
114
|
+
},
|
|
115
|
+
features: ['input', 'output', 'structured-output', 'extensions']
|
|
116
|
+
});
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
### Date-Range Filter
|
|
120
|
+
|
|
121
|
+
```typescript
|
|
122
|
+
const instance = DreadCabinet.create({
|
|
123
|
+
defaults: {
|
|
124
|
+
inputStructure: 'day',
|
|
125
|
+
outputStructure: 'month',
|
|
126
|
+
},
|
|
127
|
+
features: ['input', 'output', 'structured-input', 'structured-output']
|
|
128
|
+
});
|
|
129
|
+
|
|
130
|
+
// Then use --start and --end flags to filter
|
|
131
|
+
```
|
|
132
|
+
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
# Development Guide
|
|
2
|
+
|
|
3
|
+
**Purpose**: Instructions for contributing to and developing `dreadcabinet`.
|
|
4
|
+
|
|
5
|
+
## Setup
|
|
6
|
+
|
|
7
|
+
1. **Clone Repository**: `git clone https://github.com/utilarium/dreadcabinet.git`
|
|
8
|
+
2. **Install Dependencies**: `npm install`
|
|
9
|
+
3. **Build**: `npm run build`
|
|
10
|
+
|
|
11
|
+
## Testing
|
|
12
|
+
|
|
13
|
+
We use **Vitest** for testing.
|
|
14
|
+
|
|
15
|
+
* **Run All Tests**: `npm test`
|
|
16
|
+
* **Unit Tests Only**: `npm run test:coverage`
|
|
17
|
+
* **README Doc Tests**: `npm run test:readme` (requires build first)
|
|
18
|
+
|
|
19
|
+
### Testing Strategy
|
|
20
|
+
|
|
21
|
+
* **Unit Tests**: Located in `tests/`. We aim for high coverage.
|
|
22
|
+
* `tests/input/`: Tests for input processing (structured/unstructured).
|
|
23
|
+
* `tests/util/`: Tests for utilities (dates, storage).
|
|
24
|
+
* `tests/error/`: Tests for custom error classes.
|
|
25
|
+
* **Doc Tests**: README code examples are tested via `doccident` to ensure they stay accurate.
|
|
26
|
+
* **Mocking**: We use `vi.mock` for filesystem operations to avoid side effects.
|
|
27
|
+
|
|
28
|
+
### Running Tests
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
# Full test suite (requires build)
|
|
32
|
+
npm run precommit
|
|
33
|
+
|
|
34
|
+
# Just unit tests
|
|
35
|
+
npm run test:coverage
|
|
36
|
+
|
|
37
|
+
# Watch mode during development
|
|
38
|
+
npx vitest
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
## Linting & Formatting
|
|
42
|
+
|
|
43
|
+
* **Lint**: `npm run lint`
|
|
44
|
+
* **Fix**: `npm run lint:fix`
|
|
45
|
+
|
|
46
|
+
We use ESLint with strict TypeScript rules.
|
|
47
|
+
|
|
48
|
+
## Build
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
npm run build
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
This runs lint, TypeScript type checking, and Vite build to produce:
|
|
55
|
+
- `dist/dreadcabinet.js` (ESM)
|
|
56
|
+
- `dist/dreadcabinet.cjs` (CommonJS)
|
|
57
|
+
- `dist/dreadcabinet.d.ts` (TypeScript declarations)
|
|
58
|
+
|
|
59
|
+
## Project Structure
|
|
60
|
+
|
|
61
|
+
```
|
|
62
|
+
src/
|
|
63
|
+
├── dreadcabinet.ts # Main entry, types, factory
|
|
64
|
+
├── configure.ts # CLI option setup
|
|
65
|
+
├── read.ts # CLI args parsing
|
|
66
|
+
├── defaults.ts # Default value application
|
|
67
|
+
├── validate.ts # Config validation
|
|
68
|
+
├── operate.ts # Operator factory
|
|
69
|
+
├── output.ts # Output path/filename generation
|
|
70
|
+
├── constants.ts # Defaults and allowed values
|
|
71
|
+
├── logger.ts # Logger wrapper
|
|
72
|
+
├── input/
|
|
73
|
+
│ ├── input.ts # Input factory
|
|
74
|
+
│ ├── process.ts # File iteration
|
|
75
|
+
│ ├── structured.ts # Date-organized input
|
|
76
|
+
│ └── unstructured.ts # Flat/recursive input
|
|
77
|
+
├── util/
|
|
78
|
+
│ ├── dates.ts # Date/timezone utilities
|
|
79
|
+
│ └── storage.ts # Filesystem abstraction
|
|
80
|
+
└── error/
|
|
81
|
+
└── ArgumentError.ts # Custom error types
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## Adding Features
|
|
85
|
+
|
|
86
|
+
1. **Feature Flag**: Add to `Feature` type in `dreadcabinet.ts`.
|
|
87
|
+
2. **CLI Options**: Add to `configure.ts` with feature check.
|
|
88
|
+
3. **Read**: Update `read.ts` to handle new arguments.
|
|
89
|
+
4. **Defaults**: Update `defaults.ts` for new default values.
|
|
90
|
+
5. **Validation**: Update `validate.ts` if new validation needed.
|
|
91
|
+
6. **Constants**: Add defaults to `constants.ts`.
|
|
92
|
+
7. **Tests**: Write tests for all new functionality.
|
|
93
|
+
8. **Documentation**: Update `guide/` and README.
|
|
94
|
+
|
|
95
|
+
## Release Process
|
|
96
|
+
|
|
97
|
+
1. Update version in `package.json`.
|
|
98
|
+
2. Run `npm run precommit` (build + all tests).
|
|
99
|
+
3. Commit and push to `working` branch.
|
|
100
|
+
4. Create PR to `main`.
|
|
101
|
+
5. After merge, create GitHub release to trigger npm publish.
|
|
102
|
+
|
|
103
|
+
## Code Style
|
|
104
|
+
|
|
105
|
+
* **TypeScript**: Strict mode enabled.
|
|
106
|
+
* **Exports**: Prefer named exports over default exports.
|
|
107
|
+
* **Async**: Use async/await consistently.
|
|
108
|
+
* **Errors**: Use custom error classes for specific error types.
|
|
109
|
+
* **Logging**: Use the logger interface, never `console.log` directly in library code.
|
|
110
|
+
|
package/guide/index.md
ADDED
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
# AI Agent Guide: dreadcabinet
|
|
2
|
+
|
|
3
|
+
**Role**: You are an AI assistant tasked with understanding, integrating, or extending `dreadcabinet` file organization capabilities in applications.
|
|
4
|
+
|
|
5
|
+
**Goal**: Provide a comprehensive understanding of `dreadcabinet`'s capabilities, architecture, and usage patterns to facilitate correct implementation and extension.
|
|
6
|
+
|
|
7
|
+
## Core Capabilities
|
|
8
|
+
|
|
9
|
+
`dreadcabinet` is a file organization library for TypeScript/Node.js applications. It processes files from input directories and organizes them into structured output directories based on dates and metadata.
|
|
10
|
+
|
|
11
|
+
* **Date-Based Organization**: Place files into folders by year, month, or day (or flat structure).
|
|
12
|
+
* **Flexible Filename Generation**: Include date, time, and subject in generated filenames.
|
|
13
|
+
* **Timezone Support**: Convert timestamps to specific timezones for consistent naming.
|
|
14
|
+
* **Concurrent Processing**: Process multiple files in parallel for improved performance.
|
|
15
|
+
* **Extension Filtering**: Restrict processing to specific file types.
|
|
16
|
+
* **Non-Destructive**: Original files remain untouched; only copies are created.
|
|
17
|
+
|
|
18
|
+
## Quick Start Context
|
|
19
|
+
|
|
20
|
+
When analyzing or generating code using `dreadcabinet`, keep these patterns in mind:
|
|
21
|
+
|
|
22
|
+
1. **Create Instance**: Use `create()` with defaults and feature flags.
|
|
23
|
+
2. **Integrate CLI**: Use `.configure(program)` to bind to Commander.js.
|
|
24
|
+
3. **Read & Validate**: Use `.read()`, `.applyDefaults()`, and `.validate()`.
|
|
25
|
+
4. **Process Files**: Use the operator's `.process()` callback pattern.
|
|
26
|
+
|
|
27
|
+
```typescript
|
|
28
|
+
import { Command } from 'commander';
|
|
29
|
+
import * as DreadCabinet from '@utilarium/dreadcabinet';
|
|
30
|
+
|
|
31
|
+
const instance = DreadCabinet.create({
|
|
32
|
+
defaults: {
|
|
33
|
+
timezone: 'America/New_York',
|
|
34
|
+
extensions: ['md', 'txt'],
|
|
35
|
+
outputStructure: 'month',
|
|
36
|
+
outputDirectory: './organized',
|
|
37
|
+
}
|
|
38
|
+
});
|
|
39
|
+
|
|
40
|
+
const program = new Command();
|
|
41
|
+
await instance.configure(program);
|
|
42
|
+
program.parse();
|
|
43
|
+
|
|
44
|
+
const config = await instance.read(program.opts());
|
|
45
|
+
const finalConfig = instance.applyDefaults(config);
|
|
46
|
+
await instance.validate(finalConfig);
|
|
47
|
+
|
|
48
|
+
const operator = await instance.operate(finalConfig);
|
|
49
|
+
await operator.process(async (file) => {
|
|
50
|
+
// Your file processing logic
|
|
51
|
+
});
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
## Documentation Structure
|
|
55
|
+
|
|
56
|
+
This guide directory contains specialized documentation for different aspects of the system:
|
|
57
|
+
|
|
58
|
+
* [Configuration](./configuration.md): Deep dive into configuration options, features, and defaults.
|
|
59
|
+
* [Usage Patterns](./usage.md): Common patterns for CLI integration and file processing.
|
|
60
|
+
* [Architecture](./architecture.md): Internal design, module structure, and data flow.
|
|
61
|
+
* [Development](./development.md): Guide for contributing to `dreadcabinet` itself.
|
|
62
|
+
|
package/guide/usage.md
ADDED
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
# Usage Patterns
|
|
2
|
+
|
|
3
|
+
**Purpose**: Common patterns for integrating `dreadcabinet` into applications.
|
|
4
|
+
|
|
5
|
+
## CLI Integration (Commander.js)
|
|
6
|
+
|
|
7
|
+
`dreadcabinet` is designed to work seamlessly with `commander`.
|
|
8
|
+
|
|
9
|
+
```typescript
|
|
10
|
+
import { Command } from 'commander';
|
|
11
|
+
import * as DreadCabinet from '@utilarium/dreadcabinet';
|
|
12
|
+
|
|
13
|
+
// 1. Create instance with your defaults
|
|
14
|
+
const manager = DreadCabinet.create({
|
|
15
|
+
defaults: {
|
|
16
|
+
timezone: 'America/New_York',
|
|
17
|
+
outputStructure: 'month',
|
|
18
|
+
}
|
|
19
|
+
});
|
|
20
|
+
|
|
21
|
+
// 2. Setup Commander
|
|
22
|
+
const program = new Command();
|
|
23
|
+
program.name('my-organizer').version('1.0.0');
|
|
24
|
+
|
|
25
|
+
// 3. Configure (adds CLI options based on features)
|
|
26
|
+
await manager.configure(program);
|
|
27
|
+
|
|
28
|
+
// 4. Parse CLI args
|
|
29
|
+
program.parse();
|
|
30
|
+
const options = program.opts();
|
|
31
|
+
|
|
32
|
+
// 5. Read, apply defaults, validate
|
|
33
|
+
const config = await manager.read(options);
|
|
34
|
+
const finalConfig = manager.applyDefaults(config);
|
|
35
|
+
await manager.validate(finalConfig);
|
|
36
|
+
|
|
37
|
+
// 6. Process files
|
|
38
|
+
const operator = await manager.operate(finalConfig);
|
|
39
|
+
await operator.process(async (file) => {
|
|
40
|
+
console.log(`Processing: ${file}`);
|
|
41
|
+
});
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## File Processing Patterns
|
|
45
|
+
|
|
46
|
+
### Basic File Copy
|
|
47
|
+
|
|
48
|
+
```typescript
|
|
49
|
+
import fs from 'fs/promises';
|
|
50
|
+
import path from 'path';
|
|
51
|
+
|
|
52
|
+
await operator.process(async (file) => {
|
|
53
|
+
const createDate = new Date(); // Or extract from file metadata
|
|
54
|
+
const hash = crypto.randomBytes(4).toString('hex');
|
|
55
|
+
const ext = path.extname(file).slice(1);
|
|
56
|
+
|
|
57
|
+
const outputDir = await operator.constructOutputDirectory(createDate);
|
|
58
|
+
const filename = await operator.constructFilename(createDate, ext, hash, {
|
|
59
|
+
subject: path.basename(file, path.extname(file))
|
|
60
|
+
});
|
|
61
|
+
|
|
62
|
+
const outputPath = path.join(outputDir, `${filename}.${ext}`);
|
|
63
|
+
await fs.copyFile(file, outputPath);
|
|
64
|
+
});
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### With Transformation
|
|
68
|
+
|
|
69
|
+
```typescript
|
|
70
|
+
await operator.process(async (file) => {
|
|
71
|
+
// Read and transform content
|
|
72
|
+
const content = await fs.readFile(file, 'utf-8');
|
|
73
|
+
const transformed = processContent(content);
|
|
74
|
+
|
|
75
|
+
// Generate output location
|
|
76
|
+
const createDate = extractDateFromContent(content);
|
|
77
|
+
const outputDir = await operator.constructOutputDirectory(createDate);
|
|
78
|
+
const filename = await operator.constructFilename(createDate, 'md', hash);
|
|
79
|
+
|
|
80
|
+
// Write transformed content
|
|
81
|
+
await fs.writeFile(path.join(outputDir, `${filename}.md`), transformed);
|
|
82
|
+
});
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
### With Date Range Filtering
|
|
86
|
+
|
|
87
|
+
When using `structured-input` feature, filter files by date:
|
|
88
|
+
|
|
89
|
+
```typescript
|
|
90
|
+
await operator.process(
|
|
91
|
+
async (file, date) => {
|
|
92
|
+
console.log(`File: ${file}, Date: ${date}`);
|
|
93
|
+
},
|
|
94
|
+
{
|
|
95
|
+
start: new Date('2025-01-01'),
|
|
96
|
+
end: new Date('2025-01-31')
|
|
97
|
+
}
|
|
98
|
+
);
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
### Concurrent Processing
|
|
102
|
+
|
|
103
|
+
Set concurrency for parallel processing:
|
|
104
|
+
|
|
105
|
+
```typescript
|
|
106
|
+
const instance = DreadCabinet.create({
|
|
107
|
+
defaults: {
|
|
108
|
+
concurrency: 5, // Process 5 files simultaneously
|
|
109
|
+
}
|
|
110
|
+
});
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Or via CLI: `--concurrency 5`
|
|
114
|
+
|
|
115
|
+
## Custom Logger
|
|
116
|
+
|
|
117
|
+
Provide your own logger for integration with existing logging systems:
|
|
118
|
+
|
|
119
|
+
```typescript
|
|
120
|
+
import winston from 'winston';
|
|
121
|
+
|
|
122
|
+
const winstonLogger = winston.createLogger({ /* ... */ });
|
|
123
|
+
|
|
124
|
+
const instance = DreadCabinet.create({
|
|
125
|
+
logger: {
|
|
126
|
+
debug: (msg, ...args) => winstonLogger.debug(msg, ...args),
|
|
127
|
+
info: (msg, ...args) => winstonLogger.info(msg, ...args),
|
|
128
|
+
warn: (msg, ...args) => winstonLogger.warn(msg, ...args),
|
|
129
|
+
error: (msg, ...args) => winstonLogger.error(msg, ...args),
|
|
130
|
+
verbose: (msg, ...args) => winstonLogger.verbose(msg, ...args),
|
|
131
|
+
silly: (msg, ...args) => winstonLogger.silly(msg, ...args),
|
|
132
|
+
}
|
|
133
|
+
});
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
Or set it after creation:
|
|
137
|
+
|
|
138
|
+
```typescript
|
|
139
|
+
instance.setLogger(myLogger);
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
## Restricting Options
|
|
143
|
+
|
|
144
|
+
Limit what users can specify via CLI:
|
|
145
|
+
|
|
146
|
+
```typescript
|
|
147
|
+
const instance = DreadCabinet.create({
|
|
148
|
+
allowed: {
|
|
149
|
+
extensions: ['md'], // Only markdown files
|
|
150
|
+
outputStructures: ['month', 'day'], // No 'none' or 'year'
|
|
151
|
+
}
|
|
152
|
+
});
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
Validation will fail if users try to use disallowed values.
|
|
156
|
+
|
|
157
|
+
## Hiding Defaults in Help
|
|
158
|
+
|
|
159
|
+
By default, CLI help shows default values. To hide them (useful for dynamic defaults):
|
|
160
|
+
|
|
161
|
+
```typescript
|
|
162
|
+
const instance = DreadCabinet.create({
|
|
163
|
+
addDefaults: false, // Defaults shown as "(default: value)" in description
|
|
164
|
+
});
|
|
165
|
+
```
|
|
166
|
+
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
Replaces the legacy dependency-review workflow, nodemon, and Jest config with a modern docs site and full Vitest test suite; rewrites README for clarity and updates config files.
|
|
2
|
+
|
|
3
|
+
- Removes `.github/workflows/dependency-review.yml`, `nodemon.json`, and `jest.config.js` to clean up unused or deprecated tooling in favor of project-wide consistency.
|
|
4
|
+
- Adds `docs/` React documentation site (with Vite, TypeScript, and custom markdown renderer), a deploy-to-GitHub Pages workflow, and detailed markdown-based documentation covering getting started, configuration, CLI usage, API reference, advanced patterns, and contribution guidelines.
|
|
5
|
+
- Establishes `docs` as the canonical project documentation, replacing in-readme details with direct links to the generated site.
|
|
6
|
+
- Removes `.kodrdriv/config.yaml`, `.kodrdriv/context/content.md` and related context/config files as part of project simplification and configuration migration.
|
|
7
|
+
- Replaces all references to MIT with Apache-2.0 licensing.
|
|
8
|
+
- Upgrades testing framework from Jest to Vitest:
|
|
9
|
+
- Converts all test files to `vitest` syntax and APIs, including mocks, assertions, and setup/teardown.
|
|
10
|
+
- Replaces global Jest references with Vitest equivalents.
|
|
11
|
+
- Adds a top-level `vitest.config.ts` configuring node environment, test timeouts, coverage thresholds, and includes test setup.
|
|
12
|
+
- Updates `package.json`:
|
|
13
|
+
- Modernizes scripts to rely on Vitest for testing and coverage.
|
|
14
|
+
- Updates dependencies and devDependencies for consistency with new test/docs framework.
|
|
15
|
+
- Bumps `pnpm` version to match new lockfile.
|
|
16
|
+
- Removes explicit MIT license reference, sets Apache-2.0 in relevant places.
|
|
17
|
+
- Adds a new GitHub Actions workflow `.github/workflows/deploy-docs.yml` for building and deploying documentation to GitHub Pages.
|
|
18
|
+
- Adds `docs/.gitignore` and supporting config files for documentation site management.
|
|
19
|
+
- Refactors `README.md` for brevity, focusing on a quick start and linking out to full documentation.
|
|
20
|
+
- Ensures the docs site is fully built using Vite, React 19, and provides full coverage of previous in-repo documentation.
|
|
21
|
+
- Cleans up old or extraneous files for a unified, modern developer and documentation experience.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
Removes "jest" from the "types" array in tsconfig.json, leaving only "node" types. This cleanup reflects the transition from Jest to Vitest for testing and ensures that only relevant type definitions are included, avoiding potential conflicts or unnecessary type resolution during TypeScript compilation.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
Bump development dependencies in package.json: upgrade @babel/core to 7.28.0, @babel/plugin-transform-typescript to 7.28.0, and @theunwalked/cardigantime to 0.0.13. These updates ensure compatibility with the latest Babel and plugin features and pull in bug fixes and improvements from the referenced packages.
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# Switch to Vitest, Add Modern React Docs Site, and Simplify Project Tooling
|
|
2
|
+
|
|
3
|
+
This release prioritizes unifying documentation, updating the testing framework, and removing legacy/deprecated tools to improve project maintainability and contributor onboarding. The main focus is replacing piecemeal and obsolete project scaffolding with a modern, centralized documentation site and a streamlined testing setup. Licensing shifts from MIT to Apache-2.0 for consistency.
|
|
4
|
+
|
|
5
|
+
**Documentation Updates**
|
|
6
|
+
|
|
7
|
+
* Added a new `docs/` directory containing a fully built React documentation site (using Vite, TypeScript, and a custom Markdown renderer)
|
|
8
|
+
* Documentation site covers getting started, configuration, CLI usage, API reference, advanced usage, and contribution guidelines
|
|
9
|
+
* Added a `docs/`-specific `.gitignore`, package.json, Vite config, and test setup
|
|
10
|
+
* Documentation now deploys automatically to GitHub Pages via a new `.github/workflows/deploy-docs.yml` workflow
|
|
11
|
+
* Updated the top-level `README.md` to focus on a quick start and link to the deployed documentation site
|
|
12
|
+
* Removed configuration and feature details from the README (now in docs site)
|
|
13
|
+
|
|
14
|
+
**Testing and Tooling Changes**
|
|
15
|
+
|
|
16
|
+
* Switched test runner from Jest to Vitest:
|
|
17
|
+
* Deleted all Jest config and references (including `jest.config.js` and "jest" types from `tsconfig.json`)
|
|
18
|
+
* Converted test files to use `vitest` syntax and assertion APIs
|
|
19
|
+
* Added a new top-level `vitest.config.ts` for test configuration
|
|
20
|
+
* Updated development scripts in `package.json` for Vitest:
|
|
21
|
+
* `test` now runs documentation + coverage using Vitest
|
|
22
|
+
* Coverage thresholds and settings updated to match previous Jest configuration where applicable
|
|
23
|
+
|
|
24
|
+
**Improvements and Cleanup**
|
|
25
|
+
|
|
26
|
+
* Removed `.github/workflows/dependency-review.yml` (legacy/deprecated CI/workflow)
|
|
27
|
+
* Removed `nodemon.json` (no longer needed with new dev workflow)
|
|
28
|
+
* Removed `.kodrdriv/config.yaml` and other kodrdriv-specific context/config files as part of config migration
|
|
29
|
+
* Cleaned up old/extraneous files throughout the repo for a more unified developer and user experience
|
|
30
|
+
* All project references to the MIT license have been updated to Apache-2.0
|
|
31
|
+
* License in `README.md` now reflects this change
|
|
32
|
+
* `package.json` metadata updated as well
|
|
33
|
+
|
|
34
|
+
**Dependency Updates**
|
|
35
|
+
|
|
36
|
+
* Updated development dependencies in `package.json`:
|
|
37
|
+
* Upgraded `@babel/core` to 7.28.0
|
|
38
|
+
* Upgraded `@babel/plugin-transform-typescript` to 7.28.0
|
|
39
|
+
* Upgraded `@theunwalked/cardigantime` to 0.0.13
|
|
40
|
+
* Bumped `pnpm` version in `package.json` to `10.12.4`
|
|
41
|
+
* Updated various dependency versions for compatibility and consistency with new tools and frameworks
|
|
42
|
+
|
|
43
|
+
**Summary for Users & Contributors**
|
|
44
|
+
|
|
45
|
+
This release makes DreadCabinet easier to set up, understand, and contribute to by:
|
|
46
|
+
* Providing a unified, discoverable docs site (https://semicolonambulance.github.io/dreadcabinet/)
|
|
47
|
+
* Modernizing the test and dev workflow (Vitest > Jest, Vite for docs)
|
|
48
|
+
* Removing deprecated configs and tools
|
|
49
|
+
* Standardizing project licensing
|
|
50
|
+
|
|
51
|
+
If you maintained local config files or referenced custom project scripts or CI, please review the new documentation for updated usage and integration details.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
Removes unnecessary "composite" and "noEmit" options from docs/tsconfig.node.json to clean up the TypeScript configuration for the documentation site. Adds an empty pnpm-workspace.yaml at the project root, preparing the workspace for pnpm workspace features and multi-package setup.
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
# TypeScript Config Clean-Up and pnpm Workspace Preparation
|
|
2
|
+
|
|
3
|
+
This release centers on cleaning up configuration and preparing the project for future multi-package management. The primary focus is to streamline the developer experience and lay the groundwork for expanding to a pnpm-managed monorepo setup.
|
|
4
|
+
|
|
5
|
+
**Improvements**
|
|
6
|
+
|
|
7
|
+
* Removed unnecessary `composite` and `noEmit` options from `docs/tsconfig.node.json`, simplifying the TypeScript configuration for the documentation site
|
|
8
|
+
* Added an empty `pnpm-workspace.yaml` at the project root, initializing the project for pnpm workspace features and supporting future multi-package development
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
Simplifies the docs site TypeScript config by removing the redundant "references" array and adding "vite.config.ts" to the "include" list for better editor and type-checking support. Also cleans up `tsconfig.node.json` by dropping the unused "composite" and "noEmit" options. These adjustments streamline configuration and align it with the actual documentation project structure.
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# Documentation TypeScript Config Streamlined and Improved Editor Support
|
|
2
|
+
|
|
3
|
+
This release focuses on streamlining the TypeScript configuration for the documentation site, making the setup clearer and more closely aligned with current project usage. The goal is to reduce unnecessary complexity and enhance TypeScript support in editors and builds for documentation contributors.
|
|
4
|
+
|
|
5
|
+
**Improvements**
|
|
6
|
+
|
|
7
|
+
* Removed the redundant `references` array from `docs/tsconfig.json` as it no longer matched the actual project structure.
|
|
8
|
+
* Added `vite.config.ts` to the `include` list in `docs/tsconfig.json` to improve TypeScript editor support and ensure type checking works as expected with Vite configuration.
|
|
9
|
+
* Cleaned up `docs/tsconfig.node.json` by removing unused `composite` and `noEmit` options, matching its non-composite usage and simplifying configuration.
|
|
10
|
+
|
|
11
|
+
These changes help reduce configuration complexity and align TypeScript behavior more closely with contributor expectations and documentation workflows.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
Removes redundant TypeScript build and typecheck scripts from docs/package.json, consolidating to a single "vite build" step. Updates docs/tsconfig.json to specify "src/**/*" for source inclusion, excludes common output directories, and refines compiler options for clarity and stricter type checking. Adds a pnpm-workspace.yaml override to link @theunwalked/cardigantime to a local package, facilitating development with local dependency sources. These changes streamline configuration, reduce duplication, and support improved local package development workflows.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
Removes the `overrides` section from `pnpm-workspace.yaml`, eliminating the local link to `@theunwalked/cardigantime`. The workspace configuration now uses an empty object, reverting to default dependency resolution and workspace behavior.
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# Simplified Docs Build Process and Workspace Dependency Configuration
|
|
2
|
+
|
|
3
|
+
This release focuses on streamlining the documentation project's build process and clarifying dependency management in the workspace. The primary goals were to reduce duplication, improve clarity in TypeScript configurations, and simplify local package development workflows.
|
|
4
|
+
|
|
5
|
+
**Improvements**
|
|
6
|
+
|
|
7
|
+
* Removed redundant TypeScript build and typecheck scripts from `docs/package.json`. The build process now uses a single `vite build` step for simplicity.
|
|
8
|
+
* Updated `docs/tsconfig.json` to:
|
|
9
|
+
* Include all source files with `src/**/*` for better TypeScript coverage.
|
|
10
|
+
* Exclude standard output directories for cleaner builds.
|
|
11
|
+
* Refine compiler options for stricter and clearer type checking.
|
|
12
|
+
|
|
13
|
+
**Workspace Configuration Changes**
|
|
14
|
+
|
|
15
|
+
* The `pnpm-workspace.yaml` override that linked `@theunwalked/cardigantime` to a local package has been removed. Workspace configuration now reverts to default dependency resolution behavior, eliminating local linking and making dependency management simpler.
|
|
16
|
+
|
|
17
|
+
These changes help reduce maintenance overhead for development scripts and streamline dependency management in the workspace.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
Removes the empty pnpm-workspace.yaml file from the project root, eliminating unused workspace configuration and restoring default pnpm behavior for package management.
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# Removal of Unused Workspace Configuration Restores Default pnpm Behavior
|
|
2
|
+
|
|
3
|
+
This release focuses on streamlining package management by eliminating unnecessary workspace configuration. The primary goal, as highlighted in the Release Focus, is to simplify the project structure and revert to default package manager behavior, removing unused files that may interfere with typical development workflows.
|
|
4
|
+
|
|
5
|
+
**Improvements**
|
|
6
|
+
|
|
7
|
+
* Removed the empty `pnpm-workspace.yaml` file from the project root, deactivating pnpm workspace mode and restoring default pnpm package management behavior.
|
|
8
|
+
|
|
9
|
+
**Other Changes**
|
|
10
|
+
|
|
11
|
+
* Version bump to 0.0.9 in `package.json`.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
Add empty pnpm-workspace.yaml to initialize workspace support and enable pnpm to treat the repository as a monorepo root.
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
Remove moment-timezone and related timezone dependencies; provide static IANA timezone list and use dayjs exclusively for timezone support
|
|
2
|
+
|
|
3
|
+
Removes the moment-timezone dependency along with associated packages (luxon, winston, js-yaml and their types) from the codebase and updates `.npmignore` to exclude additional config and docs files from npm package distribution. Introduces a static list of IANA timezone names directly in `src/util/dates.ts` to replace runtime timezone name queries, and updates the `validTimezones()` function to return this static array using only dayjs for all timezone-related operations. This simplifies dependencies, reduces bundle size, and eliminates dynamic timezone database requirements while maintaining support for timezone-aware date manipulation.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
No staged changes detected; commit aborted.
|