Skip to content

sc-015.md

Latest commit

 

History

History
189 lines (165 loc) · 8.78 KB

sc-015.md

File metadata and controls

189 lines (165 loc) · 8.78 KB

← Back to Backlog

[SC-015] ✅ DONE - Reorganize project structure: separate tools from libraries

Status: Done (2026-03-15) Priority: Medium Component: lib/, tools/wsl-manager/

Summary: As a developer, I want a clear separation between reusable libraries (lib/) and executable tools (tools/) so that the project structure reflects the actual dependency direction.

Description: Currently, wsl-manager (a tool) lives inside tools/pslib/wsl/ and the utility library lives inside tools/pslib/utils/. This conflates two different concerns: libraries are reusable modules, while wsl-manager is a standalone tool that depends on them.

Additionally, commands.ps1 and manager.ps1 in tools/pslib/wsl/lib/ are wsl-manager tool orchestration files (CLI dispatcher and interactive menu), not reusable WSL library functions. They belong with the tool, not the library.

Current structure (relevant parts)

tools/
  install/
    install-npm-global.ps1        # npm-global installer
    install-npm-global.bat        # .bat wrapper
  pslib/
    AGENTS.md                     # Library-specific agent instructions
    CLAUDE.md                     # Points to AGENTS.md
    utils/
      utils.ps1                   # Reusable PowerShell utilities
      utils.Tests.ps1
      utils.Integration.Tests.ps1
    wsl/
      wsl-manager.ps1             # Tool entry point (executable)
      wsl-manager.bat             # Batch wrapper
      scripts/
        install-docker.sh          # Shell scripts used inside WSL
        install-podman.sh
        setup-proxy.sh
      lib/
        wsl.ps1                   # WSL library entry point (dot-sources modules)
        wsl.Tests.ps1
        wsl.Integration.Tests.ps1
        core.ps1                  # WSL library modules
        core.Tests.ps1
        docker.ps1
        docker.Tests.ps1
        exec.ps1
        exec.Tests.ps1
        install.ps1
        install.Tests.ps1
        ops.ps1
        ops.Tests.ps1
        podman.ps1
        podman.Tests.ps1
        proxy.ps1
        proxy.Tests.ps1
        user.ps1
        user.Tests.ps1
        commands.ps1              # Tool: action functions & dispatcher
        commands.Tests.ps1
        manager.ps1               # Tool: CLI entry & interactive menu
        manager.Tests.ps1
        manager.docker.Integration.Tests.ps1
        manager.podman.Integration.Tests.ps1

Target structure

lib/
  install/
    install-npm-global.ps1        # Reusable npm-global installer (no .bat wrapper)
  utils/
    utils.ps1                     # Reusable PowerShell utilities
    utils.Tests.ps1
    utils.Integration.Tests.ps1
  wsl/
    scripts/                      # Shell scripts used by WSL library functions
      install-docker.sh
      install-podman.sh
      setup-proxy.sh
    wsl.ps1                       # WSL library entry point (dot-sources modules)
    wsl.Tests.ps1
    wsl.Integration.Tests.ps1
    core.ps1                      # WSL library modules
    core.Tests.ps1
    docker.ps1
    docker.Tests.ps1
    exec.ps1
    exec.Tests.ps1
    install.ps1
    install.Tests.ps1
    ops.ps1
    ops.Tests.ps1
    podman.ps1
    podman.Tests.ps1
    proxy.ps1
    proxy.Tests.ps1
    user.ps1
    user.Tests.ps1
    commands.ps1                  # Action functions & command dispatcher
    commands.Tests.ps1
    manager.ps1                   # CLI entry & interactive menu
    manager.Tests.ps1
    manager.docker.Integration.Tests.ps1
    manager.podman.Integration.Tests.ps1
tools/
  wsl-manager/
    wsl-manager.ps1               # Tool entry point (sources lib/wsl/)
    wsl-manager.bat               # Batch wrapper

The tools/pslib/ and tools/install/ directories are eliminated entirely.

Key design decisions

  1. commands.ps1 and manager.ps1 stay in lib/wsl/ — they are implementation code, not entry points. Only entry scripts (wsl-manager.ps1) and batch wrappers (.bat) belong in tools/.

  2. install-npm-global.bat is removed — pwsh is a prerequisite for this project; the .bat wrapper adds no value for a library function.

  3. tools/pslib/AGENTS.md content is merged into root AGENTS.md — the library-specific guidelines (Set-StrictMode in dot-sourced files, Pester patterns, SOLID principles) are already partially duplicated in the root. Post-move, a single AGENTS.md with a clear "Library Development" section is cleaner.

  4. Shell scripts (scripts/) stay with the library — install-docker.sh, install-podman.sh, and setup-proxy.sh are invoked by library functions (docker.ps1, podman.ps1, proxy.ps1), not by the tool directly.

