clyops-api 0.2.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dan VerWeire
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -7,7 +7,7 @@ becomes a `POST` endpoint whose JSON body is validated against the tool's own
 return a job to poll.
 
 ```sh
-npm install -g clyops-api
+pnpm add --global clyops-api
 clyops-api --root ~/mytool/scripts            # http://127.0.0.1:8080
 ```
 
@@ -161,3 +161,8 @@ Watching is off by default in the library (`watch: true` turns it on, `onReload`
 new set) and on by default in the `clyops-api` command.
 
 `loadTools(root)` and `runTool(tool, input)` are exported for other servers.
+
+`--positionals-order first|last` controls generated argument order (default:
+`first`). An option terminator is only emitted for positional values starting
+with `-`, which are always placed after the options. The Node API exposes this
+as `positionalsOrder`.

package/dist/cli.js

@@ -26,6 +26,7 @@ cli.optArray('CLYOPS_API_PATHS_WITHIN', 'paths-within', '', 'Path inputs must re
 cli.opt('CLYOPS_API_MAX_BODY', 'max-body', '', '10485760', 'Largest request body in bytes: JSON, multipart or spooled for an async job', 'Security', 'int:1-');
 cli.opt('CLYOPS_API_MAX_OUTPUT', 'max-output', '', '16777216', 'Keep at most this many bytes of a tool\'s stdout and stderr (0: all)', 'Security', 'int:0-');
 cli.opt('CLYOPS_API_AUDIT', 'audit', '', 'optional', 'Append a JSON line per run to this file (-: stderr)', 'Security', 'path');
+cli.opt('CLYOPS_API_POSITIONALS_ORDER', 'positionals-order', '', 'first', 'Positionals before or after options', 'Tools', 'choice:first,last');
 const args = cli.run();
 let keys;
 if (args.CLYOPS_API_KEYS) {
@@ -41,6 +42,7 @@ const { app, current } = await createApi({
     root: args.CLYOPS_API_ROOT,
     name: args.CLYOPS_API_NAME ?? undefined,
     cwd: args.CLYOPS_API_CWD ?? undefined,
+    positionalsOrder: args.CLYOPS_API_POSITIONALS_ORDER,
     timeoutMs: args.CLYOPS_API_TIMEOUT * 1000,
     concurrency: args.CLYOPS_API_CONCURRENCY ?? undefined,
     apiKey: args.CLYOPS_API_API_KEY ?? undefined,

package/dist/server.d.ts

@@ -1,6 +1,6 @@
 import { type AuditEntry, type Group, type Tool, type ToolFilter, type ToolResult } from 'clyops-tools';
 import { JobQueue } from 'clyops-jobs';
-import { type NextFunction, type Request, type Response } from 'express';
+import express, { type NextFunction, type Request, type Response } from 'express';
 /** A named API key and what it may run: globs over tool words (see clyops-tools' ToolFilter). */
 export interface ApiKey {
     key: string;
@@ -8,6 +8,8 @@ export interface ApiKey {
     deny?: string[];
 }
 export interface ApiOptions {
+    /** Positionals before or after options (default: first). */
+    positionalsOrder?: 'first' | 'last';
     /** Tools directory or dispatcher definition file. */
     root: string;
     /** API title (default: the root's name). */
@@ -57,7 +59,7 @@ type ApiResult = ToolResult & {
  * are fixed when the app is built.
  */
 export declare function createApi(opts: ApiOptions): Promise<{
-    app: import("express-serve-static-core").Express;
+    app: express.Express;
     queue: JobQueue<ApiResult>;
     /** The tree and tools being served now. */
     current: () => {

package/dist/server.js

@@ -236,7 +236,7 @@ export async function createApi(opts) {
                 instructions: api.tree.description || undefined,
                 tools: caller?.filter ? api.tools.filter((t) => allowed(t, caller.filter)) : api.tools,
                 cwd: opts.cwd,
-                timeoutMs: opts.timeoutMs,
+                timeoutMs: opts.timeoutMs, positionalsOrder: opts.positionalsOrder,
                 within: opts.within,
                 maxOutput: opts.maxOutput,
                 audit: opts.audit && ((entry) => opts.audit?.({ ...entry, key: caller?.name })),
@@ -293,7 +293,7 @@ async function runBody(opts, ctx, tool, req, res) {
  */
 async function respond(opts, ctx, tool, input, req, res, stdin, dir) {
     const caller = res.locals.caller;
-    const base = { cwd: opts.cwd, timeoutMs: opts.timeoutMs, within: opts.within, maxOutput: opts.maxOutput };
+    const base = { cwd: opts.cwd, timeoutMs: opts.timeoutMs, positionalsOrder: opts.positionalsOrder, within: opts.within, maxOutput: opts.maxOutput };
     const open = () => (typeof stdin === 'string' ? createReadStream(stdin) : stdin);
     const audit = (result) => opts.audit?.({
         key: caller?.name, tool: tool.words.join(' '), command: result.command, exitCode: result.exitCode, signal: result.signal,
@@ -307,7 +307,7 @@ async function respond(opts, ctx, tool, input, req, res, stdin, dir) {
             if (toFile) {
                 const started = startTool(tool, input, { ...base, signal, stdin: open(), stdout: 'stream' });
                 const [r] = await Promise.all([started.result, pipeline(started.stdout, createWriteStream(join(jobDir, 'stdout')))]);
-                result = { ...r, ok: r.exitCode === 0, stdoutUrl: `/jobs/${job.record.job_id}/stdout` };
+                result = { ...r, ok: r.exitCode === 0 && !r.timedOut && !r.signal, stdoutUrl: `/jobs/${job.record.job_id}/stdout` };
             }
             else {
                 result = envelope(await runTool(tool, input, { ...base, signal, stdin: open(), stdout: binaryStdout(tool) ? 'buffer' : 'text' }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clyops-api",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Serve a directory of clyops tools as an HTTP API: an endpoint per tool, validated and documented in OpenAPI from its schema, with sync and async (job) runs.",
   "license": "MIT",
   "repository": {
@@ -35,18 +35,12 @@
     "dist",
     "src"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json && chmod +x dist/cli.js",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "node --test test/*.test.mjs",
-    "prepublishOnly": "npm run build && npm test"
-  },
   "dependencies": {
     "busboy": "^1.6.0",
-    "clyops": "0.2.0",
-    "clyops-jobs": "0.2.0",
-    "clyops-mcp": "0.2.0",
-    "clyops-tools": "0.2.0",
+    "clyops": "0.3.0",
+    "clyops-jobs": "0.3.0",
+    "clyops-mcp": "0.3.0",
+    "clyops-tools": "0.3.0",
     "express": "^5.2.1",
     "plus-express": "^2.1.1"
   },
@@ -56,5 +50,10 @@
     "@types/express": "^5.0.0",
     "@types/node": "^22.0.0",
     "typescript": "^5.6.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/cli.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test test/*.test.mjs"
   }
-}
+}

package/src/cli.ts

@@ -28,6 +28,7 @@ cli.optArray('CLYOPS_API_PATHS_WITHIN', 'paths-within', '',               'Path
 cli.opt('CLYOPS_API_MAX_BODY',          'max-body',     '',  '10485760',  'Largest request body in bytes: JSON, multipart or spooled for an async job', 'Security', 'int:1-');
 cli.opt('CLYOPS_API_MAX_OUTPUT',        'max-output',   '',  '16777216',  'Keep at most this many bytes of a tool\'s stdout and stderr (0: all)', 'Security', 'int:0-');
 cli.opt('CLYOPS_API_AUDIT',             'audit',        '',  'optional',  'Append a JSON line per run to this file (-: stderr)', 'Security', 'path');
+cli.opt('CLYOPS_API_POSITIONALS_ORDER', 'positionals-order', '', 'first', 'Positionals before or after options', 'Tools', 'choice:first,last');
 const args = cli.run();
 
 let keys: Record<string, ApiKey> | undefined;
@@ -44,6 +45,7 @@ const { app, current } = await createApi({
   root: args.CLYOPS_API_ROOT as string,
   name: (args.CLYOPS_API_NAME as string | null) ?? undefined,
   cwd: (args.CLYOPS_API_CWD as string | null) ?? undefined,
+  positionalsOrder: args.CLYOPS_API_POSITIONALS_ORDER as 'first' | 'last',
   timeoutMs: (args.CLYOPS_API_TIMEOUT as number) * 1000,
   concurrency: (args.CLYOPS_API_CONCURRENCY as number | null) ?? undefined,
   apiKey: (args.CLYOPS_API_API_KEY as string | null) ?? undefined,

package/src/server.ts

@@ -7,7 +7,7 @@ import {
 import { JobQueue, type JobRecord } from 'clyops-jobs';
 import { mcpHttpHandler } from 'clyops-mcp';
 import busboy from 'busboy';
-import express, { type NextFunction, type Request, type Response } from 'express';
+import express, { type Express, type NextFunction, type Request, type Response } from 'express';
 import { createReadStream, createWriteStream, existsSync, mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { basename, join } from 'node:path';
@@ -24,6 +24,8 @@ export interface ApiKey {
 }
 
 export interface ApiOptions {
+  /** Positionals before or after options (default: first). */
+  positionalsOrder?: 'first' | 'last';
   /** Tools directory or dispatcher definition file. */
   root: string;
   /** API title (default: the root's name). */
@@ -242,7 +244,7 @@ export async function createApi(opts: ApiOptions) {
     : undefined;
   swap(watcher ? watcher.current() : await loadTools(opts.root, { name: opts.name, filter: opts.filter, onError }));
 
-  const app = express();
+  const app: Express = express();
   app.use(express.json({ limit: maxBody }));
   const keys = Object.entries(opts.keys ?? {});
   if (opts.apiKey || keys.length) {
@@ -285,7 +287,7 @@ export async function createApi(opts: ApiOptions) {
         instructions: api.tree.description || undefined,
         tools: caller?.filter ? api.tools.filter((t) => allowed(t, caller.filter as ToolFilter)) : api.tools,
         cwd: opts.cwd,
-        timeoutMs: opts.timeoutMs,
+        timeoutMs: opts.timeoutMs, positionalsOrder: opts.positionalsOrder,
         within: opts.within,
         maxOutput: opts.maxOutput,
         audit: opts.audit && ((entry) => opts.audit?.({ ...entry, key: caller?.name })),
@@ -344,7 +346,7 @@ async function runBody(opts: ApiOptions, ctx: Ctx, tool: ApiTool, req: Request,
 async function respond(opts: ApiOptions, ctx: Ctx, tool: ApiTool, input: Record<string, unknown>, req: Request, res: Response,
   stdin?: string | Readable, dir?: string): Promise<void> {
   const caller = res.locals.caller as Caller | undefined;
-  const base: ToolRunOptions = { cwd: opts.cwd, timeoutMs: opts.timeoutMs, within: opts.within, maxOutput: opts.maxOutput };
+  const base: ToolRunOptions = { cwd: opts.cwd, timeoutMs: opts.timeoutMs, positionalsOrder: opts.positionalsOrder, within: opts.within, maxOutput: opts.maxOutput };
   const open = () => (typeof stdin === 'string' ? createReadStream(stdin) : stdin);
   const audit = (result: RunResult) => opts.audit?.({
     key: caller?.name, tool: tool.words.join(' '), command: result.command, exitCode: result.exitCode, signal: result.signal,
@@ -359,7 +361,7 @@ async function respond(opts: ApiOptions, ctx: Ctx, tool: ApiTool, input: Record<
       if (toFile) {
         const started = startTool(tool, input, { ...base, signal, stdin: open(), stdout: 'stream' });
         const [r] = await Promise.all([started.result, pipeline(started.stdout, createWriteStream(join(jobDir, 'stdout')))]);
-        result = { ...r, ok: r.exitCode === 0, stdoutUrl: `/jobs/${job.record.job_id}/stdout` };
+        result = { ...r, ok: r.exitCode === 0 && !r.timedOut && !r.signal, stdoutUrl: `/jobs/${job.record.job_id}/stdout` };
       } else {
         result = envelope(await runTool(tool, input, { ...base, signal, stdin: open(), stdout: binaryStdout(tool) ? 'buffer' : 'text' }));
       }