@oprt/cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OPERATOR contributors
+
+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

@@ -1,3 +1,92 @@
-# Temporary Holding Version
+# OPERATOR source installer
 
-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.
+`@oprt/cli` provides the `oprt` executable for Node.js 22 and newer.
+`npx @oprt/cli add button` runs it without installing anything.
+It ships source bundles for every `@oprt/react` component family and every
+operational recipe.
+
+```sh
+oprt list
+oprt list --json
+oprt add button filter-bar --out src/operator
+oprt add asset-management --dry-run
+oprt add Button --out src/operator --overwrite
+```
+
+## For coding agents
+
+```sh
+oprt init --agent claude
+oprt search "table with selection"
+oprt component DataGrid --dense
+oprt component --list
+oprt check src
+oprt doctor
+oprt mcp
+```
+
+`init` writes a block of instructions (house rules, one line per component, the recipes)
+into the file an agent reads on every turn: `AGENTS.md` by default, `CLAUDE.md` or
+`.cursor/rules/operator.mdc` with `--agent`, any file inside the project with `--path`.
+Running it again replaces only the block. `search` ranks components and recipes by need.
+`component` prints one component's props, what each option value is for, its nesting rules
+and its example. `check` reads `.tsx` and `.jsx` files with the project's own TypeScript and
+reports invalid option values, unknown exports, forbidden nesting, missing required props
+and breaks of the house rules; it exits `1` on an error. `doctor` checks the project's
+setup. `mcp` serves the lookups and the check over the Model Context Protocol on stdin and
+stdout, with no dependencies.
+
+Each of these takes `--json` and answers `{ "apiVersion": 1, "type": "…", "data": … }`. A
+failure is `{ "apiVersion": 1, "error": "…", "code": "ERR_…", "suggestions": […] }`; codes
+are stable and only ever added to. All of it is drawn from `dist/contract.json`, which ships
+beside the registry: the component contract, its guidance and the names
+`@oprt/react` exports. `@oprt/cli/read` exports the readers without the
+registry, for building pages from the same contract.
+
+## Copying source
+
+Names accept PascalCase or kebab-case. The default output directory is
+`src/components/operator`. For example, `add button --out src/operator` creates
+`src/operator/Button/Button.tsx`, its index and manifest, and the support files it
+imports. Multiple requested entries share one deduplicated set of source files.
+Copied TSX files retain or receive a `"use client"` boundary.
+
+Run the command from the consumer project. Output must be a relative directory
+inside that working directory. Absolute paths, traversal, and symlink ancestors
+or file targets are rejected. The complete request is checked before writes:
+different existing files cause an error unless `--overwrite` is set; identical
+files are skipped. `--dry-run` reports the planned files without creating files
+or directories, and still reports conflicts that would prevent installation.
+
+The package ships its registry once, as `dist/registry.json`, and `bin.js` and
+the library read it from beside themselves. The executable therefore needs
+neither this repository nor the network, but it cannot be copied away from that
+file. It reports external source dependencies, each with the version range the
+sources were verified against, and the React/Tailwind/token setup. Packages that
+the copied source imports only for their types (React Aria, for a text input) are
+listed separately as dev dependencies. Install missing dependencies yourself,
+make sure Tailwind scans your output directory (Tailwind 4 does inside your
+project; add an `@source` line for one outside it), and load OPERATOR's token CSS. The
+installer does not run package managers or change your package configuration.
+Recipe imports from `@oprt/react` remain package imports.
+
+`list --json` returns `{ "version": "…", "entries": […], "ranges": {…} }`. Each
+entry includes `name`, `slug`, `kind` (`component` or `recipe`), `description`,
+`files`, `dependencies` (every external package its source imports) and
+`devDependencies` (the subset imported only for types). `ranges` maps each
+external package to its version range. `--version` uses the package version. Exit codes are `0` for
+success, `2` for usage errors or unknown entries, and `1` for file conflicts or
+other execution failures.
+
+The library exports `registry`, `VERSION`, `parseArgs`, `resolveEntries`, and
+`install`, with their TypeScript contracts. `install(options, { cwd })` supports
+the same names, output directory, dry-run, and overwrite options as the command.
+
+## Development
+
+The build consumes the aggregated manifest and current React sources. Run the
+workspace build to prepare those inputs, then use this package's `build`, `test`,
+`typecheck`, and `lint` scripts. Registry generation follows actual relative
+imports and exports, includes each dependency family's index and manifest, and
+validates each recipe's local source bundle. Tests execute the built binary from
+temporary consumer directories.