pageship 0.0.1 → 0.1.0

package/README.md

@@ -1,8 +1,8 @@
 # Pageship
 
-Pageship is a planned HTML publishing service. This package is its early CLI
-development skeleton. It currently displays help and version information only;
-hosting, authentication, and publishing are not implemented.
+Pageship is an HTML publishing service in development. This CLI checks a server's API
+compatibility, authorizes an installation through a browser, and identifies your
+personal workspace. It publishes HTML documents and revisions behind stable addresses. Private browser delivery requires the owner to sign in.
 
 Requires Node.js 24.11 or newer.
 
@@ -10,15 +10,92 @@ Requires Node.js 24.11 or newer.
 npx pageship
 npx pageship --help
 npx pageship --version
+npx pageship status --server http://localhost:8787
+npx pageship --json status --server http://localhost:8787
 ```
 
+`status` accepts an HTTP or HTTPS server base URL and checks the API major this CLI
+requires against the majors advertised by the server. Package versions do not
+determine API compatibility. The request times out after 10 seconds.
+
+The `--json` flag is global and may appear before or after `status`, including on
+help, version, and invalid invocations. JSON mode writes one JSON value to stdout
+without human output or prompts. Like other flags, `--json` after the `--` separator
+is treated as an argument. Interactive wizard and shell-completion options are
+available only in human mode.
+
+- Exit `0`: compatible server, help, or version.
+- Exit `1`: invalid arguments, network failure, or invalid server response.
+- Exit `2`: incompatible API major. The result explains whether the CLI or server
+  needs updating, or the requested major is unsupported.
+
+JSON status results contain `ok`, `command: "status"`, `status`, `requiredApiMajor`,
+`server`, and `message`. `status` is `compatible`, `client_too_old`, `server_too_old`,
+or `unsupported`. The server object contains `serverVersion`, `currentApiMajor`,
+and `supportedApiMajors`. Failures contain `ok: false` and an `error` object with
+`code` and `message`; codes are `usage_error`, `request_failed`, or `internal_error`.
+Help and version use `command: "help"` and `command: "version"`, respectively.
+
+## Browser authorization
+
+Run `pageship login --server https://api.example.com`, open the displayed link on
+any machine, and approve the code using your invited GitHub account. Interactive
+terminals wait for approval. JSON and non-TTY calls return immediately with a link,
+code and completion arguments; then run `pageship login --complete --server
+https://api.example.com`. Run `pageship whoami --server https://api.example.com`
+to reuse the stored credential in a new process. Add global `--json` for structured
+results. Pending or denied authorization exits 2, success exits 0, request/storage
+failures exit 1, and interrupted waiting exits 130.
+
+Credentials stay outside projects in an owner-only POSIX directory or Windows
+DPAPI-protected storage under the current user's local app data.
+`PAGESHIP_CONFIG_DIR` selects an absolute private directory. They are bound to the
+exact HTTPS server origin; HTTP is allowed only on loopback for development.
+Use `login --restart` for a new code. Address selection and publication are not
+required for authorization. No credentials appear in command output.
+
+## Publish HTML
+
+Run `pageship publish report.html --server https://api.example.com` after login.
+Absolute file arguments work too. Add `--json` for structured success, source-path
+collisions and address choices. If publication fails after transfer, retry with
+the returned `--idempotency-key`. Reusing that key with the same input returns the
+same document; a different input produces a conflict. Ordinary path collisions
+never update or duplicate a document without an explicit choice.
+
+In a terminal, select `o <number>` to open a matching document, `r <number>` to
+revise it, `n` to create a separate private document, or `q` to cancel. Opening and
+cancellation do not change published content. JSON returns candidates and
+`resolutions` containing complete follow-up command arguments. Run those arguments
+in another invocation to choose explicitly.
+
+Use `--new` to create a separate document even when its source path matches. Use
+`--revise <documentId> --expected-revision <revisionId>` from a returned candidate
+to publish a revision. A concurrent publication returns `revision_conflict` and
+does not overwrite the newer revision. Revisions retain document identity, URL,
+visibility and old immutable content. An interrupted action returns `next` arguments
+including its operation key and selected target; repeat those with unchanged bytes.
+Explicit actions require a server that advertises support; an older server returns
+upgrade guidance before HTML upload.
+
+The default per-file limit is 10,000,000 bytes, configurable by the server. The CLI
+checks it before upload. Source paths are relative to the file's Git root, containing
+working directory, or parent for outside-cwd non-Git files. Git origin URLs contribute
+a normalized, credential-free hashed context. No local manifest is required.
+
+Generated address choices use `--address-choice <choiceId>` or
+`--refresh-addresses`; arbitrary subdomain input is not supported. An interactive
+terminal can select, refresh or cancel. JSON and non-TTY output never waits for a
+choice. Published results exit 0; unresolved choices, collisions, access and size
+failures exit 2; file/request/usage failures exit 1. See the repository's
+[publishing contract](../../docs/publishing.md) for details.
+
 ## Development
 
-Install the [Vite+ CLI](https://viteplus.dev/guide/) and use the exact pnpm version
-pinned in `package.json`.
+Install dependencies from the workspace root as described in the
+[root README](../../README.md). From this directory:
 
 ```sh
-vp install
 pnpm run check
 pnpm run build
 node dist/cli.mjs --help
@@ -27,6 +104,17 @@ npm pack --dry-run
 
 The CLI uses TypeScript and Effect v4's unstable CLI API. Effect and its Node
 platform package are pinned to matching release candidates.
+The shared generated API client is a workspace development dependency bundled
+into `dist/cli.mjs`. Installing the published CLI does not require the private
+workspace package or a checkout of this repository.
+
+## Revoke installation access
+
+`whoami --server <origin>` shows this CLI installation's non-secret ID. JSON mode
+returns it in `installation.id`. Match that ID in the signed-in dashboard's CLI
+installations list and select Revoke access. The next protected request returns
+exit 2 with sign-in guidance; other installations remain authorized. Run `login`
+with the same server to authorize again explicitly.
 
 ## License