Skip to content

Commit b0f80f0

Browse files
dean0xDean Sharon
dean0x
and
Dean Sharon
authored
Prepare v0.1.1 launch release (#2)
* Prepare v0.1.1 launch release - Fix install.sh to download from GitHub Releases with version override and fallback - Overhaul README with badges, demo GIF placeholder, "Why Mars?" section - Extract dev docs into CONTRIBUTING.md - Add CHANGELOG.md (v0.1.0 + v0.1.1) - Add VHS demo tape for recording demo GIF - Add launch kit with platform-specific post drafts (HN, Reddit, X, LinkedIn, Dev.to) - Bump version to 0.1.1 across package.json, build.sh, mars, dist/mars * Fix arithmetic increment with set -e on bash 5.x ((var++)) returns exit code 1 when var is 0 (post-increment evaluates to 0 = false). With set -e, this kills the script on bash 5.x (Ubuntu CI) but not bash 3.2 (macOS). Replace all ((var++)) with var=$((var + 1)) which always returns exit code 0. --------- Co-authored-by: Dean Sharon <deanshrn@gmain.com>
1 parent e7fddf8 commit b0f80f0

24 files changed

+795
-159
lines changed

‎CHANGELOG.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Changelog
2+
3+
## [0.1.1] - 2026-02-19
4+
5+
### Changed
6+
- Install script now downloads from GitHub Releases instead of raw.githubusercontent.com
7+
- README overhaul with demo GIF, badges, and restructured content
8+
9+
### Added
10+
- CONTRIBUTING.md with development and architecture documentation
11+
- CHANGELOG.md
12+
- VHS demo tape for recording demo GIFs
13+
- Launch materials
14+
15+
## [0.1.0] - 2026-02-16
16+
17+
### Added
18+
- Workspace initialization (`mars init`)
19+
- Repository management (`add`, `clone`, `list`)
20+
- Git operations (`status`, `branch`, `checkout`, `sync`)
21+
- Cross-repo command execution (`mars exec`)
22+
- Tag-based filtering for all operations
23+
- Parallel cloning (4 concurrent jobs)
24+
- Shared Claude configuration (`claude.md`, `.claude/`)
25+
- Clack-style terminal UI with Unicode/ASCII fallback
26+
- Distribution via npm, Homebrew, and curl installer

‎CONTRIBUTING.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# Contributing to Mars
2+
3+
## Development Setup
4+
5+
Clone the repo and run directly in development mode:
6+
7+
```bash
8+
git clone https://github.com/dean0x/mars.git
9+
cd mars
10+
./mars init # Sources from lib/ directory
11+
```
12+
13+
## Project Structure
14+
15+
```
16+
mars/
17+
├── mars # Main CLI entry point
18+
├── lib/
19+
│ ├── ui.sh # Terminal UI (colors, spinners, prompts, tables)
20+
│ ├── yaml.sh # mars.yaml parser
21+
│ ├── config.sh # Workspace detection and config loading
22+
│ ├── git.sh # Git wrapper with output capture
23+
│ └── commands/ # Command implementations
24+
│ ├── init.sh
25+
│ ├── clone.sh
26+
│ ├── status.sh
27+
│ ├── branch.sh
28+
│ ├── checkout.sh
29+
│ ├── sync.sh
30+
│ ├── exec.sh
31+
│ ├── add.sh
32+
│ └── list.sh
33+
├── build.sh # Build bundled distribution
34+
├── install.sh # Curl installer
35+
├── dist/ # Bundled distribution (committed)
36+
└── test/ # Test suite
37+
```
38+
39+
## Architecture
40+
41+
### Two Operating Modes
42+
43+
- **Development**: `./mars` sources files from `lib/` subdirectories
44+
- **Distribution**: `dist/mars` is a single bundled file with all code inlined
45+
46+
### Key Patterns
47+
48+
**Output Capture** — Git operations capture output in globals:
49+
50+
```bash
51+
GIT_OUTPUT=""
52+
GIT_ERROR=""
53+
if git_clone "$url" "$path"; then
54+
# success: use GIT_OUTPUT
55+
else
56+
# failure: use GIT_ERROR
57+
fi
58+
```
59+
60+
**Bash 3.2 Compatibility** — No associative arrays; uses parallel indexed arrays:
61+
62+
```bash
63+
YAML_REPO_URLS=()
64+
YAML_REPO_PATHS=()
65+
YAML_REPO_TAGS=()
66+
```
67+
68+
**Tag Filtering** — Comma-separated tags with string matching:
69+
70+
```bash
71+
[[ ",$tags," == *",$filter_tag,"* ]]
72+
```
73+
74+
**Command Pattern** — Each command is `cmd_<name>()` in its own file under `lib/commands/`.
75+
76+
### Implementation Constraints
77+
78+
- Bash 3.2+ (macOS default) — no associative arrays, no `readarray`
79+
- Return exit codes, never throw (bash has no exceptions)
80+
- Avoid subshells where possible (breaks global variable updates)
81+
- Check return codes explicitly and propagate errors
82+
- Use `ui_step_error()`/`ui_step_done()` for user feedback
83+
- Parallel operations limited to 4 concurrent jobs (`CLONE_PARALLEL_LIMIT`)
84+
85+
## Running Tests
86+
87+
```bash
88+
bash test/test_yaml.sh
89+
bash test/test_config.sh
90+
bash test/test_integration.sh
91+
```
92+
93+
Tests use `/tmp/claude/` for temporary files.
94+
95+
## Building
96+
97+
```bash
98+
./build.sh # Output: dist/mars
99+
```
100+
101+
**Important:** `dist/mars` is committed to the repo for easy installation. Always run `./build.sh` before committing changes to source files.
102+
103+
## Pull Requests
104+
105+
- Run all tests before submitting
106+
- Run `./build.sh` and include the updated `dist/mars`
107+
- Maintain bash 3.2 compatibility (test on macOS if possible)
108+
- Follow existing code patterns (output capture, parallel arrays, command pattern)
109+
110+
## Release Process
111+
112+
1. Update version in `package.json`
113+
2. Commit: `git commit -am "Bump version to X.Y.Z"`
114+
3. Tag: `git tag vX.Y.Z`
115+
4. Push: `git push origin main --tags`
116+
117+
CI automatically handles:
118+
119+
- Run tests
120+
- Verify tag version matches `package.json`
121+
- Create GitHub Release with `dist/mars` binary attached
122+
- Publish to npm (`@dean0x/mars`)
123+
- Update Homebrew formula (`dean0x/tap/mars`)
124+
125+
### Required Secrets (Maintainers)
126+
127+
| Secret | Repository | Purpose |
128+
|--------|------------|---------|
129+
| `NPM_TOKEN` | mars | npm publish access token |
130+
| `HOMEBREW_TAP_TOKEN` | mars | PAT with repo scope for homebrew-tap workflow |

‎README.md‎

Lines changed: 60 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -1,83 +1,46 @@
1-
# Mars CLI
1+
# Mars
22

3-
Multi Agentic Repo workspace manager for git repositories with shared Claude configuration.
3+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
4+
[![npm](https://img.shields.io/npm/v/@dean0x/mars)](https://www.npmjs.com/package/@dean0x/mars)
5+
[![CI](https://github.com/dean0x/mars/actions/workflows/ci.yml/badge.svg)](https://github.com/dean0x/mars/actions/workflows/ci.yml)
46

5-
## Features
7+
Manage multiple Git repositories as one workspace.
68

7-
- Manage multiple git repos as a unified workspace
8-
- Shared `claude.md` and `.claude/` config across repos
9-
- Tag-based repo filtering for targeted operations
10-
- Parallel cloning with rate limiting
11-
- Works with bash 3.2+ (macOS compatible)
9+
Tag-based filtering, parallel operations, shared Claude configuration.
1210

13-
## Installation
14-
15-
### npm (recommended)
16-
17-
```bash
18-
npm install -g @dean0x/mars
19-
```
20-
21-
Or run without installing:
22-
23-
```bash
24-
npx @dean0x/mars --help
25-
```
11+
<p align="center">
12+
<img src="demo.gif" alt="Mars CLI demo" width="800" />
13+
</p>
2614

27-
### Homebrew (macOS/Linux)
15+
## Why Mars?
2816

29-
```bash
30-
brew install dean0x/tap/mars
31-
```
17+
- **Polyrepo without the pain** — one CLI for status, branching, syncing across all repos
18+
- **Tag-based filtering** — target subsets of repos (`--tag frontend`, `--tag backend`)
19+
- **Shared Claude config** — `claude.md` and `.claude/` directory shared across repos
20+
- **Zero dependencies** — pure bash 3.2+, works on macOS out of the box
3221

33-
### Shell Script
22+
## Quick Install
3423

3524
```bash
36-
curl -fsSL https://raw.githubusercontent.com/dean0x/mars/main/install.sh | bash
25+
npm install -g @dean0x/mars
3726
```
3827

39-
### Manual
40-
41-
```bash
42-
git clone https://github.com/dean0x/mars.git
43-
cd mars
44-
./build.sh
45-
cp dist/mars ~/.local/bin/ # or anywhere in PATH
46-
```
28+
See [all installation methods](#installation) for Homebrew, curl, and manual options.
4729

4830
## Quick Start
4931

5032
```bash
51-
# Create a new workspace
5233
mkdir my-project && cd my-project
5334
mars init
5435

55-
# Add repositories
56-
mars add git@github.com:org/frontend.git --tags frontend,web
57-
mars add git@github.com:org/backend.git --tags backend,api
58-
mars add git@github.com:org/shared.git --tags shared
36+
mars add https://github.com/dean0x/mars-example-frontend.git --tags frontend,web
37+
mars add https://github.com/dean0x/mars-example-backend.git --tags backend,api
38+
mars add https://github.com/dean0x/mars-example-shared.git --tags shared
5939

60-
# Clone all repos
6140
mars clone
62-
63-
# Check status
6441
mars status
6542
```
6643

67-
## Workspace Structure
68-
69-
```
70-
my-project/
71-
├── mars.yaml # Workspace configuration
72-
├── claude.md # Shared Claude config (optional)
73-
├── .claude/ # Shared Claude folder (optional)
74-
├── .gitignore # Contains 'repos/'
75-
└── repos/ # Cloned repositories (gitignored)
76-
├── frontend/
77-
├── backend/
78-
└── shared/
79-
```
80-
8144
## Commands
8245

8346
| Command | Description |
@@ -128,62 +91,64 @@ defaults:
12891
branch: main
12992
```
13093
131-
## Development
132-
133-
### Project Structure
94+
## Workspace Structure
13495
13596
```
136-
mars/
137-
├── mars # Main CLI entry point
138-
├── lib/
139-
│ ├── ui.sh # Terminal UI components
140-
│ ├── yaml.sh # YAML parser
141-
│ ├── config.sh # Config management
142-
│ ├── git.sh # Git operations
143-
│ └── commands/ # Command implementations
144-
├── build.sh # Build distribution
145-
├── install.sh # Installer script
146-
└── test/ # Test suite
97+
my-project/
98+
├── mars.yaml # Workspace configuration
99+
├── claude.md # Shared Claude config (optional)
100+
├── .claude/ # Shared Claude folder (optional)
101+
├── .gitignore # Contains 'repos/'
102+
└── repos/ # Cloned repositories (gitignored)
103+
├── frontend/
104+
├── backend/
105+
└── shared/
106+
```
107+
108+
## Installation
109+
110+
### npm (recommended)
111+
112+
```bash
113+
npm install -g @dean0x/mars
147114
```
148115

149-
### Running Tests
116+
Or run without installing:
150117

151118
```bash
152-
# Run all tests
153-
bash test/test_yaml.sh
154-
bash test/test_config.sh
155-
bash test/test_integration.sh
119+
npx @dean0x/mars --help
156120
```
157121

158-
### Building
122+
### Homebrew (macOS/Linux)
159123

160124
```bash
161-
./build.sh # Output: dist/mars
125+
brew install dean0x/tap/mars
162126
```
163127

164-
**Important:** `dist/mars` is committed for easy installation. Always run `./build.sh` before committing changes to source files.
128+
### Shell Script
129+
130+
```bash
131+
curl -fsSL https://raw.githubusercontent.com/dean0x/mars/main/install.sh | bash
132+
```
165133

166-
## Releasing
134+
Install a specific version:
167135

168-
Releases are automated via GitHub Actions. To create a release:
136+
```bash
137+
MARS_VERSION=0.1.1 curl -fsSL https://raw.githubusercontent.com/dean0x/mars/main/install.sh | bash
138+
```
169139

170-
1. Update version in `package.json`
171-
2. Commit the change
172-
3. Create and push a tag: `git tag v0.1.1 && git push origin v0.1.1`
140+
### Manual
173141

174-
The CI will automatically:
175-
- Run tests
176-
- Verify the tag version matches `package.json`
177-
- Create a GitHub Release with auto-generated notes
178-
- Publish to npm
179-
- Update the Homebrew formula
142+
```bash
143+
git clone https://github.com/dean0x/mars.git
144+
cd mars
145+
./build.sh
146+
cp dist/mars ~/.local/bin/ # or anywhere in PATH
147+
```
180148

181-
### Required Secrets (for maintainers)
149+
## Contributing
182150

183-
| Secret | Repository | Purpose |
184-
|--------|------------|---------|
185-
| `NPM_TOKEN` | mars | npm publish access token |
186-
| `HOMEBREW_TAP_TOKEN` | mars | PAT with repo scope to trigger homebrew-tap workflow |
151+
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, architecture, and release process.
187152

188153
## License
189154

‎build.sh‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ cat > "$OUTPUT_FILE" << 'HEADER'
1919
2020
set -euo pipefail
2121
22-
MARS_VERSION="0.1.0"
22+
MARS_VERSION="0.1.1"
2323
2424
HEADER
2525

0 commit comments

Comments
 (0)