@ovrdev/cli 0.1.0-alpha.16

package/README.md

@@ -0,0 +1,111 @@
+# Override (`ovr`)
+
+**Development environments as code.** One command boots your whole multi-repo local stack —
+every service, every port, every worktree — wired together and health-gated from a single typed
+config.
+
+> **Agents drive fast; don't let them crash.** Multiple agents (or people) work the same project in
+> parallel, each in its own isolated workspace, without fighting over ports, hand-managing
+> worktrees, or stepping on each other. The tool handles it.
+
+> ⚠️ Alpha. APIs may still shift between `0.1.0-alpha.*` releases.
+
+## Quickstart
+
+The fastest way to see it is the [ovr-guestbook](https://github.com/msanchezdev/ovr-guestbook) demo —
+two zero-dependency services booted by one command:
+
+```bash
+git clone https://github.com/msanchezdev/ovr-guestbook && cd ovr-guestbook
+npm install
+npx ovr run
+```
+
+Open the `web` URL it prints, then quit (`qq`) and `npx ovr run` again — your data is still there.
+
+### In your own repo
+
+```bash
+npm i -D @ovrdev/cli
+```
+
+Add an `ovr.config.mts`:
+
+```ts
+import { defineConfig, waitHttp } from "@ovrdev/cli"
+
+export default defineConfig(({ workspace, kind }) => ({
+  services: {
+    api: kind.shell({
+      prepare: async ({ ports }) => ({ port: await ports.alloc() }), // a free port, sticky
+      command: ({ port }) => `PORT=${port} node server.mjs`,
+      exports: ({ port }) => ({ url: `http://localhost:${port}`, port }),
+      ready: ({ port }) => waitHttp(`http://localhost:${port}/health`),
+    }),
+    web: kind.shell({
+      prepare: async ({ ports }) => ({ port: await ports.alloc() }),
+      command: ({ port }) => `PORT=${port} vite`,
+      env: { API_URL: workspace.services.api.url }, // auto-wired to api's real port
+    }),
+  },
+}))
+```
+
+Then `npx ovr run`. In a fresh folder ovr auto-onboards it — no setup step.
+
+## Concepts
+
+- **workspace** — a named, runnable config: which repos, at which worktrees, with which env. A
+  **fork** is just another workspace that shares repos on new branches (isolation for a ticket or
+  an agent). **repos** feed a workspace; a base repo runs **in place** (your folder), fork worktrees
+  live under the ovr root.
+- **services & kinds** — a service is declared with a *kind*: `kind.shell` (a process) builtin, plus
+  plugin kinds (`kind.docker.*`, supabase, …). `prepare(ctx)` reserves resources and returns a
+  "bag"; `command`/`env`/`exports` are pure functions of it.
+- **zero fixed ports** — every service allocates its own port; cross-service **refs**
+  (`workspace.services.x.url`, `workspace.repos["y"].services.z.url`) resolve to the real
+  allocations, known before anything starts. Refs carry any JSON value.
+- **readiness** — `ready: waitHttp(...)` gates dependents; `waitFor: [x.ready]` for explicit edges.
+- **provisioning helpers** in `prepare` — everything sticky per environment: `ports`, `secrets`
+  (generated passwords/tokens), `paths` (data dirs that survive restarts), `scratch` (ephemeral),
+  `keys` (crypto keypairs → `.jwks()`/`.ssh()`), `files.render` (templated config), `once`
+  (run-once provisioning), `env` (fail-fast base-env access).
+- **shared services** — `ovr run` runs every repo with a config and **reuses** anything already up
+  (`ovr ps` to see across sessions); a shared service stays up until its last consumer leaves
+  (`ovr stop` to force it).
+- **discovery** — a service pushes to another: `x.announce({ redirect: url })`; the provider
+  reconciles the live set via `discovery: (anns) => …` (allowlists, CORS, redirect URIs).
+- **env sources** — base env from plugins: `dotenv()` builtin, `@ovrdev/plugin-infisical`,
+  … layered per repo. `ovr run --env <name>` picks the environment (sticky per workspace).
+- **interactive actions** — TUI actions with typed input forms: `action.session`/`action.fn`/
+  `action.handover` + `input.*`; `login: true` runs through your shell profile.
+
+## CLI
+
+```
+ovr run [-w <workspace>] [--env <name>]   boot the workspace (auto-onboards a fresh repo)
+ovr ps                                    services running across all sessions
+ovr stop <name|--all>                     stop running services
+ovr workspace new|ls|use|rm  (alias: ws)  manage workspaces
+ovr fork <name> [--repos a,b|--all]       fork a workspace, pick repos to materialize
+ovr repo add|override|rm                  manage a workspace's repos
+```
+
+## Packages
+
+| package | what |
+| --- | --- |
+| [`@ovrdev/cli`](https://npmjs.com/package/@ovrdev/cli) | the framework + `ovr` CLI + TUI |
+| [`@ovrdev/plugin-portless`](https://npmjs.com/package/@ovrdev/plugin-portless) | stable `https://*.localhost` URLs |
+| [`@ovrdev/plugin-docker`](https://npmjs.com/package/@ovrdev/plugin-docker) | compose / container kinds |
+| [`@ovrdev/plugin-infisical`](https://npmjs.com/package/@ovrdev/plugin-infisical) | Infisical hosted env source |
+| [`@ovrdev/plugin-supabase`](https://npmjs.com/package/@ovrdev/plugin-supabase) | local Supabase stack kind (`kind.supabase.stack`) |
+| [`@ovrdev/plugin-js`](https://npmjs.com/package/@ovrdev/plugin-js) | ensure deps + run package scripts (`node()`) |
+| [`@ovrdev/plugin-postgres`](https://npmjs.com/package/@ovrdev/plugin-postgres) | local Postgres kind + SQL action builders |
+
+Built into the cli (no extra install): `kind.shell` — the one universal service kind. Everything
+heavier (docker, Supabase, Postgres, …) lives in a plugin, so the core stays primitive.
+
+## License
+
+TBD.