@kaynooo/cli-wt 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Kaynooo <contact@kaynooo.fr>
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,94 @@
1
- # Temporary Holding Version
1
+ # wt
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Git worktrees of a compose project, each with its own stack, its own copy of the data and its own `<task>.<host>` subdomains beside main.
4
+
5
+ ```sh
6
+ bun install -g @kaynooo/cli-wt
7
+ ```
8
+
9
+ `wt add planning` checks the project out on `wt/planning` next to main, copies the gitignored files main needs (env files, certificates), clones its volumes while main's containers are paused, rewrites the hosts in the copied env files to `planning.<host>`, and writes a compose override giving the worktree's routed services their [devproxy](https://git.kaynooo.fr/kaynooo/devproxy) labels. `wt up planning` starts it, `wt rm planning` stops it and deletes everything but its branches.
10
+
11
+ ## Commands
12
+
13
+ | Command | What it does |
14
+ | --- | --- |
15
+ | `wt add <task> [branch]` | creates the worktree on `branch` (`wt/<task>`), copies and clones from main, routes its subdomains |
16
+ | `wt sync [task]` | provisions it again after a manifest change |
17
+ | `wt up [task]` / `wt down [task]` | starts or stops its stack |
18
+ | `wt rm <task>` | stops the stack, deletes the checkouts, volumes, certificates and override, keeps the branches; refuses uncommitted changes or commits on no branch unless `--force` |
19
+ | `wt ls` | main and the worktrees of the current project (`-a` every project), with their changed files |
20
+ | `wt path [task]` | the directory of a worktree, or of main |
21
+ | `wt init [dir]` | drafts a manifest from the compose project in `dir` into the manifests folder (`--print` to stdout) |
22
+ | `wt run <task> -- <cmd>` | runs a command in a throwaway container of the manifest's `run.service`, against a test database of the worktree's own |
23
+ | `wt heavy -- <cmd>` | runs a command once the heavy ones queued before it, from any session, are done |
24
+ | `wt shell fish` | the shell function giving `wt cd <task>`, and `wt rm` leaving the folder it removed |
25
+
26
+ A task defaults to the worktree the current directory is in, and `-p <name>` picks the project when the current directory is in none. `add`, `rm`, `up` and `down` take `--bg` to run detached, ending with a desktop notification. One action runs per stack at a time: a second one is refused, naming what holds it.
27
+
28
+ Put `wt shell fish | source` in `config.fish` for `wt cd`.
29
+
30
+ ## Manifests
31
+
32
+ One file per project in `~/.config/wt/projects/<name>.ts`, `wt init` writing a first draft:
33
+
34
+ ```ts
35
+ import type { ProjectConfig } from '@kaynooo/cli-wt'
36
+
37
+ export default {
38
+ root: '~/Workspace/times',
39
+ repos: [],
40
+ copy: ['.env', 'api/.env.local', '.docker/nginx/certs'],
41
+ clone: ['mailpit'],
42
+ certs: '.docker/nginx/certs',
43
+ setup: ['docker compose exec -T api-php composer install'],
44
+ routes: [
45
+ { host: 'times.localhost', to: 'client' },
46
+ { host: 'api.times.localhost', to: 'api-php:443', passthrough: true },
47
+ ],
48
+ } satisfies ProjectConfig
49
+ ```
50
+
51
+ | Key | |
52
+ | --- | --- |
53
+ | `root` | the main checkout |
54
+ | `repos` | nested repos put on the task branch; empty when the root itself is the repo |
55
+ | `copy` | gitignored files and folders copied from main, hosts rewritten in the `.env*` ones |
56
+ | `clone` | data each worktree gets its own copy of: a path under root or a named volume's key |
57
+ | `link` | paths shared with main through a symlink |
58
+ | `skip` | services left out of a worktree's stack |
59
+ | `routeHosts` | services that dial the stack's own hosts from inside a container, given the worktree's in `/etc/hosts` |
60
+ | `env` | values forced into copied env files, per file; `{task}` and `{port}` (the dev server's) filled in |
61
+ | `certs` | where the stack's nginx reads certificates, required by passthrough routes |
62
+ | `setup` | `sh -c` commands run in the worktree the first time its stack comes up |
63
+ | `run` | `wt run`'s `service`, `dir`, `provision` commands, optional `dns` and `env` |
64
+ | `routes` | `host` main answers on, `to` `client` (the dev server on the host) or `<service>:<port>`, `passthrough` to leave TLS to the stack |
65
+
66
+ ## Config
67
+
68
+ `~/.config/wt/config.ts` (`$WT_CONFIG`), every key optional:
69
+
70
+ ```ts
71
+ import type { WtConfig } from '@kaynooo/cli-wt'
72
+
73
+ export default {
74
+ runner: { up: ['mystack', 'up', '{project}/{task}'] },
75
+ } satisfies WtConfig
76
+ ```
77
+
78
+ | Key | Default | |
79
+ | --- | --- | --- |
80
+ | `manifests` | `<config dir>/projects` | the manifests folder |
81
+ | `worktrees` | `{root}/.worktrees/{repo}` | where a project's worktrees go, `{root}` the main checkout's parent, `{repo}` its folder name |
82
+ | `overrides` | `~/.local/share/wt/overrides` | the generated compose overrides |
83
+ | `state` | `~/.cache/wt` | setup markers, clone progress, queues |
84
+ | `jobs` | `<state>/jobs` | job records and per-stack locks; a tool pointing at the same folder shares the locks |
85
+ | `proxyNetwork` | `proxy` | the network devproxy reaches the stacks on |
86
+ | `runner` | | `up`, `down` and `removed` argv replacing `docker compose up -d --build`, `docker compose down` and nothing; `{project}`, `{task}`, `{dir}` and `{id}` filled in |
87
+
88
+ Without a runner, `wt up` brings devproxy up first when it is installed (on PATH or as this package's dependency), then compose, then the manifest's `setup` once. A runner command that itself runs wt, or another tool sharing the `jobs` folder, works inside the job that started it instead of being refused by its lock.
89
+
90
+ ## Library
91
+
92
+ `import { loadProjects, worktreeOf, Jobs, runSetup } from '@kaynooo/cli-wt'` for tools built on the same manifests: projects and worktrees, compose helpers, the job locks and the setup step.
93
+
94
+ Exit codes: 0 done, 1 refused or failed, 2 a usage error; `wt run` and `wt heavy` exit with the command's code.