Impact analysis

~167 path references across the codebase need updating:

Category Files affected References
Dot-source paths (external → pslib) 5 files ~5 refs
Dot-source paths (internal lib-to-lib) 12 files ~20 refs
Test file sourcing (BeforeAll blocks) 11 files ~15 refs
Documentation (AGENTS.md, README.md, docs/) 6 files ~50 refs
Skill files (.claude/skills/) 12 files ~40 refs
Backlog items (docs/backlog/) 18 files ~30 refs
Test runner / test infra (test/) 2 files ~5 refs
Copilot instructions (.github/) 1 file ~1 ref
Batch wrappers 1 file ~1 ref
Total ~68 files ~167 refs

Suggested implementation order

  1. Create lib/ directory structure — lib/utils/, lib/wsl/, lib/wsl/scripts/, lib/install/
  2. Move library files — utils/, WSL modules, scripts, tests → lib/
  3. Move tool entry points — wsl-manager.ps1, .bat → tools/wsl-manager/; commands.ps1, manager.ps1 + tests stay in lib/wsl/
  4. Move npm installer — tools/install/install-npm-global.ps1 → lib/install/, remove .bat
  5. Update all dot-source paths in PowerShell files (library internal + external consumers)
  6. Update documentation paths — AGENTS.md, README.md, docs/wsl-manager.md, docs/development-principles.md
  7. Merge tools/pslib/AGENTS.md into root AGENTS.md
  8. Update skill references — all .claude/skills/ files
  9. Update backlog item paths — docs/backlog/ (done items are historical, only update todo/in_progress items)
  10. Update copilot instructions — .github/copilot-instructions.md
  11. Remove tools/pslib/ and tools/install/ directories
  12. Run full test suite — verify all unit and integration tests pass
  13. Update other open backlog items that reference old paths (sc-006, sc-016, sc-017)

Risks and considerations

  • Large number of file moves — use git mv to preserve history
  • Dot-source path changes are runtime-breaking — if any path is missed, scripts will fail at load time. A systematic search-and-replace approach is safer than manual editing.
  • Backlog done items contain historical paths — these should generally NOT be updated (they document what was true at the time). Only update open/in-progress items.
  • Other open backlog items (sc-006, sc-016, sc-017) reference tools/pslib/ paths and need updating as part of this work.
  • Skill file accuracy is critical — skills are used by AI agents and incorrect paths will cause agent failures.

Acceptance Criteria:

  • lib/ top-level directory created
  • tools/pslib/utils/ moved to lib/utils/
  • tools/pslib/wsl/lib/ library files (modules + unit tests) moved to lib/wsl/
  • tools/pslib/wsl/scripts/ moved to lib/wsl/scripts/
  • tools/pslib/wsl/wsl-manager.ps1 and .bat moved to tools/wsl-manager/
  • tools/pslib/wsl/lib/commands.ps1, manager.ps1 and their tests moved to lib/wsl/ (implementation code stays in lib, not tools)
  • tools/pslib/wsl/lib/manager.*.Integration.Tests.ps1 moved to lib/wsl/ (co-located with library code they test)
  • wsl.Integration.Tests.ps1 moved from tools/wsl-manager/ to lib/wsl/ (library test belongs with library)
  • tools/install/install-npm-global.ps1 moved to lib/install/
  • tools/install/install-npm-global.bat removed
  • tools/pslib/AGENTS.md content merged into root AGENTS.md
  • tools/pslib/CLAUDE.md removed
  • tools/pslib/ directory eliminated
  • tools/install/ directory eliminated
  • All internal dot-source paths updated (~35 references in ~17 PS1 files)
  • All documentation paths updated (AGENTS.md, README.md, docs/wsl-manager.md, docs/development-principles.md)
  • All skill references updated (~40 references across 12 skill files in .claude/skills/)
  • Copilot instructions updated (.github/copilot-instructions.md)
  • Open backlog items updated (sc-006, sc-016, sc-017, sc-020)
  • .bat wrapper path updated (tools/wsl-manager/wsl-manager.bat)
  • All existing unit tests pass
  • All existing integration tests pass

← Back to Backlog