@seamward/cli 0.1.0-alpha.10

package/LICENSE

@@ -0,0 +1,31 @@
+Seamward CLI Proprietary License
+
+Copyright (c) 2026 Seamward. All rights reserved.
+
+This software and its accompanying documentation are proprietary to Seamward.
+Possession, installation, or availability through a package registry does not
+grant a licence to use, copy, modify, distribute, sublicense, sell, or create
+derivative works from the software.
+
+You may use the software only to the extent expressly permitted by a written
+agreement with Seamward, including an applicable customer, evaluation, pilot,
+or partner agreement. If that agreement conflicts with this notice, the
+written agreement controls.
+
+Except where applicable law does not permit the restriction, you may not:
+
+1. redistribute, publish, sublicense, lease, sell, or transfer the software;
+2. reverse engineer, decompile, disassemble, or attempt to derive source code
+   from any distributed binary or package; or
+3. remove or alter proprietary notices.
+
+THE SOFTWARE IS PROVIDED "AS IS" TO THE MAXIMUM EXTENT PERMITTED BY LAW,
+WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND
+NON-INFRINGEMENT. TO THE MAXIMUM EXTENT PERMITTED BY LAW, SEAMWARD IS NOT
+LIABLE FOR INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR EXEMPLARY DAMAGES,
+OR FOR LOSS OF DATA, REVENUE, PROFITS, OR BUSINESS OPPORTUNITY, ARISING FROM OR
+RELATED TO THE SOFTWARE.
+
+No trademark rights are granted. All rights not expressly granted in a written
+agreement with Seamward are reserved.

package/README.md

