@nomai/nomai 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nomai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# nomai
+
+Installer CLI for **Nomai** — skills, commands, and hooks for AI coding
+harnesses (Claude Code first; Codex, Cursor, Gemini CLI, ... later).
+
+```
+npx @nomai/nomai install
+```
+
+An interactive wizard (built on [@clack/prompts](https://github.com/bombshell-dev/clack))
+detects which harnesses you use, asks whether to install per-project or
+globally, then downloads the Nomai payload from this repo and installs it.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `npx @nomai/nomai install` | Wizard: pick harnesses + scope, then install |
+| `npx @nomai/nomai update` | Re-apply the latest payload to existing installs (never prompts) |
+| `npx @nomai/nomai status [--json]` | Show detection/install/drift state per harness × scope (never prompts) |
+| `npx @nomai/nomai uninstall` | Remove exactly the files Nomai installed |
+
+Useful flags (all commands): `--harness <id>` (repeatable), `--scope project|global`,
+`--dir <path>`. Install/update also take `--source <path|owner/repo#ref>` (payload
+override), `--dry-run`, `--force`, and `-y/--yes` for CI. Non-interactive sessions
+(pipes, CI, AI agents) exit with code 2 unless `--yes` is passed — the CLI never
+hangs on a prompt.
+
+## How it works
+
+- The npm package is a single bundled `dist/cli.js` with **zero runtime
+  dependencies** (`@clack/prompts`, `commander`, and `@vercel/detect-agent` are
+  inlined at build time).
+- The installable payload lives in [`payload/`](payload/README.md) in this repo
+  and is downloaded at install time as a GitHub tarball — pushing to `main`
+  ships payload updates without an npm release.
+- Every install writes a `nomai-manifest.json` receipt (file list + sha256)
+  into the harness config dir. That receipt makes installs idempotent, updates
+  orphan-safe, and uninstalls surgical: Nomai only ever deletes files it wrote,
+  keeps files you modified (unless `--force`), and never removes the harness
+  dir itself.
+
+## Development
+
+```
+npm install
+npm run dev -- install --dry-run --source .   # run the CLI from source
+npm test                                      # vitest
+npm run typecheck                             # tsc --noEmit
+npm run build                                 # tsdown → dist/
+```
+
+`--source .` points the installer at your local checkout instead of GitHub.
+Without it, the payload comes from
+[A-MCode/nomai-installer](https://github.com/A-MCode/nomai-installer) at `main`
+(`DEFAULT_SOURCE` in `src/core/payload.ts`).
+
+## Adding a harness
+
+1. Create `src/harnesses/<id>.ts`:
+
+   ```ts
+   import { defineHarness } from "./define.js";
+
+   export const codex = defineHarness({
+     id: "codex",
+     displayName: "Codex CLI",
+     configDirName: ".agents",
+   });
+   ```
+
+2. Register it in `src/harnesses/index.ts` (one line).
+3. Optionally add `payload/<id>/` for harness-specific files.
+
+Defaults cover detection (config dir exists at project/global scope), install
+location, and file copying. Override `transformPayload` for per-harness
+compilation, or `install`/`uninstall`/`status` wholesale for harnesses that
+need custom mechanics (e.g. merging hooks into a `settings.json`).
+
+## Architecture
+
+```
+src/
+├── cli.ts                 # bin entry: commander program (install/update/status/uninstall)
+├── index.ts               # public API for programmatic use
+├── commands/              # one file per subcommand + shared flag/context helpers
+├── wizard/                # the @clack/prompts install wizard (flag-bypassable)
+├── core/
+│   ├── types.ts           # HarnessAdapter contract + all shared types
+│   ├── registry.ts        # harness lookup
+│   ├── detect.ts          # which harnesses does this user have?
+│   ├── payload.ts         # payload sources: GitHub tarball / local path
+│   ├── installer.ts       # generic engine — the only module that writes to disk
+│   └── manifest.ts        # install receipts (idempotency, updates, clean uninstall)
+├── harnesses/             # defineHarness() factory + one adapter per harness
+└── test-utils/            # temp-dir fixtures for tests
+payload/                   # the installable content (fetched from GitHub, not npm)
+```