jao 0.3.3

Discover and run workspace scripts from a simple CLI
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170

<img width="431" height="204" alt="image" src="https://github.com/user-attachments/assets/0bd4e72a-8690-4bc3-a21c-5bdb7a4a301f" />
<br />

`jao` finds repo scripts and lets you run them by name.

It is meant for repos that already have shell or batch scripts and want a thin CLI on top, not a bigger task runner.

## Installation

Just run `cargo install jao` ;)

## What It Does

- Finds runnable scripts under the directory you start from
- Matches `.sh` on Unix and `.bat` on Windows
- Lets you run scripts by command parts instead of file paths
- Respects `.gitignore` during discovery
- Supports `.jaofolder` to expose directory names in commands
- Supports recursive `.jaoignore` files to hide scripts or whole areas
- Supports trust prompts for local use and fingerprints for CI

**`jao` runs scripts from the script's own directory, so existing scripts that rely on relative paths keep working.**

## Example 1: Basic Use

Repo:

```text
scripts/
  check.sh
  test.integration.sh
  db.reset.local.sh
```

Commands:

```bash
jao check
jao test integration
jao db reset local
jao --list
```

This is the default model: command parts map to script stems like `check`, `test.integration`, and `db.reset.local`.

## Example 2: `.jaofolder` In A Multi-Project Repo

Repo:

```text
apps/
  .jaofolder
  frontend/
    .jaofolder
    scripts/
      build.sh
      dev.sh
  backend/
    .jaofolder
    scripts/
      build.sh
      dev.sh
```

From the repo root:

```bash
jao apps frontend dev
jao apps backend build
```

From inside `apps/`:

```bash
jao frontend dev
jao backend build
```

From inside `apps/backend/`:

```bash
jao dev
jao build
```

Use this when multiple projects have the same script names and you want commands to get shorter as you move deeper into the repo.

## Example 3: `.jaoignore` For Internal Or Throwaway Scripts

Repo:

```text
.jaoignore
scripts/
  check.sh
scratch/
  scripts/
    one-off-fix.sh
services/
  api/
    .jaofolder
    .jaoignore
    scripts/
      migrate.dev.sh
      seed.dev.sh
```

Root `.jaoignore`:

```text
scratch/
```

`services/api/.jaoignore`:

```text
seed.dev.sh
```

Result:

- `scratch/` is not walked at all
- `seed.dev.sh` is hidden from `jao --list`
- `migrate.dev.sh` still resolves normally

Use this when a repo contains one-off maintenance scripts, experiments, or internal scripts that should not be part of the public command surface.

## Example 4: Fingerprinting In CI

Print the fingerprint for a script:

```bash
jao --fingerprint db reset local
```

Use that value in CI:

```bash
jao --ci --require-fingerprint <FINGERPRINT> db reset local
```

That gives CI an exact content check instead of trusting whatever script happens to be present.

For local interactive use, `jao` keeps a trust manifest under `~/.jao/`:

- unknown scripts ask before running
- modified scripts ask again

## Install from source

```bash
cargo install --path .
```

During development:

```bash
cargo run -- --list
```

## Docker

```bash
docker build -t jao .
docker run --rm -it -v "$PWD:/workspace" -w /workspace jao --list
```

## License

Apache-2.0