@@ -0,0 +1,428 @@
+# Seamward setup CLI
+
+`@seamward/cli` discovers integration boundaries in a local codebase and builds
+a deterministic, reviewable setup plan. The alpha release scans TypeScript,
+JavaScript, Python, PHP, and Go for HTTP, webhook, queue, and scheduled-feed
+operations.
+
+Discovery and setup previews are read-only. The CLI does not upload source
+code, read `.env` files, or modify application handlers. The scanner records
+file names, line numbers, operation categories, confidence, and redacted target
+hints. It does not include source lines in its output. Interactive review writes
+local review state only after an explicit confirmation.
+
+## Support matrix
+
+| Target                           | Discovery         | Generated collector bootstrap | Instrumentation                |
+| -------------------------------- | ----------------- | ----------------------------- | ------------------------------ |
+| Node.js 22+ TypeScript, ESM      | Alpha             | Yes                           | Review required                |
+| Node.js 22+ JavaScript, ESM      | Alpha             | Yes                           | Review required                |
+| Node.js 22+ JavaScript, CommonJS | Alpha             | ESM bridge (`.mjs`)           | Review required                |
+| Browser or edge JavaScript       | Discovery only    | No                            | Unsupported                    |
+| Python                           | Discovery preview | No                            | Direct REST, manual            |
+| PHP                              | Discovery preview | No                            | Direct REST, manual            |
+| Go                               | Discovery preview | No                            | Direct REST, manual            |
+| Monorepo root                    | Refused           | No                            | Run from one service directory |
+
+Discovery uses deterministic lexical detectors, not a compiler. Review every
+finding before instrumenting it. Tests, fixtures, generated output, ignored
+dependencies, scripts, mocks, tools, provider simulators, secret files, and
+`.gitignore` matches are excluded by default.
+
+## Coding-agent setup with MCP
+
+Use `@seamward/setup-mcp` when your coding agent supports local stdio MCP
+servers. It wraps this package's discovery and planning engine, so the CLI and
+agent workflow produce the same plan. The difference is responsibility:
+
+- the local MCP analyzes automatically and presents one readable local proposal;
+- one local approval covers the dependency, generated file, and reviewed source
+  changes;
+- the MCP applies supported JavaScript or TypeScript source changes, runs the
+  project verification scripts, and records evidence as one reversible local
+  operation;
+- one remote approval either registers and activates the exact reviewed
+  contract or links an exact already-active version to local setup evidence;
+- a final read-only status check reports whether traffic has arrived;
+- the CLI remains the deterministic fallback for terminals and CI.
+
+Start by asking the agent: "Set up Seamward in this project." The MCP owns
+discovery, previews, repository verification, and environment-file safety. The
+interactive workflow does not ask a user to name a provider, guess a protocol,
+select a contract path in the prompt, or copy internal plan values between
+calls. See the
+[`@seamward/setup-mcp` package](https://www.npmjs.com/package/@seamward/setup-mcp)
+for the supported workflow and status states.
+
+Automatic MCP instrumentation currently covers outbound Node.js HTTP client
+calls and inbound Node.js webhook handlers. Inbound HTTP servers, queues, and
+scheduled feeds are discovered, then routed to a manual setup guide before any
+local approval. The CLI remains available for explicit planning across every
+discovered protocol.
+
+Local MCP evidence stores current file hashes. Older alpha state is migrated
+only during the approved local apply and only when generated targets can be
+proven safe.
+
+## Install
+
+```bash
+pnpm add -D @seamward/cli@alpha
+```
+
+The CLI and generated Node bootstrap require Node.js 22 or newer. The generated
+plan pins collector installation to `@seamward/collector@0.1.0-alpha.3`, the
+first release with Connection-key and multi-protocol wrappers used by this
+setup schema. Regenerate and review the plan before changing that dependency.
+
+## Discover and prepare a plan
+
+```bash
+pnpm exec seamward discover .
+pnpm exec seamward setup .
+pnpm exec seamward setup . --write
+```
+
+One Seamward Integration has exactly one direction and protocol. When discovery
+finds more than one compatible scope, `setup` refuses to build an ambiguous
+single-key plan. Select one scope explicitly:
+
+```bash
+pnpm exec seamward setup . \
+  --direction outbound \
+  --protocol http-api \
+  --contract contracts/provider.openapi.json
+```
+
+Valid protocols are `http-api`, `http-webhook`, `queue`, and
+`scheduled-feed`. The plan records the selected `integrationScope` and every
+`excludedIntegrationScope`. Complete and verify each scope separately. Each
+scope needs its own Integration and Connection key. Never reuse one
+Integration's key for a different direction or protocol.
+
+Contract files do not declare whether they describe your inbound API or a
+provider you call. Discovery therefore never assigns one by file name or
+proximity. Pass `--contract` for each reviewed contract that belongs to the
+selected scope. Other discovered artifacts remain visible in
+`unassignedContracts` and cannot be registered from that plan.
+
+OpenAPI assignment is limited to `http-api` and `http-webhook` scopes. A mixed
+OpenAPI document is split by the selected scope: HTTP API plans register
+`paths`, while webhook plans register `webhooks`. Use an operation-bound JSON
+Schema for queue and scheduled-feed Integrations.
+
+`setup` previews `.seamward/setup-plan.json` and, for a declared backend Node
+service, a scope-named file such as
+`src/seamward.outbound-http-api.generated.ts`. JavaScript uses `.js` or `.mjs`.
+`--write` creates only those generated files. Existing files are never replaced
+unless `--force` is also supplied. Symbolic-link destinations and paths outside
+the selected service root are rejected.
+
+The generated bootstrap reads the scoped Connection-key and Integration-owned
+ingest-token names printed in the plan. For example:
+
+```text
+SEAMWARD_CONNECTION_KEY_OUTBOUND_HTTP_API
+SEAMWARD_INGEST_TOKEN_OUTBOUND_HTTP_API
+```
+
+Run and verify one selected scope before replacing `.seamward/setup-plan.json`
+with another scope. Scope-named bootstrap files remain separate, so a mixed
+service can import one collector per Integration after each plan is reviewed.
+
+The plan's `review_required` and `manual` actions remain application changes for
+an engineer to make. `verify` exits non-zero while any action remains pending:
+
+```bash
+pnpm exec seamward verify .
+```
+
+Verification checks the plan fingerprint, exact generated contents, collector
+dependency, and pending actions. It does not claim that a regex finding is
+already instrumented.
+
+## Complete reviewed actions
+
+After implementing the proposed instrumentation, bind the selected actions to
+the current implementation files:
+
+```bash
+pnpm exec seamward review . --source-backed
+pnpm exec seamward verify .
+```
+
+The CLI presents numbered descriptions containing the operation kind,
+direction, file, and line. Select `all` or a comma-separated set of numbers,
+add an optional review note, and confirm once. The action identifiers remain in
+the machine-readable plan and local audit state; an interactive user does not
+copy them. Only the final affirmative confirmation writes a timestamped entry
+to `.seamward/setup-state.json`, bound to the current plan fingerprint.
+
+Source-backed review records current hashes for the implementation files named
+by the selected actions. It does not edit application source, install
+dependencies, register a contract, or prove business correctness. A later file
+change makes that evidence stale. Review without `--source-backed` records a
+legacy `attested_only` decision and does not satisfy source-backed completion.
+For TypeScript and JavaScript, a single reviewed wrapper or adapter factory in
+one file may serve several findings in that file. Every selected action is
+bound to the same current file hash. Static evidence proves that the planned
+wrapper boundary exists, not that every route ran. Project tests and the first
+accepted observation remain separate requirements.
+
+For deterministic non-interactive automation, preview or record every pending
+instrumentation action with `--all`:
+
+```bash
+pnpm exec seamward review . --all
+pnpm exec seamward review . \
+  --all \
+  --source-backed \
+  --evidence "instrumented and reviewed in src/provider.ts" \
+  --write
+```
+
+Bare `review .` requires an interactive terminal. In CI or redirected input,
+use `--all` so the command never waits for input.
+The review command accepts instrumentation actions only. A contract-registration
+action remains pending until `contracts register --write` receives a successful
+API response containing the registered draft id.
+
+`verify` exits zero only when generated artifacts still match the plan, the
+required collector dependency is present, source-backed evidence is current,
+the required contract is registered and active, and the first accepted
+observation has been recorded. A new setup-plan fingerprint invalidates
+completion state from an older plan; review the new findings instead of copying
+the old state file.
+
+The assisted setup path can reconcile an already-active version without a
+remote write. It requires an exact match for the Integration, declared version,
+import format, contract document, and every imported operation selector and
+schema fingerprint. JSON Schema reconciliation also requires the same explicit
+operation binding. A mismatch remains incomplete and requires a fresh remote
+review.
+
+The packaged [Node service example](examples/node-service) contains one webhook,
+one outbound provider call, and one OpenAPI document you can use to inspect the
+discovery and setup-plan output.
+
+## Register one contract draft
+
+Create a scoped API key with `contracts:write`. Keep the key in your secret
+manager or temporary shell environment. The Connection key identifies the
+Integration and is public routing configuration.
+
+The CLI uses `https://api.seamward.com` by default. For local development, set
+`SEAMWARD_MANAGEMENT_API_URL=http://127.0.0.1:4100`. An explicit `--endpoint`
+value takes precedence over the environment variable. Non-local HTTP endpoints
+are rejected.
+
+The saved plan must first bind the reviewed file to this Integration scope:
+
+```bash
+pnpm exec seamward setup . \
+  --direction outbound \
+  --protocol http-api \
+  --contract contracts/provider.openapi.json \
+  --write
+```
+
+```bash
+export SEAMWARD_API_KEY=replace_with_scoped_key
+export SEAMWARD_CONNECTION_KEY_OUTBOUND_HTTP_API=replace_with_connection_key
+
+pnpm exec seamward contracts register . \
+  --version 2026-08 \
+  --file contracts/provider.openapi.json
+
+pnpm exec seamward contracts register . \
+  --version 2026-08 \
+  --file contracts/provider.openapi.json \
+  --write
+```
+
+The first command previews the destination and lifecycle effect. Only
+`--write` sends the document. One invocation registers exactly one immutable
+draft, never several partial versions. Contract files are limited to 1 MB,
+must match the fingerprint in the reviewed plan, and must resolve inside the
+project. `example`, `examples`, and code-sample fields are removed by default.
+Use `--include-examples` only after reviewing those values.
+
+After a successful `--write`, the CLI records the matching
+`register_contract` action as completed with the returned draft id. It does
+not complete instrumentation actions.
+
+The JSON preview is a local dry-run. It validates the selected file and plan
+fingerprint without calling the Seamward API and reports:
+
+| Field                  | Meaning                                                       |
+| ---------------------- | ------------------------------------------------------------- |
+| `applied`              | Always `false` in a preview                                   |
+| `operation`            | `contract_registration`                                       |
+| `integrationId`        | Destination derived from the public Connection key            |
+| `declaredVersion`      | Immutable version label requested on the command line         |
+| `files`                | The one reviewed contract file                                |
+| `format`               | `openapi` or `json_schema`                                    |
+| `fingerprint`          | SHA-256 fingerprint recorded in the setup plan                |
+| `byteSize`             | Source contract file size before upload                       |
+| `removedExampleFields` | Number of example or code-sample fields that would be removed |
+| `operationBinding`     | Validated JSON Schema binding, when required                  |
+| `examples`             | Whether examples would be removed or included                 |
+
+The preview requires the scoped Connection-key environment variable printed in
+the plan so it can show the destination, but it does not require
+`SEAMWARD_API_KEY`. A JSON Schema preview fails before network access when
+`--binding` is absent, outside the project, malformed, or contains an invalid
+selector.
+
+If the network drops after the server accepts a registration, the CLI retries
+once. The API returns the existing version only when the document and every
+operation selector are identical. A different document or selector with the
+same declared version remains a conflict.
+
+JSON Schema describes one operation and therefore needs an explicit binding:
+
+```json
+{
+  "method": "POST",
+  "routeTemplate": "/candidates",
+  "payloadLocation": "response",
+  "statusSelector": "201"
+}
+```
+
+```bash
+pnpm exec seamward contracts register . \
+  --version 2026-08 \
+  --file contracts/candidate.schema.json \
+  --binding contracts/candidate.binding.json \
+  --write
+```
+
+Swagger 2.0 is not accepted. Convert it to OpenAPI 3 before discovery.
+
+## Activate a reviewed contract
+
+Activation changes the schema used for analysis and requires a key with
+`contracts:read` and `contracts:activate`. It is a separate, explicit command
+with an optimistic concurrency precondition. Preview it first:
+
+```bash
+pnpm exec seamward contracts status .
+
+pnpm exec seamward contracts activate . \
+  --contract contract_target \
+  --expected contract_current
+
+pnpm exec seamward contracts activate . \
+  --contract contract_target \
+  --expected contract_current \
+  --write
+```
+
+Use `--expected none` only when the Integration has no active version. Use
+`--reason rollback` for an intentional rollback. Contract versions are
+immutable and do not have a delete command.
+
+If an activation response is lost, a retry reconciles successfully only when
+the requested target is already active. Any other conflict requires a new
+status review.
+
+## Check the first accepted observation
+
+After starting the instrumented service, send one representative request or
+message. The scoped API key needs `observations:read`:
+
+```bash
+pnpm exec seamward observations check .
+pnpm exec seamward observations check . --write
+pnpm exec seamward verify .
+```
+
+The first command previews the remote result. `--write` stores the accepted
+observation id and timestamp in local setup state. The query begins after the
+latest source evidence and activation, so older traffic cannot complete a new
+setup. When the plan has a contract, the check also confirms that the locally
+recorded contract version is still active. One observation proves connectivity
+for the Integration, not coverage of every discovered operation.
+
+The setup MCP uses `contracts:read` to review and reconcile an exact active
+version. It needs `contracts:write` and `contracts:activate` only when it must
+create and activate a new version. The observation check needs
+`observations:read`. An interrupted local reconciliation is retry-safe and does
+not repeat a remote mutation.
+
+## Programmatic use
+
+The package exports the same deterministic building blocks for tools that need
+structured results instead of CLI JSON:
+
+| Import              | Value exports                                                                                                                                                                                                                                                                                                                                                                                            | Type exports                                                                                                                                   |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@seamward/cli`     | `discoverSources`, `scanProject`                                                                                                                                                                                                                                                                                                                                                                         | `ContractArtifact`, discovery result, finding, protocol, language, direction, confidence, input, and option types                              |
+| `@seamward/cli`     | `createSetupPlan`, `discoverIntegrationScopes`, `applySetupPlan`, `inspectSetupPlanFiles`, `inspectSetupActionEvidence`, `inspectSetupCompletionState`, `inspectSetupRemoteLifecycle`, `completedSetupActionIds`, `operatorReviewableSetupActions`, `reviewSetupActions`, `recordSourceBackedSetupEvidence`, `resetSetupCompletionState`, `setupCompletionStateFingerprint`, `supportedCollectorVersion` | setup plan, scope, action, completion state, remote lifecycle, evidence, file inspection, runtime, package-manager, apply, and review types    |
+| `@seamward/cli`     | `previewPlanContract`, `registerPlanContracts`, `readContractStatus`, `readMatchingActivePlanContract`, `reconcileActivePlanContract`, `previewPlanContractActivation`, `validatePlanContractActivation`, `activatePlanContractVersion`, `activateContractVersion`, `checkFirstSetupObservation`                                                                                                         | registration, exact-active matching, reconciliation, status, plan activation, low-level activation, observation, and JSON Schema binding types |
+| `@seamward/cli`     | `createLocalSetupEngine`, `readSetupPlan`, `verifySetup`, `readProjectMetadata`                                                                                                                                                                                                                                                                                                                          | local setup engine, analysis, selection, verification, and project metadata types                                                              |
+| `@seamward/cli`     | `SeamwardRemoteApiError`                                                                                                                                                                                                                                                                                                                                                                                 | stable remote API error code types                                                                                                             |
+| `@seamward/cli`     | `parseConnectionKey`, `cliVersion`                                                                                                                                                                                                                                                                                                                                                                       | `ParsedConnectionKey`                                                                                                                          |
+| `@seamward/cli/cli` | `runCli`                                                                                                                                                                                                                                                                                                                                                                                                 | `CliIo`                                                                                                                                        |
+
+Use `runCli` only when embedding the command dispatcher with an explicit I/O
+adapter. Do not import files from `dist`, `src`, or other internal paths.
+
+`activateContractVersion` remains exported for alpha compatibility but is
+deprecated. It bypasses setup-plan ownership and source-evidence checks. New
+tools must use `previewPlanContractActivation` and then
+`activatePlanContractVersion` so the exact plan, source evidence, active
+version, and approval remain locked together.
+
+This package is an alpha release. Command output, TypeScript types, generated
+file schema, detector coverage, and programmatic signatures may change between
+alpha versions. Pin an exact version and review the changelog and generated
+plan before upgrading. Discovery findings remain advisory and require an
+engineer review.
+
+## Privacy and limitations
+
+- Application source remains local. Plans do not contain source lines.
+- Literal URL paths are replaced with `<redacted-path>`.
+- Contract documents are the only files uploaded by this CLI. Their exact file,
+  fingerprint, size boundary, target Integration, and version are reviewed
+  before `--write`.
+- Field names in contracts remain visible because structural matching needs
+  them. Remove confidential descriptions and extensions before registration.
+- The CLI never edits `.env` or deployed configuration.
+- Non-Node and browser projects receive discovery guidance, not a claim of
+  automatic instrumentation.
+- Run the CLI from one deployable service directory in a monorepo.
+
+## Troubleshooting
+
+- **Verification reports missing Seamward credentials:** upgrade to the latest
+  CLI and generated bootstrap, then rerun the reviewed local apply. The setup
+  engine gives the generated collector an allowlisted, credential-free
+  verification environment, so it cannot start or transmit an observation.
+  Project verification scripts still run exactly as the repository defines
+  them and may perform their own file or network access. Normal application
+  startup still requires the Connection key and ingest token.
+- **Automatic instrumentation is unsupported:** no source or generated change
+  is retained. Use the manual integration guide or refactor the boundary into a
+  supported shape, then create and review a fresh plan. Do not mix plan-owned
+  setup with unrelated automated edits.
+- **No plan found:** run `seamward setup . --write` first.
+- **Multiple Integration scopes:** rerun `setup` with one `--direction` and
+  `--protocol`. Use a distinct Integration and Connection key for every scope.
+- **Plan fingerprint mismatch:** run a fresh read-only setup preview, review the
+  changed findings, then explicitly replace generated artifacts if appropriate.
+- **Generated file conflict:** move or review the existing file. Use `--force`
+  only for a file previously generated by Seamward.
+- **Setup lock remains after a crash:** a lock whose recorded process is still
+  running must be left in place. If the recorded process no longer exists,
+  inspect the named lock, remove only that lock file, and rerun the command.
+  Seamward never steals or replaces a lock automatically.
+- **Multiple contracts discovered:** pass exactly one `--file`.
+- **JSON Schema binding invalid:** include `routeTemplate` and
+  `payloadLocation`; remove unsupported fields.
+- **Verification incomplete:** install the collector when requested and review
+  every pending instrumentation or contract action.
+- **403 response:** create a workspace-scoped key with the documented contract
+  scope. Credentials are not printed in command output.

package/dist/cli.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+export interface CliIo {
+    cwd(): string;
+    stdout(value: string): void;
+    stderr(value: string): void;
+    env?(name: string): string | undefined;
+    fetchFn?: typeof fetch;
+    isInteractive?(): boolean;
+    prompt?(question: string): Promise<string>;
+}
+export declare function runCli(arguments_: string[], io?: CliIo): Promise<number>;