import fs from 'node:fs';
import path from 'node:path';
import { API_OPERATIONS } from '../src/web/api-catalog.js';

const rows = API_OPERATIONS.map((operation) =>
  `| \`${operation.method}\` | \`${operation.path}\` | ${operation.summary} | ${operation.access} | ${operation.mutates ? 'yes' : 'no'} |`,
).join('\n');

const document = `# RedditBot API

This file is generated from \`src/web/api-catalog.ts\`. Run \`npm run docs:api\`
after changing the HTTP surface. The live OpenAPI 3.1 document is available at
\`GET /api/openapi.json\`, and compact agent discovery is available at
\`GET /api/v1/capabilities\`.

## Authentication

The dashboard token is an administrator credential. Browser users can exchange
it for an HttpOnly, SameSite=Strict session; API clients can send it as a bearer
token.

Optional least-privilege bearer credentials are configured with:

- \`REDDIT_BOT_AGENT_READ_TOKEN\`: GET, HEAD, SSE, and private-media reads except debug routes.
- \`REDDIT_BOT_AGENT_CONTROL_TOKEN\`: read access plus mutations under \`/api/v1\`.

Control credentials cannot send messages, import sessions, activate accounts,
or update legacy configuration endpoints. Those operations require the
administrator dashboard token.

## Agent entry points

- \`GET /healthz\`: unauthenticated process liveness with no private state.
- \`GET /api/v1/readyz\`: component readiness and authentication degradation.
- \`GET /api/v1/overview\`: bot, account, sync, rate-limit, and recent-error snapshot.
- \`GET /api/v1/control\`: current running state.
- \`POST /api/v1/control/start\`, \`/stop\`, or \`POST /api/v1/control\`: explicit bot control.
- \`POST /api/v1/jobs\`: tracked chat/media sync; poll \`GET /api/v1/jobs/:id\`.
- \`GET /api/events/stream\`: replayable typed SSE events.

## MCP server

Run the stdio MCP adapter with \`npm run mcp\`. It connects to
\`REDDIT_BOT_API_URL\` (default \`http://127.0.0.1:3000\`) and reads its bearer
credential from \`REDDIT_BOT_AGENT_TOKEN\`, then the scoped agent variables, and
finally \`WEB_DASHBOARD_TOKEN\`.

Read tools cover overview, readiness, accounts, activity, conversations,
errors, sync state, and performance. Control tools include \`start_bot\`,
\`stop_bot\`, \`set_bot_running\`, \`trigger_sync\`, and \`get_job\`. External
message tools are separately annotated as destructive/non-idempotent and need
an administrator credential.

## Operations

| Method | Path | Summary | Access | Mutates |
|---|---|---|---|---|
${rows}

## Error model

Errors use JSON with an \`error\` string and optional \`detail\`. Authentication
failures are \`401\`; recognized but insufficient agent credentials receive
\`403\`; invalid inputs receive \`400\`; unavailable services receive \`503\`.
Long-running agent jobs expose failure text in the job resource.
`;

const target = path.resolve(process.cwd(), 'docs/api.md');
if (process.argv.includes('--check')) {
  if (!fs.existsSync(target) || fs.readFileSync(target, 'utf8') !== document) {
    process.stderr.write('docs/api.md is stale; run npm run docs:api\n');
    process.exitCode = 1;
  }
} else {
  fs.writeFileSync(target, document);
}