@crouter/api 0.3.377

package/README.md

@@ -0,0 +1,67 @@
+# @crouter/api — the typed client and contract for the crtrd `/v1` API
+
+![crouter](https://raw.githubusercontent.com/crouton-labs/crouter/main/assets/banner.svg)
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@crouter/api"><img alt="npm" src="https://img.shields.io/npm/v/@crouter/api?label=npm"></a>
+  <a href="https://github.com/crouton-labs/crouter/blob/main/LICENSE"><img alt="license" src="https://img.shields.io/badge/license-GPL--3.0-blue"></a>
+</p>
+
+`@crouter/api` is the low-level contract for the crouter daemon's `/v1` HTTP API: the `CrtrClient` class, route builders, the API error type, request and response types (DTOs), and the schema for command-plugin manifests. It has no runtime dependencies and no install scripts.
+
+It is not the package most applications want. [`@crouter/sdk`](https://www.npmjs.com/package/@crouter/sdk) is built on it and adds run management, streaming, typed results and OAuth. Use `@crouter/api` when you need the wire contract itself — a thin client, a proxy, or tooling that validates plugin manifests.
+
+[Docs](https://docs.crouter.ai/docs/sdk) · [SDK resource map](https://docs.crouter.ai/docs/sdk/resources) · [crouter repository](https://github.com/crouton-labs/crouter) · [Source](https://github.com/crouton-labs/crouter/tree/main/src/api)
+
+## Install
+
+```bash
+npm install @crouter/api
+```
+
+The package is ESM-only. Import it from an ES module, or use dynamic `import()` from CommonJS. A crouter daemon (`npm install -g crouter`) must be reachable for any request.
+
+## Connect to a daemon
+
+`CrtrClient` is the typed HTTP client. Give it a TCP base URL and any required bearer header. `crtr sys connect` prints both for a local daemon.
+
+```ts
+import { CrtrClient } from '@crouter/api';
+
+const client = new CrtrClient({
+  baseUrl: 'https://my-crtrd.example.com',
+  headers: { authorization: 'Bearer a-daemon-token' },
+});
+
+const nodes = await client.listNodes();
+console.log(nodes.map((node) => node.node_id));
+```
+
+For the local Unix socket, import the Node-only entry point:
+
+```ts
+import { localClient } from '@crouter/api/node';
+
+const client = localClient();
+console.log(await client.healthz());
+```
+
+## Exports
+
+- `CrtrClient` and `waitForDaemonAvailability` for typed `/v1` requests.
+- `routes` and `API_VERSION` for route construction.
+- `ApiError`, `APIError`, `ErrorBody` and `isErrorBody` for the API error contract.
+- DTOs for canvas, nodes, reports, lifecycle, files, bash, memory, models, human requests, crons, reviews and related routes.
+- `@crouter/api/node` — `defaultSocketPath`, `socketFetch` and `localClient`.
+- `@crouter/api/plugin-manifest` and `@crouter/api/command-manifest` — the plugin command-manifest schema and validation types.
+- `@crouter/api/cards` — generated context types.
+
+## Related
+
+- [`@crouter/sdk`](../crouter-sdk) — the client most applications should use.
+- [`@crouter/plugin`](../crouter-plugin) — author plugins whose manifests use this package's types.
+- [Main repository](https://github.com/crouton-labs/crouter) — the `crtr` CLI, the `crtrd` daemon, and contribution guidelines.
+
+## License
+
+[GPL-3.0-only](https://github.com/crouton-labs/crouter/blob/main/LICENSE).

package/dist/api/__tests__/error-codes.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/api/__tests__/error-codes.test.js

@@ -0,0 +1,78 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import ts from 'typescript';
+import { errorCodes } from '../error-codes.js';
+test('SDK and API expose one fixed code table with contract 2 tuples', () => {
+    assert.deepEqual(errorCodes.server_error, { type: 'server_error', status: 500, retryable: true });
+    assert.deepEqual(errorCodes.runtime_starting, { type: 'server_error', status: 503, retryable: true });
+    assert.deepEqual(errorCodes.payer_not_app, { type: 'permission_error', status: 403, retryable: false });
+    assert.deepEqual(errorCodes.cap_exhausted, { type: 'rate_limit_error', status: 402, retryable: false });
+    assert.deepEqual(errorCodes.concurrency_limit, { type: 'rate_limit_error', status: 429, retryable: true });
+    for (const code of ['grant_revoked', 'grant_removed', 'grant_suspended', 'refresh_token_expired', 'refresh_token_reused']) {
+        assert.deepEqual(errorCodes[code], { type: 'authentication_error', status: 401, retryable: false }, code);
+    }
+    assert.equal('provider_error' in errorCodes, false); // provider's 4xx status varies
+    assert.equal('usage' in errorCodes, false); // legacy socket-only code
+    assert.equal('stream_gap' in errorCodes, false); // stream protocol, not a fixed HTTP row
+});
+test('every statically named RunError and ProviderError agrees with the fixed table', () => {
+    const src = fileURLToPath(new URL('../..', import.meta.url));
+    const files = (dir) => readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+        const path = join(dir, entry.name);
+        return entry.isDirectory() ? files(path) : entry.name.endsWith('.ts') && !path.includes('/__tests__/') ? [path] : [];
+    });
+    const literals = (expr) => {
+        if (ts.isStringLiteral(expr) || ts.isNumericLiteral(expr))
+            return [ts.isNumericLiteral(expr) ? Number(expr.text) : expr.text];
+        if (ts.isConditionalExpression(expr))
+            return [...literals(expr.whenTrue), ...literals(expr.whenFalse)];
+        return [];
+    };
+    let checked = 0;
+    for (const path of files(src)) {
+        const source = ts.createSourceFile(path, readFileSync(path, 'utf8'), ts.ScriptTarget.Latest, true);
+        const visit = (node) => {
+            if (ts.isNewExpression(node) && ts.isIdentifier(node.expression) && ['RunError', 'ProviderError'].includes(node.expression.text)) {
+                const args = node.arguments ?? [];
+                const run = node.expression.text === 'RunError';
+                const codes = args[run ? 1 : 0] ? literals(args[run ? 1 : 0]) : [];
+                const statuses = run && args[0] ? literals(args[0]) : [];
+                const options = !run && args[2] && ts.isObjectLiteralExpression(args[2]) ? args[2] : undefined;
+                const override = options?.properties.find((prop) => ts.isPropertyAssignment(prop) && prop.name.getText(source) === 'status');
+                const providerStatuses = override && ts.isPropertyAssignment(override) ? literals(override.initializer) : [];
+                for (const code of codes) {
+                    if (typeof code !== 'string' || ['provider_error', 'usage', 'stream_gap', 'stream_dropped', 'stream_error'].includes(code))
+                        continue;
+                    const row = errorCodes[code];
+                    assert.ok(row, `${path}:${source.getLineAndCharacterOfPosition(node.pos).line + 1}: ${code} missing from errorCodes`);
+                    for (const status of run ? statuses : providerStatuses)
+                        assert.equal(status, row.status, `${path}: ${code} status`);
+                    if (run && args[6] && args[6].kind !== ts.SyntaxKind.UndefinedKeyword && args[6].kind !== ts.SyntaxKind.NullKeyword) {
+                        const retry = args[6].kind === ts.SyntaxKind.TrueKeyword ? true : args[6].kind === ts.SyntaxKind.FalseKeyword ? false : undefined;
+                        if (retry !== undefined)
+                            assert.equal(retry, row.retryable, `${path}: ${code} retryable`);
+                    }
+                    else if (run && statuses.length) {
+                        for (const status of statuses)
+                            assert.equal(status === 503, row.retryable, `${path}: ${code} default retryable`);
+                    }
+                    checked++;
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(source);
+    }
+    assert.ok(checked > 100, `checked only ${checked} throw sites`);
+});
+test('app origin belongs to the full HTTP envelope without a body status', () => {
+    const row = errorCodes.invalid_request;
+    const body = { error: { code: 'invalid_request', message: 'Missing prompt',
+            type: row.type, origin: 'app', retryable: row.retryable, request_id: 'request-1', param: 'prompt' } };
+    assert.equal(body.error.origin, 'app');
+    assert.equal('status' in body.error, false);
+    assert.equal(row.status, 400);
+});

package/dist/api/__tests__/integration/client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/api/__tests__/integration/client.test.js

@@ -0,0 +1,179 @@
+// Client availability recovery regressions.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createServer } from 'node:http';
+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { CrtrClient, safeColdStartDiagnostic } from '../../client.js';
+import { localClient } from '../../node-transport.js';
+import { ApiError } from '../../errors.js';
+function startDelayedHealthzServer(socketPath, delayMs) {
+    const server = createServer((_req, res) => {
+        res.writeHead(200, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ ok: true }));
+    });
+    const timer = setTimeout(() => server.listen(socketPath), delayMs);
+    return { server, cancel: () => clearTimeout(timer) };
+}
+// A dropped response is distinct from a refused connect. Its cause is unknown, so reads may wait and retry but mutations never replay.
+function startHandoverServer(socketPath) {
+    let dropped = false;
+    const server = createServer((req, res) => {
+        if (!dropped) {
+            dropped = true; // model the old server dying mid-request
+            req.socket.destroy();
+            return;
+        }
+        res.writeHead(200, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ ok: true, method: req.method }));
+    });
+    return {
+        server,
+        ready: new Promise((resolvePromise) => server.listen(socketPath, resolvePromise)),
+    };
+}
+test('a hang-up mid-request rides out the daemon handover and replays the idempotent call', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-client-handover-'));
+    const socketPath = join(dir, 'crtrd.sock');
+    const { server, ready } = startHandoverServer(socketPath);
+    try {
+        await ready;
+        const client = localClient({ socketPath, autostart: false, coldStartPollWindowMs: 2_000 });
+        assert.deepEqual(await client.request('GET', '/v1/nodes'), { ok: true, method: 'GET' });
+    }
+    finally {
+        server.close();
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('an interrupted mutation is not replayed or labelled a daemon handover', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-client-handover-'));
+    const socketPath = join(dir, 'crtrd.sock');
+    const { server, ready } = startHandoverServer(socketPath);
+    try {
+        await ready;
+        const client = localClient({ socketPath, autostart: false, coldStartPollWindowMs: 2_000 });
+        await assert.rejects(() => client.request('POST', '/v1/nodes', {}), 
+        // Replaying is unsafe (the daemon may have applied it), so this one is the
+        // caller's call — but it must not be reported as a daemon that is down.
+        (err) => err instanceof ApiError && err.code === 'daemon_request_interrupted');
+    }
+    finally {
+        server.close();
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('a non-socket cold-start path surfaces its diagnostic after autostart times out', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-client-nonsocket-'));
+    const socketPath = join(dir, 'crtrd.sock');
+    mkdirSync(socketPath);
+    const diagnostic = 'crtrd.log (tail):\napi.server.failed: EADDRINUSE';
+    const client = localClient({
+        socketPath,
+        autostart: true,
+        onColdSocket: async () => { },
+        coldStartPollWindowMs: 50,
+        coldStartDiagnostic: () => diagnostic,
+    });
+    try {
+        await assert.rejects(() => client.healthz(), (error) => error instanceof ApiError
+            && error.code === 'daemon_unavailable'
+            && error.message.includes(diagnostic));
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('cliClient-style cold start fails loud when the injected poll window is shorter than the (valid) startup delay', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-client-coldstart-'));
+    const socketPath = join(dir, 'crtrd.sock');
+    const { server, cancel } = startDelayedHealthzServer(socketPath, 300);
+    try {
+        const client = localClient({
+            socketPath,
+            autostart: true,
+            onColdSocket: async () => {
+                /* fire-and-forget: the delayed listen() above models ensureDaemon() */
+            },
+            coldStartPollWindowMs: 100, // shorter than the 300ms the daemon actually needs
+        });
+        await assert.rejects(() => client.healthz(), (err) => err instanceof ApiError && err.code === 'daemon_unavailable');
+    }
+    finally {
+        cancel(); // the client already timed out at 100ms; never let listen() fire at 300ms
+        server.close();
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('a disabled-autostart client waits for an externally managed listener without invoking its spawn hook', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-client-coldstart-'));
+    const socketPath = join(dir, 'crtrd.sock');
+    const { server, cancel } = startDelayedHealthzServer(socketPath, 100);
+    let spawnAttempts = 0;
+    try {
+        const client = localClient({
+            socketPath,
+            autostart: false,
+            onColdSocket: async () => { spawnAttempts += 1; },
+            coldStartPollWindowMs: 1_000,
+        });
+        assert.deepEqual(await client.request('GET', '/v1/nodes'), { ok: true });
+        assert.equal(spawnAttempts, 0, 'disabled autostart only waits; it never invokes the spawn hook');
+    }
+    finally {
+        cancel();
+        server.close();
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('availability expiry keeps the final transport failure inside one wall-clock budget', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'crtr-client-coldstart-'));
+    const socketPath = join(dir, 'crtrd.sock');
+    const server = createServer((_req, _res) => { });
+    let listenTimer;
+    try {
+        const client = localClient({
+            socketPath,
+            autostart: true,
+            timeoutMs: 5_000,
+            coldStartPollWindowMs: 250,
+            onColdSocket: async () => { listenTimer = setTimeout(() => server.listen(socketPath), 10); },
+        });
+        const started = Date.now();
+        await assert.rejects(() => client.healthz(), (error) => error instanceof ApiError && error.code === 'request_timeout' && error.message.includes('request timed out'));
+        assert.ok(Date.now() - started < 500, 'a probe cannot extend the 250ms availability budget');
+    }
+    finally {
+        if (listenTimer !== undefined)
+            clearTimeout(listenTimer);
+        server.close();
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('a caller abort with a custom reason is request_aborted', async () => {
+    const controller = new AbortController();
+    const client = new CrtrClient({
+        baseUrl: 'http://fixture.test',
+        fetch: async (_input, init) => await new Promise((_resolve, reject) => {
+            const signal = init?.signal;
+            if (signal === null || signal === undefined)
+                throw new Error('request signal is required');
+            signal.addEventListener('abort', () => reject(signal.reason), { once: true });
+        }),
+    });
+    const request = client.request('GET', '/healthz', undefined, { signal: controller.signal });
+    controller.abort(new Error('caller custom abort'));
+    await assert.rejects(request, (error) => error instanceof ApiError && error.code === 'request_aborted');
+});
+test('safeColdStartDiagnostic returns undefined for an absent hook', () => {
+    assert.equal(safeColdStartDiagnostic(undefined), undefined);
+});
+test('safeColdStartDiagnostic returns the hook result when it succeeds', () => {
+    assert.equal(safeColdStartDiagnostic(() => 'crtrd.log (tail):\nboom'), 'crtrd.log (tail):\nboom');
+});
+test('safeColdStartDiagnostic treats a THROWING hook as absent, not a propagated error', () => {
+    assert.equal(safeColdStartDiagnostic(() => {
+        throw new Error('custom hook blew up');
+    }), undefined);
+});