@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.
Files changed (128) hide show
  1. package/.nvmrc +2 -0
  2. package/LICENSE +190 -0
  3. package/README.md +95 -0
  4. package/dist/configure.d.ts +5 -0
  5. package/dist/configure.js +44 -0
  6. package/dist/configure.js.map +1 -0
  7. package/dist/constants.d.ts +36 -0
  8. package/dist/constants.js +53 -0
  9. package/dist/constants.js.map +1 -0
  10. package/dist/defaults.d.ts +2 -0
  11. package/dist/defaults.js +32 -0
  12. package/dist/defaults.js.map +1 -0
  13. package/dist/dreadcabinet.cjs +1793 -0
  14. package/dist/dreadcabinet.cjs.map +1 -0
  15. package/dist/dreadcabinet.d.ts +131 -0
  16. package/dist/dreadcabinet.js +111 -0
  17. package/dist/dreadcabinet.js.map +1 -0
  18. package/dist/error/ArgumentError.d.ts +5 -0
  19. package/dist/error/ArgumentError.js +26 -0
  20. package/dist/error/ArgumentError.js.map +1 -0
  21. package/dist/input/input.d.ts +7 -0
  22. package/dist/input/input.js +13 -0
  23. package/dist/input/input.js.map +1 -0
  24. package/dist/input/process.d.ts +5 -0
  25. package/dist/input/process.js +36 -0
  26. package/dist/input/process.js.map +1 -0
  27. package/dist/input/structured.d.ts +15 -0
  28. package/dist/input/structured.js +324 -0
  29. package/dist/input/structured.js.map +1 -0
  30. package/dist/input/unstructured.d.ts +2 -0
  31. package/dist/input/unstructured.js +45 -0
  32. package/dist/input/unstructured.js.map +1 -0
  33. package/dist/logger.d.ts +2 -0
  34. package/dist/logger.js +19 -0
  35. package/dist/logger.js.map +1 -0
  36. package/dist/operate.d.ts +2 -0
  37. package/dist/operate.js +27 -0
  38. package/dist/operate.js.map +1 -0
  39. package/dist/output.d.ts +7 -0
  40. package/dist/output.js +99 -0
  41. package/dist/output.js.map +1 -0
  42. package/dist/read.d.ts +4 -0
  43. package/dist/read.js +30 -0
  44. package/dist/read.js.map +1 -0
  45. package/dist/util/dates.d.ts +60 -0
  46. package/dist/util/dates.js +699 -0
  47. package/dist/util/dates.js.map +1 -0
  48. package/dist/util/storage.d.ts +33 -0
  49. package/dist/util/storage.js +140 -0
  50. package/dist/util/storage.js.map +1 -0
  51. package/dist/validate.d.ts +4 -0
  52. package/dist/validate.js +134 -0
  53. package/dist/validate.js.map +1 -0
  54. package/guide/architecture.md +60 -0
  55. package/guide/configuration.md +132 -0
  56. package/guide/development.md +110 -0
  57. package/guide/index.md +62 -0
  58. package/guide/usage.md +166 -0
  59. package/output/kodrdriv/250703-0645-commit-message.md +21 -0
  60. package/output/kodrdriv/250703-0653-commit-message.md +1 -0
  61. package/output/kodrdriv/250703-0654-commit-message.md +1 -0
  62. package/output/kodrdriv/250703-0655-release-notes.md +51 -0
  63. package/output/kodrdriv/250703-0700-commit-message.md +1 -0
  64. package/output/kodrdriv/250703-0700-release-notes.md +8 -0
  65. package/output/kodrdriv/250703-0706-commit-message.md +1 -0
  66. package/output/kodrdriv/250703-0706-release-notes.md +11 -0
  67. package/output/kodrdriv/250703-0717-commit-message.md +1 -0
  68. package/output/kodrdriv/250703-0719-commit-message.md +1 -0
  69. package/output/kodrdriv/250703-0719-release-notes.md +17 -0
  70. package/output/kodrdriv/250703-0730-commit-message.md +1 -0
  71. package/output/kodrdriv/250703-0730-release-notes.md +11 -0
  72. package/output/kodrdriv/250703-1510-commit-message.md +1 -0
  73. package/output/kodrdriv/250710-0805-commit-message.md +3 -0
  74. package/output/kodrdriv/250710-0815-commit-message.md +1 -0
  75. package/output/kodrdriv/250710-0815-release-notes.md +39 -0
  76. package/output/kodrdriv/260107-2021-commit-message.md +37 -0
  77. package/output/kodrdriv/260108-0432-commit-message.md +6 -0
  78. package/output/kodrdriv/260108-0435-commit-message.md +3 -0
  79. package/output/kodrdriv/260108-0436-commit-message.md +4 -0
  80. package/output/kodrdriv/260108-0439-release-notes.md +63 -0
  81. package/output/kodrdriv/260108-0543-commit-message.md +19 -0
  82. package/output/kodrdriv/260108-0550-commit-message.md +3 -0
  83. package/output/kodrdriv/260108-0550-release-notes.md +19 -0
  84. package/output/kodrdriv/260108-0600-commit-message.md +3 -0
  85. package/output/kodrdriv/260110-0717-commit-message.md +4 -0
  86. package/output/kodrdriv/260110-1152-commit-message.md +1 -0
  87. package/output/kodrdriv/260110-1850-commit-message.md +1 -0
  88. package/output/kodrdriv/260110-1852-release-notes.md +33 -0
  89. package/output/kodrdriv/260112-2257-commit-message.md +5 -0
  90. package/output/kodrdriv/260112-2317-commit-message.md +1 -0
  91. package/output/kodrdriv/260112-2318-release-notes.md +42 -0
  92. package/output/kodrdriv/260113-0053-commit-message.md +1 -0
  93. package/output/kodrdriv/260113-0054-commit-message.md +1 -0
  94. package/output/kodrdriv/260113-0054-release-notes.md +49 -0
  95. package/output/kodrdriv/260130-1132-commit-message.md +1 -0
  96. package/output/kodrdriv/260130-1135-commit-message.md +1 -0
  97. package/output/kodrdriv/260130-1335-commit-message.md +10 -0
  98. package/output/kodrdriv/RELEASE_NOTES.md +47 -0
  99. package/output/kodrdriv/RELEASE_TITLE.md +1 -0
  100. package/output/kodrdriv/agentic-reflection-commit-2026-01-08T04-21-54-623Z.md +372 -0
  101. package/output/kodrdriv/agentic-reflection-commit-2026-01-08T12-32-36-513Z.md +55 -0
  102. package/output/kodrdriv/agentic-reflection-commit-2026-01-08T12-35-58-580Z.md +105 -0
  103. package/output/kodrdriv/agentic-reflection-commit-2026-01-08T12-36-05-658Z.md +53 -0
  104. package/output/kodrdriv/agentic-reflection-commit-2026-01-08T13-43-55-498Z.md +178 -0
  105. package/output/kodrdriv/agentic-reflection-commit-2026-01-08T13-50-10-230Z.md +53 -0
  106. package/output/kodrdriv/agentic-reflection-commit-2026-01-08T13-50-35-136Z.md +52 -0
  107. package/output/kodrdriv/agentic-reflection-commit-2026-01-08T14-00-30-772Z.md +52 -0
  108. package/output/kodrdriv/agentic-reflection-commit-2026-01-10T15-17-43-324Z.md +53 -0
  109. package/output/kodrdriv/agentic-reflection-commit-2026-01-10T19-52-47-424Z.md +97 -0
  110. package/output/kodrdriv/agentic-reflection-commit-2026-01-11T02-50-23-123Z.md +138 -0
  111. package/output/kodrdriv/agentic-reflection-commit-2026-01-11T02-50-45-038Z.md +114 -0
  112. package/output/kodrdriv/agentic-reflection-commit-2026-01-11T02-50-49-467Z.md +114 -0
  113. package/output/kodrdriv/agentic-reflection-commit-2026-01-13T06-57-00-384Z.md +169 -0
  114. package/output/kodrdriv/agentic-reflection-commit-2026-01-13T07-17-29-292Z.md +114 -0
  115. package/output/kodrdriv/agentic-reflection-commit-2026-01-13T07-17-47-579Z.md +114 -0
  116. package/output/kodrdriv/agentic-reflection-commit-2026-01-13T08-48-55-599Z.md +144 -0
  117. package/output/kodrdriv/agentic-reflection-commit-2026-01-13T08-53-53-725Z.md +114 -0
  118. package/output/kodrdriv/agentic-reflection-commit-2026-01-13T08-54-11-600Z.md +97 -0
  119. package/output/kodrdriv/agentic-reflection-commit-2026-01-30T19-32-17-053Z.md +174 -0
  120. package/output/kodrdriv/agentic-reflection-commit-2026-01-30T19-35-00-887Z.md +152 -0
  121. package/output/kodrdriv/agentic-reflection-commit-2026-01-30T21-02-16-553Z.md +236 -0
  122. package/output/kodrdriv/agentic-reflection-commit-2026-01-30T21-17-22-227Z.md +347 -0
  123. package/output/kodrdriv/agentic-reflection-release-2026-01-08T12-39-08-279Z.md +507 -0
  124. package/output/kodrdriv/agentic-reflection-release-2026-01-08T13-50-57-683Z.md +183 -0
  125. package/output/kodrdriv/agentic-reflection-release-2026-01-11T02-52-39-082Z.md +347 -0
  126. package/output/kodrdriv/agentic-reflection-release-2026-01-13T07-18-21-218Z.md +315 -0
  127. package/output/kodrdriv/agentic-reflection-release-2026-01-13T08-54-59-340Z.md +354 -0
  128. 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.