@oprt/cli 0.0.0-stage → 0.3.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,117 @@
-# 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
+(`--limit` is a whole number from 1 to 50). `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 (5 or 6; TypeScript 7 has no JavaScript syntax API to read with) and
+reports invalid option values, unknown exports, forbidden nesting, missing required props and breaks
+of the house rules. `doctor` says whether lookups and code checking can run here, one at a time,
+and why checking is blocked when it is. `mcp` serves the lookups and the check over the Model
+Context Protocol on stdin and stdout, with no dependencies.
+
+`check` says how much it read. `evaluation_status` is `evaluated_clean` only when every file was
+read in full and nothing was found; otherwise it is `evaluated_with_findings`,
+`partially_evaluated` (a spread or computed option value it could not read is a limit, recorded
+with its place; or some files did not parse), `not_evaluated` (no file parsed) or
+`no_files_evaluated` (nothing was read, for example a Markdown file). A file that does not parse
+is reported as `SYNTAX_ERROR` findings and is never clean. Types and rendering are not checked.
+Exit codes: `0` when what was read has no errors (warnings fail only with `--strict`; limits do not
+fail the run), `1` for an error, a file that did not parse, no file read, or no usable TypeScript,
+`2` for a usage error or a path that does not exist.
+
+Every command takes `--json`, `list` and `add` included, and answers
+`{ "apiVersion": 1, "type": "…", "identity": {…}, "data": … }`. `identity` keeps four things
+apart: `cli_version` (this package), `contract_version` (the `@oprt/react` version the contract
+describes), `contract_digest` (`sha256:` of `dist/contract.json`) and `schema_version` (this
+result format, the same number as `apiVersion`). A failure is
+`{ "apiVersion": 1, "error": "…", "code": "ERR_…", "suggestions": […], "identity": {…} }`; codes
+are stable and only ever added to. `component --dense --json` is a compact form of the same data.
+`oprt mcp` returns the same envelope as each tool's structured result, with an `outputSchema` on
+every tool (a summary of the full schema, so the tool list is about 5.4 KB); a check that finds problems is a successful call, and a call that could not run is an
+error result. 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. The library exports
+the schemas of every answer as `RESULT_SCHEMAS`.
+
+## 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 then the setup (Tailwind CSS 4, which has no
+presets): install `@oprt/tokens` and `react-dom`, and as dev dependencies `tailwindcss` and
+`@oprt/tailwind`; add `@plugin "@oprt/tailwind";` to the stylesheet that imports Tailwind;
+import `@oprt/tokens` once at the application root. A recipe also imports `@oprt/react`, so its
+stylesheet needs `@source "../node_modules/@oprt/react/dist";` (relative to the stylesheet) or the
+components render unstyled; source copied into your project needs no `@source` line. No copied source needs `@oprt/tokens-operational`. 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. The
+installer does not run package managers or change your package configuration or stylesheet.
+The same setup is `data.setup` in `add --json`. Recipe imports from `@oprt/react` remain package
+imports.
+
+`list --json` answers in the common envelope; its `data` is
+`{ "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. `add --json` answers with the install result
+(`outputDirectory`, `entries`, `dependencies`, `devDependencies`, `ranges`, `files`, `dryRun`)
+and the `setup`. `--version` prints the package version. Exit codes are `0` for
+success, `2` for usage errors, unknown entries or a path that does not exist, and `1` for file
+conflicts or other execution failures; `check` has its own, above.
+
+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.