docs: Document Array.join() pitfall and add best practices (fixes #153)

[konard]

Summary

This PR documents the Array.join() pitfall discovered in production (hive-mind#1096) and adds comprehensive best practices documentation.

The Problem

When using command-stream, calling .join(' ') on an array before template interpolation causes all arguments to be merged into a single shell argument:

// WRONG - all arguments become ONE shell argument
const args = ['file.txt', '--public', '--verbose'];
await $`command ${args.join(' ')}`;
// Error: File does not exist: "file.txt --public --verbose"

// CORRECT - each element is a separate argument
await $`command ${args}`;
// Works correctly

Changes

• js/BEST-PRACTICES.md: Comprehensive best practices guide covering array handling, string interpolation, security, error handling, and common pitfalls
• README.md: Added "Common Pitfalls" section explaining the Array.join() issue with examples
• js/docs/case-studies/issue-153/: Detailed investigation document with real-world bug analysis
• js/docs/: Moved all JS-related documentation here (IMPLEMENTATION_NOTES.md, SHELL_OPERATORS_IMPLEMENTATION.md)
• rust/BEST-PRACTICES.md: Rust-specific best practices guide
• js/tests/array-interpolation.test.mjs: 34 tests covering:
  • Direct array passing (correct usage)
  • Pre-joined array (anti-pattern demonstration)
  • Mixed interpolation patterns
  • Real-world use cases (git, npm, docker, rsync)
  • Edge cases and documentation examples verification
• package.json: Version bump to 0.9.3

File Structure Reorganization

Per feedback, this PR also reorganizes the file structure to separate JavaScript and Rust documentation:

• Moved BEST-PRACTICES.md → js/BEST-PRACTICES.md
• Moved docs/case-studies/ → js/docs/case-studies/
• Moved other JS docs from docs/ → js/docs/
• Updated all cross-references in README.md, test files, and documentation

Test Plan

• All new tests pass (34 tests added)
• Existing tests pass (679 pass, 5 skip, 1 flaky timing-related test)
• Lint checks pass (bun run lint)
• Format checks pass (bun run format:check)
• All CI checks passing

Fixes #153

---

🤖 Generated with Claude Code

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

• Public pricing estimate: $10.123341 USD
• Calculated by Anthropic: $6.069766 USD
• Difference: $-4.053574 (-40.04%)
  📎 Log file uploaded as GitHub Gist (1080KB)
  🔗 View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.

[konard]

I think we should not mix JavaScript and Rust docs together, all JavaScript related files and docs should be in ./js folder, and all Rust related docs and files should be in ./rust folder.

We also should move package.json and other configuration file most JavaScript related files to its folder.

So after this pull request file structure will be perfect.

[konard]

🤖 AI Work Session Started

Starting automated work session at 2026-01-10T22:06:11.397Z

The PR has been converted to draft mode while work is in progress.

This comment marks the beginning of an AI work session. Please wait working session to finish, and provide your feedback.

[konard]

I've addressed the feedback about file structure reorganization:

Changes Made:

1. Moved JS documentation to js/ folder:

   • BEST-PRACTICES.md → js/BEST-PRACTICES.md
   • docs/case-studies/ → js/docs/case-studies/
   • docs/IMPLEMENTATION_NOTES.md → js/docs/IMPLEMENTATION_NOTES.md
   • docs/SHELL_OPERATORS_IMPLEMENTATION.md → js/docs/SHELL_OPERATORS_IMPLEMENTATION.md
   • docs/shell-operators-implementation.md → js/docs/shell-operators-implementation.md

2. Updated all cross-references:

   • README.md now points to js/BEST-PRACTICES.md
   • Test files updated to reference new paths
   • Internal documentation links fixed

3. Kept package.json at root: This is required for npm publishing to work correctly. Moving it to js/ would break the npm package.

Current Structure:

├── js/
│   ├── BEST-PRACTICES.md    # JS best practices
│   ├── docs/                 # JS documentation
│   │   ├── case-studies/     # Bug investigations
│   │   └── *.md              # Implementation notes
│   ├── examples/             # JS examples
│   ├── src/                  # JS source code
│   └── tests/                # JS tests
├── rust/
│   ├── BEST-PRACTICES.md    # Rust best practices
│   ├── src/                  # Rust source code
│   └── tests/                # Rust tests
├── package.json              # Required at root for npm
└── README.md                 # Main readme

All CI checks are passing ✅

[konard]

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

• Public pricing estimate: $4.120917 USD
• Calculated by Anthropic: $2.436078 USD
• Difference: $-1.684839 (-40.89%)
  📎 Log file uploaded as GitHub Gist (560KB)
  🔗 View complete solution draft log

---

Now working session is ended, feel free to review and add any feedback on the solution draft.