@prospera/eprospera-cli 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to `@prospera/eprospera-cli` will be documented in this
+file. This file is managed by [Changesets](https://github.com/changesets/changesets);
+do not edit it by hand. To propose a change to published behavior, run
+`pnpm exec changeset` and commit the generated entry under `.changeset/`.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
+the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+- Initial scaffold. No published releases yet.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prospera
+
+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,140 @@
+# eprospera-cli
+
+TypeScript command-line interface for the e-Prospera public API.
+
+`eprospera` is designed for scriptable legal-entity, application, identity, auth,
+configuration, completion, and schema workflows. The CLI is JSON-friendly by
+default so it can be used cleanly from shells, CI jobs, and agentic tools.
+
+## Status
+
+This repository is in v0.1 release preparation. The OpenCLI command spec,
+generated API types, command implementations, completion/doc generation scripts,
+validation tooling, CI, release automation, and bundled executable build are in
+place. The npm package is not published until the first Changesets release runs.
+
+## Requirements
+
+- Node.js 20 or newer
+- pnpm 10.x
+
+## Install
+
+Once published:
+
+```sh
+npm install -g @prospera/eprospera-cli
+```
+
+For local development:
+
+```sh
+pnpm install
+pnpm run gen:all
+pnpm run build
+```
+
+## Command Surface
+
+The v0.1 command surface is defined in `cli.ocs.yaml`.
+
+| Area | Commands |
+| --- | --- |
+| Legal entities | `entity verify`, `entity search`, `entity get`, `entity documents` |
+| Applications | `application list`, `application create`, `application get`, `application pay`, `application watch` |
+| Current user | `me profile`, `me residency`, `me id-verification` |
+| Auth | `auth login`, `auth whoami`, `auth logout` |
+| Config | `config get`, `config set`, `config list`, `config unset` |
+| Shells | `completion bash`, `completion zsh`, `completion fish`, `completion powershell` |
+| Schema | `schema` |
+
+Common global flags:
+
+```sh
+--json
+--raw
+--fields id,status
+--api-key <value>
+--dry-run
+--yes
+```
+
+## Authentication
+
+The CLI is intended to resolve credentials in this order:
+
+1. `--api-key <value>`
+2. `EPROSPERA_API_KEY`
+3. Credentials saved by `eprospera auth login`
+
+Do not commit API keys, request payloads, `.env` files, or exported credentials.
+The repository ignore rules are configured to keep those out of the public repo.
+
+## Development
+
+Useful scripts:
+
+```sh
+pnpm run gen:api          # Generate TypeScript types from the public OpenAPI spec
+pnpm run gen:docs         # Regenerate tracked command docs under docs/commands/
+pnpm run gen:completions  # Generate shell completions under dist/
+pnpm run validate:ocs     # Validate cli.ocs.yaml against the OpenCLI schema
+pnpm run typecheck        # Run TypeScript without emitting files
+pnpm test                 # Run unit tests
+pnpm run test:e2e         # Run opt-in staging e2e tests when EPROSPERA_E2E=1
+pnpm run check            # Run formatting/lint checks and typecheck
+pnpm run bundle           # Build a portable ncc executable at dist/bundle/
+pnpm run pack:smoke       # Install the packed tarball in a clean temp project
+```
+
+The pre-commit hook runs `pnpm run gen:all` to keep generated artifacts current.
+
+## Packaging
+
+The npm package is configured to include the runtime entrypoint, compiled output,
+the OpenCLI spec, license, changelog, and README. It excludes source, tests,
+scripts, local docs, CI config, source maps, logs, and environment files.
+
+Before publishing or tagging a release, check the package contents:
+
+```sh
+npm pack --dry-run --json --ignore-scripts
+pnpm run pack:smoke
+```
+
+## Release
+
+The first public release should happen only after the full local gate passes:
+
+```sh
+pnpm run gen:all
+pnpm run check
+pnpm run validate:ocs
+pnpm test
+pnpm run build
+pnpm run bundle
+npm pack --dry-run --json --ignore-scripts
+pnpm run pack:smoke
+```
+
+For the first public publish, use one of these npm auth paths:
+
+- Manual: publish from a logged-in maintainer account with a one-time code.
+- Automated: configure the repository `NPM_TOKEN` secret with a granular token
+  that can publish `@prospera/eprospera-cli` and bypass publish-time 2FA.
+
+After the package exists on npm, prefer npm trusted publishing with GitHub
+Actions publisher `Honduras-Prospera-inc/eprospera-cli` and workflow filename
+`release.yml`, then remove any long-lived publish token.
+
+Manual first publish:
+
+```sh
+npm publish --access public --otp <one-time-code>
+npm install -g @prospera/eprospera-cli
+eprospera --help
+```
+
+## License
+
+MIT

package/bin/eprospera.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+const { runCli } = await import("../dist/src/index.js");
+process.exitCode = await runCli();

package/cli.ocs.yaml

@@ -0,0 +1,406 @@
+$schema: https://opencli.org/draft.json
+opencli: "0.1"
+info:
+  title: eprospera
+  version: "0.1.0"
+  summary: Command-line access to the e-Prospera public API.
+  description: >
+    Agent-key-first TypeScript CLI for e-Prospera legal entity, application,
+    identity, authentication, configuration, completion, and schema workflows.
+  contact:
+    name: Prospera
+    url: https://docs.eprospera.com
+  license:
+    name: MIT License
+    identifier: MIT
+    url: https://opensource.org/license/mit
+conventions:
+  groupOptions: true
+  optionSeparator: " "
+command:
+  name: eprospera
+  description: Command-line wrapper over the e-Prospera public API.
+  options:
+    - name: --json
+      recursive: true
+      group: Output
+      description: Pretty-print JSON to stdout and suppress color, spinners, and incidental output.
+    - name: --raw
+      recursive: true
+      group: Output
+      description: Print compact single-line JSON to stdout.
+    - name: --fields
+      recursive: true
+      group: Output
+      description: Restrict output keys for read commands.
+      arguments:
+        - name: keys
+          required: true
+          description: Comma-separated output fields, such as id,statusId,name.
+    - name: --quiet
+      recursive: true
+      group: Output
+      description: Suppress incidental human output.
+    - name: --yes
+      aliases: [-y]
+      recursive: true
+      group: Interaction
+      description: Skip confirmation prompts.
+    - name: --api-key
+      recursive: true
+      group: Authentication
+      description: Use this bearer token instead of environment or stored credentials.
+      arguments:
+        - name: value
+          required: true
+          description: Agent Key, standard API key, or OAuth access token.
+    - name: --dry-run
+      recursive: true
+      group: Execution
+      description: Validate locally and print the request that would be sent.
+    - name: --help
+      aliases: [-h]
+      recursive: true
+      group: Help
+      description: Show help for a command.
+    - name: --version
+      recursive: true
+      group: Help
+      description: Show the CLI version.
+    - name: --no-auto-json
+      recursive: true
+      group: Output
+      description: Disable automatic JSON output when stdout is not a TTY.
+    - name: --skip-scope-check
+      recursive: true
+      group: Authentication
+      description: Skip cached local Agent Key scope preflight.
+  exitCodes:
+    - code: 0
+      description: Success.
+    - code: 1
+      description: Generic failure or unexpected error.
+    - code: 2
+      description: Invalid usage, bad flag, or missing argument.
+    - code: 3
+      description: Authentication failure, including 401 or no credential configured.
+    - code: 4
+      description: Authorization failure, including missing scope or revoked Manifestation of Will.
+    - code: 5
+      description: Resource not found, usually 404.
+    - code: 6
+      description: Conflict, including 409, name collision, or impossible state transition.
+    - code: 7
+      description: Rate limit, usually 429.
+    - code: 8
+      description: Validation error, usually 400.
+    - code: 9
+      description: Timeout, including polling or network timeout.
+    - code: 10
+      description: Application or coupon entered a terminal failure state.
+  commands:
+    - name: entity
+      description: Verify, search, inspect, and fetch documents for legal entities.
+      commands:
+        - name: verify
+          description: Verify whether an RPN exists and is active.
+          arguments:
+            - name: rpn
+              required: true
+              description: 14-digit resident permit number starting with 8 or 9.
+          examples:
+            - eprospera --json entity verify 80000000000012
+          metadata:
+            - name: endpoint
+              value: POST /api/v1/verify_rpn
+            - name: requiredScope
+              value: agent:verify_rpn
+            - name: credentialTypes
+              value: [ak, sk]
+        - name: search
+          description: Search the legal-entity registry by name or partial RPN.
+          arguments:
+            - name: query
+              required: true
+              description: Free-text query. Multi-word input is split by the API.
+          examples:
+            - eprospera --json entity search "Acme Holdings"
+          metadata:
+            - name: endpoint
+              value: POST /api/v1/registries/legal_entities/search
+            - name: requiredScope
+              value: agent:registry.search
+            - name: credentialTypes
+              value: [ak, sk]
+        - name: get
+          description: Fetch one legal entity by UUID.
+          arguments:
+            - name: id
+              required: true
+              description: Legal entity UUID.
+          examples:
+            - eprospera --json entity get 00000000-0000-4000-8000-000000000000
+          metadata:
+            - name: endpoint
+              value: GET /api/v1/legal_entities/{id}
+            - name: requiredScope
+              value: agent:entity.read
+            - name: credentialTypes
+              value: [ak, sk]
+        - name: documents
+          description: Fetch documents for one legal entity.
+          arguments:
+            - name: id
+              required: true
+              description: Legal entity UUID.
+          examples:
+            - eprospera --json entity documents 00000000-0000-4000-8000-000000000000
+          metadata:
+            - name: endpoint
+              value: GET /api/v1/legal_entities/{id}/documents
+            - name: requiredScope
+              value: agent:entity.documents.read
+            - name: credentialTypes
+              value: [ak, sk]
+    - name: application
+      description: Create, pay, list, inspect, and watch legal-entity applications.
+      commands:
+        - name: list
+          description: List API-created legal-entity applications visible to the credential.
+          examples:
+            - eprospera --json application list --fields id,statusId,legalEntityId
+          metadata:
+            - name: endpoint
+              value: GET /api/v1/legal_entity_applications
+            - name: requiredScope
+              value: agent:entity.application.read
+            - name: credentialTypes
+              value: [ak, sk]
+        - name: create
+          description: Create a legal-entity application from a JSON request file.
+          interactive: true
+          options:
+            - name: --file
+              description: Read the application request body from a JSON file.
+              arguments:
+                - name: path
+                  required: true
+                  description: Path to a JSON request body.
+          examples:
+            - eprospera --json --yes application create --file application.json
+          metadata:
+            - name: endpoint
+              value: POST /api/v1/legal_entity_applications
+            - name: requiredScope
+              value: agent:entity.application.create
+            - name: credentialTypes
+              value: [ak, sk]
+        - name: get
+          description: Fetch one legal-entity application by UUID.
+          arguments:
+            - name: id
+              required: true
+              description: Legal entity application UUID.
+          examples:
+            - eprospera --json application get 00000000-0000-4000-8000-000000000000
+          metadata:
+            - name: endpoint
+              value: GET /api/v1/legal_entity_applications/{id}
+            - name: requiredScope
+              value: agent:entity.application.read
+            - name: credentialTypes
+              value: [ak, sk]
+        - name: pay
+          description: Apply a fully covering coupon to a legal-entity application.
+          interactive: true
+          arguments:
+            - name: id
+              required: true
+              description: Legal entity application UUID.
+          options:
+            - name: --coupon
+              required: true
+              description: Coupon code to apply.
+              arguments:
+                - name: code
+                  required: true
+                  description: Coupon code.
+          examples:
+            - eprospera --json --yes application pay 00000000-0000-4000-8000-000000000000 --coupon EXAMPLE_COUPON
+          metadata:
+            - name: endpoint
+              value: POST /api/v1/legal_entity_applications/{id}/pay/coupon
+            - name: requiredScope
+              value: agent:entity.application.pay
+            - name: credentialTypes
+              value: [ak, sk]
+        - name: watch
+          description: Poll an application until approval, rejection, payment failure, or timeout.
+          arguments:
+            - name: id
+              required: true
+              description: Legal entity application UUID.
+          options:
+            - name: --timeout
+              description: Hard polling timeout.
+              arguments:
+                - name: duration
+                  required: true
+                  description: Duration such as 30m or 1h.
+            - name: --initial-interval
+              description: Polling interval before backoff.
+              arguments:
+                - name: duration
+                  required: true
+                  description: Duration such as 30s.
+            - name: --max-interval
+              description: Maximum polling interval after backoff.
+              arguments:
+                - name: duration
+                  required: true
+                  description: Duration such as 5m.
+          examples:
+            - eprospera --json application watch 00000000-0000-4000-8000-000000000000 --timeout 30m
+          metadata:
+            - name: endpoint
+              value: GET /api/v1/legal_entity_applications/{id}
+            - name: requiredScope
+              value: agent:entity.application.read
+            - name: credentialTypes
+              value: [ak, sk]
+    - name: me
+      description: Read profile data for the Agent Key owner or OAuth user.
+      commands:
+        - name: profile
+          description: Fetch the natural-person profile for the credential owner.
+          examples:
+            - eprospera --json me profile
+          metadata:
+            - name: endpoint
+              value: GET /api/v1/me/natural-person
+            - name: requiredScope
+              value: agent:person.details.read
+            - name: oauthScope
+              value: eprospera:person.details.read
+            - name: credentialTypes
+              value: [ak, oauth]
+        - name: residency
+          description: Fetch current or historical residency status for the credential owner.
+          examples:
+            - eprospera --json me residency
+          metadata:
+            - name: endpoint
+              value: GET /api/v1/me/natural-person/residency
+            - name: requiredScope
+              value: agent:person.residency.read
+            - name: oauthScope
+              value: eprospera:person.residency.read
+            - name: credentialTypes
+              value: [ak, oauth]
+        - name: id-verification
+          description: Fetch ID-verification artifact URLs for the credential owner.
+          examples:
+            - eprospera --json me id-verification
+          metadata:
+            - name: endpoint
+              value: GET /api/v1/me/natural-person/id-verification
+            - name: requiredScope
+              value: agent:person.id_verification.read
+            - name: oauthScope
+              value: eprospera:person.id_verification.read
+            - name: credentialTypes
+              value: [ak, oauth]
+    - name: auth
+      description: Log in, inspect, and remove local credentials.
+      commands:
+        - name: login
+          description: Store an Agent Key or standard API key.
+          interactive: true
+          options:
+            - name: --agent-key
+              description: Prompt for an ak- Agent Key and validate it.
+            - name: --standard-key
+              description: Prompt for an sk- standard API key.
+            - name: --scopes
+              description: Comma-separated Agent Key scopes to cache.
+              arguments:
+                - name: csv
+                  required: true
+                  description: Comma-separated scope names.
+          examples:
+            - eprospera auth login --agent-key --scopes agent:person.details.read
+          metadata:
+            - name: credentialTypes
+              value: [ak, sk]
+        - name: whoami
+          description: Show the currently resolved credential kind and owner metadata.
+          examples:
+            - eprospera --json auth whoami
+          metadata:
+            - name: credentialTypes
+              value: [ak, sk, oauth]
+        - name: logout
+          description: Delete locally stored credentials.
+          interactive: true
+          examples:
+            - eprospera --yes auth logout
+          metadata:
+            - name: credentialTypes
+              value: [ak, sk, oauth]
+    - name: config
+      description: Read and write local CLI configuration.
+      commands:
+        - name: get
+          description: Read one configuration value.
+          arguments:
+            - name: key
+              required: true
+              description: Configuration key.
+          examples:
+            - eprospera --json config get api.baseUrl
+        - name: set
+          description: Set one configuration value.
+          arguments:
+            - name: key
+              required: true
+              description: Configuration key.
+            - name: value
+              required: true
+              description: Configuration value.
+          examples:
+            - eprospera config set api.baseUrl https://api.example.com
+        - name: list
+          description: List all local configuration values.
+          examples:
+            - eprospera --json config list
+        - name: unset
+          description: Remove one configuration value.
+          arguments:
+            - name: key
+              required: true
+              description: Configuration key.
+          examples:
+            - eprospera config unset api.baseUrl
+    - name: completion
+      description: Generate shell completion scripts.
+      commands:
+        - name: bash
+          description: Print Bash completion script.
+          examples:
+            - eprospera completion bash
+        - name: zsh
+          description: Print Zsh completion script.
+          examples:
+            - eprospera completion zsh
+        - name: fish
+          description: Print Fish completion script.
+          examples:
+            - eprospera completion fish
+        - name: powershell
+          description: Print PowerShell completion script.
+          examples:
+            - eprospera completion powershell
+    - name: schema
+      description: Print this OpenCLI document to stdout.
+      examples:
+        - eprospera schema