docs(08-01): complete Rust directory archiver plan
- Create 08-01-SUMMARY.md with execution results and metrics - Update STATE.md: Phase 8 complete, 12/~19 plans (63%) - Update ROADMAP.md: Phase 8 marked complete - Update REQUIREMENTS.md: DIR-01 through DIR-05 marked complete Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
NikitolProject
@@ -70,11 +70,11 @@
|
||||
|
||||
### Directory (Поддержка директорий)
|
||||
|
||||
- [ ] **DIR-01**: `pack` рекурсивно обходит директории и добавляет все файлы
|
||||
- [ ] **DIR-02**: Относительные пути сохраняются при архивации (dir/subdir/file.txt)
|
||||
- [ ] **DIR-03**: Пустые директории сохраняются как записи типа "directory" в TOC
|
||||
- [ ] **DIR-04**: `unpack` создаёт полную иерархию директорий
|
||||
- [ ] **DIR-05**: `unpack` восстанавливает Unix mode bits для файлов и директорий
|
||||
- [x] **DIR-01**: `pack` рекурсивно обходит директории и добавляет все файлы
|
||||
- [x] **DIR-02**: Относительные пути сохраняются при архивации (dir/subdir/file.txt)
|
||||
- [x] **DIR-03**: Пустые директории сохраняются как записи типа "directory" в TOC
|
||||
- [x] **DIR-04**: `unpack` создаёт полную иерархию директорий
|
||||
- [x] **DIR-05**: `unpack` восстанавливает Unix mode bits для файлов и директорий
|
||||
|
||||
### Kotlin Decoder
|
||||
|
||||
@@ -165,11 +165,11 @@
|
||||
| FMT-10 | Phase 7 | Complete |
|
||||
| FMT-11 | Phase 7 | Complete |
|
||||
| FMT-12 | Phase 7 | Complete |
|
||||
| DIR-01 | Phase 8 | Pending |
|
||||
| DIR-02 | Phase 8 | Pending |
|
||||
| DIR-03 | Phase 8 | Pending |
|
||||
| DIR-04 | Phase 8 | Pending |
|
||||
| DIR-05 | Phase 8 | Pending |
|
||||
| DIR-01 | Phase 8 | Complete |
|
||||
| DIR-02 | Phase 8 | Complete |
|
||||
| DIR-03 | Phase 8 | Complete |
|
||||
| DIR-04 | Phase 8 | Complete |
|
||||
| DIR-05 | Phase 8 | Complete |
|
||||
| KOT-05 | Phase 9 | Pending |
|
||||
| KOT-06 | Phase 9 | Pending |
|
||||
| KOT-07 | Phase 9 | Pending |
|
||||
@@ -189,4 +189,4 @@
|
||||
|
||||
---
|
||||
*Requirements defined: 2026-02-24*
|
||||
*Last updated: 2026-02-25 after v1.1 roadmap creation*
|
||||
*Last updated: 2026-02-26 after Phase 8 completion (DIR-01 to DIR-05 complete)*
|
||||
|
||||
@@ -31,8 +31,8 @@ Decimal phases appear between their surrounding integers in numeric order.
|
||||
|
||||
### v1.1 Directory Support (In Progress)
|
||||
|
||||
- [ ] **Phase 7: Format Spec Update** - Extend FORMAT.md with entry type, permission bits, and relative path fields in TOC
|
||||
- [ ] **Phase 8: Rust Directory Archiver** - Recursive directory traversal, path-preserving pack/unpack, empty dirs, and mode bits in Rust CLI
|
||||
- [x] **Phase 7: Format Spec Update** - Extend FORMAT.md with entry type, permission bits, and relative path fields in TOC
|
||||
- [x] **Phase 8: Rust Directory Archiver** - Recursive directory traversal, path-preserving pack/unpack, empty dirs, and mode bits in Rust CLI
|
||||
- [ ] **Phase 9: Kotlin Decoder Update** - Kotlin decoder parses new TOC, creates directory hierarchy, and sets permissions
|
||||
- [ ] **Phase 10: Shell Decoder Update** - Shell decoder parses new TOC, mkdir -p for hierarchy, chmod for permissions
|
||||
- [ ] **Phase 11: Directory Cross-Validation** - Round-trip tests with nested dirs, empty dirs, mode bits, and cross-decoder verification
|
||||
@@ -159,7 +159,7 @@ Plans:
|
||||
**Plans**: 1 plan
|
||||
|
||||
Plans:
|
||||
- [ ] 08-01-PLAN.md -- Update format.rs (v1.1 TocEntry), archive.rs (recursive dir pack/unpack/inspect), and integration tests
|
||||
- [x] 08-01-PLAN.md -- Update format.rs (v1.1 TocEntry), archive.rs (recursive dir pack/unpack/inspect), and integration tests
|
||||
|
||||
### Phase 9: Kotlin Decoder Update
|
||||
**Goal**: Kotlin decoder extracts directory archives created by the updated Rust archiver, preserving hierarchy and permissions on Android
|
||||
@@ -209,7 +209,7 @@ Phases execute in numeric order: 1 -> 2 -> 3 -> 4 -> 5 -> 6 -> 7 -> 8 -> 9 -> 10
|
||||
| 5. Shell Decoder | v1.0 | 2/2 | Complete | 2026-02-25 |
|
||||
| 6. Obfuscation Hardening | v1.0 | 2/2 | Complete | 2026-02-25 |
|
||||
| 7. Format Spec Update | v1.1 | 1/1 | Complete | 2026-02-26 |
|
||||
| 8. Rust Directory Archiver | v1.1 | 0/1 | Not started | - |
|
||||
| 8. Rust Directory Archiver | v1.1 | 1/1 | Complete | 2026-02-26 |
|
||||
| 9. Kotlin Decoder Update | v1.1 | 0/TBD | Not started | - |
|
||||
| 10. Shell Decoder Update | v1.1 | 0/TBD | Not started | - |
|
||||
| 11. Directory Cross-Validation | v1.1 | 0/TBD | Not started | - |
|
||||
|
||||
@@ -2,13 +2,13 @@
|
||||
gsd_state_version: 1.0
|
||||
milestone: v1.0
|
||||
milestone_name: Directory Support
|
||||
status: unknown
|
||||
last_updated: "2026-02-26T18:32:22.936Z"
|
||||
status: active
|
||||
last_updated: "2026-02-26T18:48:33Z"
|
||||
progress:
|
||||
total_phases: 7
|
||||
completed_phases: 7
|
||||
total_plans: 11
|
||||
completed_plans: 11
|
||||
total_phases: 8
|
||||
completed_phases: 8
|
||||
total_plans: 12
|
||||
completed_plans: 12
|
||||
---
|
||||
|
||||
# Project State
|
||||
@@ -18,27 +18,28 @@ progress:
|
||||
See: .planning/PROJECT.md (updated 2026-02-25)
|
||||
|
||||
**Core value:** Archive impossible to unpack without knowing the format -- standard tools (7z, tar, unzip, binwalk) cannot recognize or extract contents
|
||||
**Current focus:** Milestone v1.1 Directory Support -- Phase 7: Format Spec Update
|
||||
**Current focus:** Milestone v1.1 Directory Support -- Phase 8: Rust Directory Archiver COMPLETE
|
||||
|
||||
## Current Position
|
||||
|
||||
Phase: 7 of 11 (Format Spec Update) -- COMPLETE
|
||||
Phase: 8 of 11 (Rust Directory Archiver) -- COMPLETE
|
||||
Plan: 1 of 1 -- COMPLETE
|
||||
Status: Phase 7 complete, ready for Phase 8
|
||||
Last activity: 2026-02-26 -- Phase 7 Plan 01 executed (FORMAT.md v1.1 update)
|
||||
Status: Phase 8 complete, v1.1 directory support implemented and tested
|
||||
Last activity: 2026-02-26 -- Phase 8 Plan 01 executed (directory archival in Rust)
|
||||
|
||||
Progress: [###########.........] 58% (11/~19 plans estimated)
|
||||
Progress: [############........] 63% (12/~19 plans estimated)
|
||||
|
||||
## Performance Metrics
|
||||
|
||||
**Velocity:**
|
||||
- Total plans completed: 11
|
||||
- Total plans completed: 12
|
||||
- Average duration: 3.8 min
|
||||
- Total execution time: 0.7 hours
|
||||
- Total execution time: 0.8 hours
|
||||
|
||||
| Phase | Plan | Duration | Tasks | Files |
|
||||
|-------|------|----------|-------|-------|
|
||||
| 07-01 | Format Spec Update | 8 min | 2 | 1 |
|
||||
| 08-01 | Rust Directory Archiver | 6 min | 3 | 4 |
|
||||
|
||||
## Accumulated Context
|
||||
|
||||
@@ -57,6 +58,10 @@ Recent decisions affecting current work:
|
||||
- v1.1: entry_type and permissions fields placed AFTER name, BEFORE original_size in TOC entry
|
||||
- v1.1: Directory entries use zero-filled crypto fields (uniform entry structure)
|
||||
- v1.1: Entry size formula: 104 + name_length (was 101)
|
||||
- v1.1: DFS preorder with sorted children for deterministic parent-before-child ordering
|
||||
- v1.1: Extracted crypto pipeline into process_file() helper for reuse
|
||||
- v1.1: Directory entries skip data_offset computation (offset=0, no ciphertext)
|
||||
- v1.1: Permissions stored as lower 12 bits of mode_t (0o7777 mask)
|
||||
|
||||
### Pending Todos
|
||||
|
||||
@@ -69,5 +74,5 @@ None.
|
||||
## Session Continuity
|
||||
|
||||
Last session: 2026-02-26
|
||||
Stopped at: Completed 07-01-PLAN.md -- Phase 7 complete, ready for Phase 8
|
||||
Stopped at: Completed 08-01-PLAN.md -- Phase 8 complete, v1.1 directory support implemented
|
||||
Resume file: None
|
||||
|
||||
119
.planning/phases/08-rust-directory-archiver/08-01-SUMMARY.md
Normal file
119
.planning/phases/08-rust-directory-archiver/08-01-SUMMARY.md
Normal file
@@ -0,0 +1,119 @@
|
||||
---
|
||||
phase: 08-rust-directory-archiver
|
||||
plan: 01
|
||||
subsystem: archive
|
||||
tags: [rust, directory-traversal, unix-permissions, binary-format, toc-entry]
|
||||
|
||||
# Dependency graph
|
||||
requires:
|
||||
- phase: 07-format-spec-update
|
||||
provides: v1.1 FORMAT.md with entry_type, permissions fields, directory entry semantics
|
||||
provides:
|
||||
- v1.1 TocEntry with entry_type and permissions fields (format.rs)
|
||||
- Recursive directory traversal in pack with relative paths
|
||||
- Directory hierarchy restoration with Unix mode bits in unpack
|
||||
- Entry type and permissions display in inspect
|
||||
- Directory round-trip integration tests
|
||||
affects: [09-backward-compat, 10-hardening, 11-polish]
|
||||
|
||||
# Tech tracking
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns: [collect_entries pattern for recursive directory traversal, DFS preorder for parent-before-child ordering, ProcessedFile entry_type discriminator for file vs directory handling]
|
||||
|
||||
key-files:
|
||||
created: []
|
||||
modified:
|
||||
- src/format.rs
|
||||
- src/archive.rs
|
||||
- src/cli.rs
|
||||
- tests/round_trip.rs
|
||||
|
||||
key-decisions:
|
||||
- "DFS preorder traversal with sorted children for deterministic parent-before-child ordering"
|
||||
- "Directory entries use zero-filled crypto fields (no data block) per FORMAT.md v1.1"
|
||||
- "Permissions captured via std::os::unix::fs::PermissionsExt::mode() & 0o7777"
|
||||
- "Standalone files use filename-only names; directory children use relative paths with / separator"
|
||||
|
||||
patterns-established:
|
||||
- "collect_entries(): unified entry collection for mixed file/directory inputs"
|
||||
- "process_file(): extracted crypto pipeline into reusable function"
|
||||
- "make_directory_entry(): factory for zero-length directory ProcessedFile"
|
||||
|
||||
requirements-completed: [DIR-01, DIR-02, DIR-03, DIR-04, DIR-05]
|
||||
|
||||
# Metrics
|
||||
duration: 6min
|
||||
completed: 2026-02-26
|
||||
---
|
||||
|
||||
# Phase 8 Plan 01: Rust Directory Archiver Summary
|
||||
|
||||
**v1.1 format implementation with recursive directory traversal, Unix permission preservation, and directory/file type discrimination in pack/unpack/inspect**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** 6 min
|
||||
- **Started:** 2026-02-26T18:42:02Z
|
||||
- **Completed:** 2026-02-26T18:48:33Z
|
||||
- **Tasks:** 3
|
||||
- **Files modified:** 4
|
||||
|
||||
## Accomplishments
|
||||
- Updated format.rs to v1.1 binary layout: VERSION=2, TocEntry with entry_type (u8) and permissions (u16), entry_size=104+name_length
|
||||
- Implemented recursive directory traversal in pack() with parent-before-child ordering and relative path naming
|
||||
- unpack() creates full directory hierarchy, restores Unix mode bits on both files and directories
|
||||
- inspect() displays entry type (dir/file) and octal permissions for each TOC entry
|
||||
- All 41 tests pass: 25 unit + 7 golden + 9 integration (3 new directory tests)
|
||||
|
||||
## Task Commits
|
||||
|
||||
Each task was committed atomically:
|
||||
|
||||
1. **Task 1: Update format.rs for v1.1 TOC entry layout** - `4e25d19` (feat)
|
||||
2. **Task 2: Update archive.rs and cli.rs for directory support** - `7820c18` (feat)
|
||||
3. **Task 3: Add directory round-trip integration test** - `8760981` (test)
|
||||
|
||||
## Files Created/Modified
|
||||
- `src/format.rs` - v1.1 TocEntry with entry_type/permissions, VERSION=2, entry_size=104+N
|
||||
- `src/archive.rs` - Recursive directory traversal, permission capture/restore, directory-aware pack/unpack/inspect
|
||||
- `src/cli.rs` - Updated doc comments for directory support
|
||||
- `tests/round_trip.rs` - 3 new tests: directory round-trip, mixed files+dirs, inspect directory info
|
||||
|
||||
## Decisions Made
|
||||
- Used DFS preorder with sorted children for deterministic parent-before-child ordering (no external walkdir dependency)
|
||||
- Extracted crypto pipeline into process_file() helper for reuse between single-file and directory-file processing
|
||||
- Directory entries skip data_offset computation and data block writing (offset=0, no ciphertext)
|
||||
- Permissions always stored as lower 12 bits of mode_t (0o7777 mask) per FORMAT.md v1.1 spec
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 3 - Blocking] Added entry_type/permissions to archive.rs ProcessedFile during Task 1**
|
||||
- **Found during:** Task 1 (format.rs update)
|
||||
- **Issue:** After adding new fields to TocEntry, archive.rs TocEntry constructions failed to compile
|
||||
- **Fix:** Added entry_type and permissions fields to ProcessedFile struct and its construction in pack()
|
||||
- **Files modified:** src/archive.rs
|
||||
- **Verification:** cargo test --lib format:: passed all 13 tests
|
||||
- **Committed in:** 4e25d19 (Task 1 commit)
|
||||
|
||||
---
|
||||
|
||||
**Total deviations:** 1 auto-fixed (1 blocking)
|
||||
**Impact on plan:** Necessary compilation fix from cross-file dependency. No scope creep.
|
||||
|
||||
## Issues Encountered
|
||||
None -- all tasks executed smoothly after the blocking compilation fix.
|
||||
|
||||
## User Setup Required
|
||||
None - no external service configuration required.
|
||||
|
||||
## Next Phase Readiness
|
||||
- v1.1 format fully implemented and tested
|
||||
- Ready for Phase 9 (backward compatibility) or Phase 10 (hardening) if planned
|
||||
- All existing v1.0 tests updated to v1.1 format (no backward compat with v1.0 archives per decision)
|
||||
|
||||
---
|
||||
*Phase: 08-rust-directory-archiver*
|
||||
*Completed: 2026-02-26*
|
||||
Reference in New Issue
Block a user