@typeship-ax/cli 0.6.0

package/api.md

@@ -0,0 +1,512 @@
+# typeship — API reference
+
+Version 0.6.0. Generated by typeship; regenerate rather than editing.
+
+All methods return `ApiResult<T, E>`: check `result.ok`, or `unwrap(result)` to throw typed errors.
+
+For complete input and output schemas, use [`api.json`](./api.json), the machine-readable companion to this reference. Collapsed wire arguments below use API field names for CLI and MCP; SDK calls use the native signature shown in each heading.
+
+## generate
+
+### `client.generate.run(body)`
+
+Generate a package from a spec
+
+`POST /generate`
+
+Stateless generation: nothing is stored. Returns the full generated
+package as files. Works without an API key: anonymous calls generate
+the first 25 operations, rate limited per IP address, and the
+response's `limits` object says what was held back and where to lift
+it; anonymous calls from a spec URL also carry `claim.url`, a link
+that turns the run into a project once a person signs in. With a key, the free plan generates the first 25 operations and
+paid plans generate the whole spec. A present but invalid key is a
+401, not a downgrade to anonymous.
+
+Safety: **write** · Authentication: **optional**
+
+Body: `GenerateRequest` (required)
+
+Returns: `GenerationResult`
+Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `PayloadTooLargeError` (413), `UnprocessableEntityError` (422), `RateLimitedError` (429), `ApiResponseError` (default)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "spec": {
+    "url": "https://example.com"
+  },
+  "outputs": [
+    "typescript-sdk"
+  ]
+}
+```
+
+</details>
+
+## projects
+
+### `client.projects.list(params)`
+
+List projects
+
+`GET /projects`
+
+Safety: **read** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `limit` | query | `number` | no | Maximum number of resources to return. |
+| `cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. |
+
+Returns: `PagePromise<Project>` — auto-paginating (`for await` walks every page)
+Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{}
+```
+
+</details>
+
+### `client.projects.create(body, params)`
+
+Create a project
+
+`POST /projects`
+
+Stores a URL- or GitHub-sourced project. Free includes one stored project, every selected output, and the first 25 operations, while keeping manual and automatic regeneration, history, destination pull requests, and preview checks. Stateless POST /generate does not consume this slot. Pro adds projects and the whole spec.
+
+Safety: **write** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `idempotencyKey` | header | `string` | no | Uniquely identifies this creation attempt. Retrying the same request with the same key returns the original response instead of creating another project. Reusing a key with different parameters returns 409. |
+
+Body: `CreateProjectRequest` (required)
+
+Returns: `Project`
+Errors: `BadRequestError` (400), `UnauthorizedError` (401), `PaymentRequiredError` (402), `ForbiddenError` (403), `ConflictError` (409), `RateLimitedError` (429), `InternalServerError` (500)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "name": "example",
+  "source": {
+    "kind": "url",
+    "url": "https://example.com"
+  },
+  "outputs": [
+    "typescript-sdk"
+  ]
+}
+```
+
+</details>
+
+### `client.projects.retrieve(projectId)`
+
+Retrieve a project
+
+`GET /projects/{project_id}`
+
+Safety: **read** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `projectId` | path | `ProjectId` | yes | — |
+
+Returns: `Project`
+Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "project_id": "prj_4f8k2m7x9q1v6b3n"
+}
+```
+
+</details>
+
+### `client.projects.delete(projectId)`
+
+Delete a project
+
+`DELETE /projects/{project_id}`
+
+Safety: **destructive** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `projectId` | path | `ProjectId` | yes | — |
+
+Returns: `DeletedProject`
+Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "project_id": "prj_4f8k2m7x9q1v6b3n"
+}
+```
+
+</details>
+
+### `client.projects.update(projectId, body)`
+
+Update a project
+
+`PATCH /projects/{project_id}`
+
+Safety: **write** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `projectId` | path | `ProjectId` | yes | — |
+
+Body: `UpdateProjectRequest` (required)
+
+Returns: `Project`
+Errors: `BadRequestError` (400), `UnauthorizedError` (401), `PaymentRequiredError` (402), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "project_id": "prj_4f8k2m7x9q1v6b3n"
+}
+```
+
+</details>
+
+### `client.projects.retrieveGithubHealth(projectId)`
+
+Diagnose a project's GitHub integration
+
+`GET /projects/{project_id}/github`
+
+Returns machine-actionable source and destination access, spec readability, optional label setup, required status names, and the latest durable webhook delivery. The console renders this same result.
+
+Safety: **read** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `projectId` | path | `ProjectId` | yes | — |
+
+Returns: `GithubIntegrationHealth`
+Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "project_id": "prj_4f8k2m7x9q1v6b3n"
+}
+```
+
+</details>
+
+### `client.projects.listGenerations(projectId, params)`
+
+List a project's generations
+
+`GET /projects/{project_id}/generations`
+
+Safety: **read** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `projectId` | path | `ProjectId` | yes | — |
+| `limit` | query | `number` | no | Maximum number of resources to return. |
+| `cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. |
+| `output` | query | `OutputId` | no | Only generations for this output. |
+
+Returns: `PagePromise<Generation>` — auto-paginating (`for await` walks every page)
+Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "project_id": "prj_4f8k2m7x9q1v6b3n"
+}
+```
+
+</details>
+
+### `client.projects.generate(projectId)`
+
+Generate outputs and open pull requests
+
+`POST /projects/{project_id}/generations`
+
+Resolves the project's URL or repository source, generates every
+configured delivery package, stores each result in the project's history,
+and attempts to open a pull request in every configured destination.
+When the complete generated tree already matches a destination, no
+commit, branch, or pull request is created and that generation reports
+`pr_status: no_changes`. This is the same pipeline automatic
+regeneration runs after a source change.
+
+Safety: **write** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `projectId` | path | `ProjectId` | yes | — |
+
+Returns: `GenerationBatch`
+Errors: `UnauthorizedError` (401), `PaymentRequiredError` (402), `ForbiddenError` (403), `NotFoundError` (404), `UnprocessableEntityError` (422), `RateLimitedError` (429), `InternalServerError` (500)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "project_id": "prj_4f8k2m7x9q1v6b3n"
+}
+```
+
+</details>
+
+## generations
+
+### `client.generations.retrieve(generationId)`
+
+Retrieve a generation
+
+`GET /generations/{generation_id}`
+
+Includes the generated files when the generation succeeded.
+
+Safety: **read** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `generationId` | path | `GenerationId` | yes | — |
+
+Returns: `Generation`
+Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "generation_id": "gen_7h2p5d9c3m8w1k6q"
+}
+```
+
+</details>
+
+### `client.generations.retrieveFile(generationId, params)`
+
+Fetch one file from a generation
+
+`GET /generations/{generation_id}/file`
+
+Raw file content, for generations whose output was too large to inline (files_omitted true). The generation's files_index lists valid paths.
+
+Safety: **read** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `generationId` | path | `GenerationId` | yes | — |
+| `path` | query | `string` | yes | Repo-relative path inside the generated package. |
+
+Returns: `string`
+Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "generation_id": "gen_7h2p5d9c3m8w1k6q",
+  "path": "openapi.yaml"
+}
+```
+
+</details>
+
+## specRevisions
+
+### `client.specRevisions.list(projectId, params)`
+
+List specification revisions
+
+`GET /projects/{project_id}/spec_revisions`
+
+Immutable snapshots of the exact source text this project consumed, newest first. Raw content is available from each revision's content endpoint and is never embedded in a list response.
+
+Safety: **read** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `projectId` | path | `ProjectId` | yes | — |
+| `limit` | query | `number` | no | Maximum number of resources to return. |
+| `cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. |
+
+Returns: `PagePromise<SpecRevision>` — auto-paginating (`for await` walks every page)
+Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "project_id": "prj_4f8k2m7x9q1v6b3n"
+}
+```
+
+</details>
+
+### `client.specRevisions.retrieve(specRevisionId)`
+
+Retrieve a specification revision
+
+`GET /spec_revisions/{spec_revision_id}`
+
+Metadata for one immutable source snapshot. Fetch raw source text from the content endpoint so metadata responses stay small and predictable.
+
+Safety: **read** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `specRevisionId` | path | `SpecRevisionId` | yes | — |
+
+Returns: `SpecRevision`
+Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "spec_revision_id": "spec_6m1q8v4k2p9d7h3c"
+}
+```
+
+</details>
+
+### `client.specRevisions.retrieveContent(specRevisionId)`
+
+Retrieve a specification revision's raw text
+
+`GET /spec_revisions/{spec_revision_id}/content`
+
+Returns the exact source text identified by the revision's SHA-256 digest, suitable for saving or piping directly into a diff.
+
+Safety: **read** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `specRevisionId` | path | `SpecRevisionId` | yes | — |
+
+Returns: `string`
+Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "spec_revision_id": "spec_6m1q8v4k2p9d7h3c"
+}
+```
+
+</details>
+
+## account
+
+### `client.account.retrieve()`
+
+The account behind the presented credentials
+
+`GET /me`
+
+Returns the account that owns the presented API key. This is also the
+identity endpoint the generated typeship CLI's `whoami` calls.
+
+Safety: **read** · Authentication: **required**
+
+Returns: `Account`
+Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{}
+```
+
+</details>
+
+## apiKeys
+
+### `client.apiKeys.list(params)`
+
+List API keys
+
+`GET /api_keys`
+
+Keys are never returned in full — only their identity and last four. Creation stays in the console deliberately: a leaked key that can mint more keys is a leaked account.
+
+Safety: **read** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `limit` | query | `number` | no | Maximum number of resources to return. |
+| `cursor` | query | `string` | no | Opaque cursor from the preceding page's next_cursor. |
+
+Returns: `PagePromise<ApiKey>` — auto-paginating (`for await` walks every page)
+Errors: `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{}
+```
+
+</details>
+
+### `client.apiKeys.revoke(apiKeyId)`
+
+Revoke an API key
+
+`DELETE /api_keys/{api_key_id}`
+
+Idempotent: revoking an already-revoked key returns the same body, so a rotation script that re-runs does not have to special-case having already succeeded.
+
+Safety: **destructive** · Authentication: **required**
+
+| Parameter | In | Type | Required | Description |
+| --- | --- | --- | --- | --- |
+| `apiKeyId` | path | `string` | yes | — |
+
+Returns: `ApiKey`
+Errors: `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `RateLimitedError` (429)
+
+<details>
+<summary>Wire arguments (CLI and MCP)</summary>
+
+```json
+{
+  "api_key_id": "api_key_123"
+}
+```
+
+</details>

package/dist/cli-agent.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Stable codes an agent can branch on. The message is for people; the code
+ * is the contract. Additive only.
+ */
+export type IssueCode = "NO_AUTH" | "AUTH_INVALID" | "PLAN_LIMIT" | "NOT_FOUND" | "INVALID_REQUEST" | "SPEC_INVALID" | "RATE_LIMITED" | "SERVER_ERROR" | "NETWORK_ERROR" | "VALIDATION_FAILED" | "TTY_REQUIRED" | "CONFIRMATION_REQUIRED" | "INVALID_USAGE" | "UNKNOWN_COMMAND" | "UNKNOWN_FLAG" | "MISSING_ARGUMENT" | "COMMAND_FAILED";
+export interface Issue {
+    code: IssueCode;
+    message: string;
+}
+export interface Envelope {
+    /** error: it failed. action_required: it stopped on purpose and next_steps says what unblocks it. */
+    status: "error" | "action_required";
+    issues: Issue[];
+    /** Where to read more; the docs site when one is configured. */
+    docs_url?: string;
+    /** Ordered, concrete, copy-pastable. Empty when there is nothing to suggest. */
+    next_steps: string[];
+    /** The API's own error body, the transport error, or the validation violations. */
+    detail?: unknown;
+}
+export interface EnvelopeInput {
+    status?: Envelope["status"];
+    code: IssueCode;
+    message: string;
+    docsUrl?: string | null;
+    nextSteps?: string[];
+    detail?: unknown;
+}
+export declare function envelope(input: EnvelopeInput): Envelope;
+/** Exit code convention: 0 ok, 1 the request or command failed, 2 usage. */
+export declare function exitCodeFor(code: IssueCode): 1 | 2;
+/** Interpret an SDK error result: HTTP status, body, transport, validation. */
+export declare function classifyApiError(error: unknown, context: {
+    bin: string;
+    hadCredential: boolean;
+    docsUrl: string | null;
+}): EnvelopeInput;
+export interface AgentModeInput {
+    flagMode: string | boolean | undefined;
+    envMode: string | undefined;
+    stdoutIsTTY: boolean;
+    stdinIsTTY: boolean;
+}
+/**
+ * --mode agent beats <PREFIX>_MODE=agent beats "no terminal on either end".
+ * In agent mode nothing prompts, browsers are not opened, and every stop is
+ * an action_required envelope with next_steps.
+ */
+export declare function agentMode(input: AgentModeInput): boolean;
+/** Which agent harness is running us, from its environment; analytics and AGENTS.md placement only. */
+export declare function detectHarness(env?: NodeJS.ProcessEnv): string | null;
+export type McpClientId = "claude-code" | "cursor" | "codex" | "vscode" | "windsurf" | "gemini-cli" | "opencode" | "zed" | "claude-desktop";
+export interface McpEntry {
+    /** A hosted endpoint: {type:"http", url, headers?} */
+    url?: string;
+    /** Header name → value; values may be env references like ${VAR}. */
+    headers?: Record<string, string>;
+    /** A local stdio server: command + args. */
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+}
+export interface McpClient {
+    id: McpClientId;
+    label: string;
+    /** Where the config lives; project-scoped clients resolve against cwd. */
+    file: (cwd: string) => string;
+    /** Presence test: is this client on the machine (or in this project)? */
+    detect: (cwd: string) => boolean;
+    /** Merge an entry into the file's contents. */
+    write: (existing: string, name: string, entry: McpEntry) => string;
+    /** True when the client cannot speak the current MCP protocol; skipped by --all. */
+    incompatible?: string;
+}
+export declare const MCP_CLIENTS: McpClient[];
+export declare function findMcpClient(id: string): McpClient | undefined;
+export interface McpWriteResult {
+    client: McpClientId;
+    file: string;
+    written: boolean;
+    note?: string;
+}
+/** Merge the entry into one client's config file. Never writes a literal secret: callers pass env references. */
+export declare function writeMcpConfig(client: McpClient, cwd: string, name: string, entry: McpEntry): McpWriteResult;
+/** Does a client's config already mention this server? For doctor. */
+export declare function mcpConfigured(client: McpClient, cwd: string, name: string): boolean;
+/**
+ * Upsert a marked block into a repo's agent instructions. Idempotent: the
+ * block between the markers is replaced, everything else is untouched, and
+ * a missing file is created. Returns the file written and whether the
+ * block already existed.
+ */
+export declare function upsertAgentBlock(file: string, marker: string, body: string): {
+    file: string;
+    updated: boolean;
+};
+/** AGENTS.md by default; CLAUDE.md when only it exists, or when running under Claude Code and AGENTS.md is absent. */
+export declare function agentInstructionsFile(cwd: string, harness: string | null): string;
+export interface CommandFlagSummary {
+    flag: string;
+    /** string | number | boolean | array | object | json | file */
+    type: string;
+    /** Element type of an array flag. */
+    items?: {
+        type: string;
+        enum?: string[];
+    };
+    enum?: string[];
+    required: boolean;
+    description?: string;
+}
+export interface CommandSummary {
+    resource: string;
+    command: string;
+    method: string;
+    path: string;
+    summary?: string;
+    paginated: boolean;
+    destructive: boolean;
+    /** required | optional | none — what the spec's security says. */
+    auth?: "required" | "optional" | "none";
+    flags: CommandFlagSummary[];
+}
+export interface AgentContext {
+    bin: string;
+    pkg: string;
+    apiTitle: string;
+    version: string;
+    envPrefix: string;
+    authEnvVars: string[];
+    docsUrl: string | null;
+    /** The API's hosted MCP endpoint, when it has one. */
+    mcpUrl: string | null;
+    /** Skills repository (owner/name) an agent can install with npx skills add. */
+    skillsRepo: string | null;
+    hasMcp: boolean;
+    builtins: string[];
+}
+/** One line per command, pipe-delimited: the compact index that goes into AGENTS.md. */
+/** string, number, usd|eur, string[], usd|eur[], object, json — the type as a reader expects it. */
+export declare function flagTypeLabel(f: CommandFlagSummary): string;
+export declare function compactIndex(commands: CommandSummary[]): string;
+/** The AGENTS.md block body. */
+export declare function agentBlock(ctx: AgentContext, commands: CommandSummary[]): string;
+/** What `agent-guide --format json` returns. */
+export declare function agentGuide(ctx: AgentContext, commands: CommandSummary[]): Record<string, unknown>;
+export interface SkillsInstallResult {
+    status: "installed" | "skipped" | "failed";
+    repo: string | null;
+    detail?: string;
+}
+/** Install a skills repository through the skills CLI (npx skills add). Best effort: init reports, never fails on it. */
+export declare function installSkills(repo: string | null, options?: {
+    global?: boolean;
+    agent?: string | null;
+}): SkillsInstallResult;
+/**
+ * A response that carries files: an array property whose items have string
+ * `path` and `content`. typeship's own generate call is one; any API that
+ * returns generated or exported files is another. `--out <dir>` writes them.
+ */
+export declare function bundleProperty(outputSchema: Record<string, unknown> | undefined): string | null;
+/** A non-page response whose result is a collection wrapped in one array
+ * property (`{data: [...]}` is the common shape). `--fields` applies to
+ * each item while preserving that envelope, just as it does for pages. */
+export declare function collectionProperty(outputSchema: Record<string, unknown> | undefined): string | null;
+export declare function writeBundle(dir: string, files: {
+    path: string;
+    content: string;
+}[]): {
+    dir: string;
+    written: number;
+    paths: string[];
+};
+/**
+ * A response that carries a claim: an object property `claim` with a string
+ * `url` (typeship's anonymous generate is one). The CLI tells the person
+ * where to claim and leaves a breadcrumb in the working directory so a
+ * later session (or `doctor`) can list what is still unclaimed.
+ */
+export declare function claimProperty(outputSchema: Record<string, unknown> | undefined): boolean;
+export interface ClaimBreadcrumb {
+    url: string;
+    expires_at?: string;
+    command: string;
+    created_at: string;
+}
+export declare function breadcrumbFile(cwd: string, bin: string): string;
+/** Append a claim to .<bin>/claims.json (git-ignored when a .gitignore exists). */
+export declare function recordClaim(cwd: string, bin: string, crumb: ClaimBreadcrumb): string;
+/** Claims on file that have not expired. */
+export declare function pendingClaims(cwd: string, bin: string): ClaimBreadcrumb[];
+export interface DoctorCheck {
+    name: string;
+    ok: boolean;
+    detail?: string;
+    fix?: string;
+}
+export declare function summarizeDoctor(checks: DoctorCheck[]): {
+    status: "ok" | "action_required";
+    checks: DoctorCheck[];
+    next_steps: string[];
+};
+//# sourceMappingURL=cli-agent.d.ts.map