@oprt/cli 0.1.0 → 0.3.0

package/README.md

@@ -28,20 +28,38 @@ 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.
+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.
 
-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.
+`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
 
@@ -62,21 +80,28 @@ 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
+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,
-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.
+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` returns `{ "version": "…", "entries": […], "ranges": {…} }`. Each
+`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. `--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.
+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