@3minapi/cli 0.0.0-stage → 0.22.0

package/dist/modules/workers/template.js

@@ -0,0 +1,100 @@
+const HEADER = (name) => `// Worker "${name}" — runs on this machine as a local worker when an AI creates a task for it.
+// One file = one worker. The file name is the worker name.
+// Code edits take effect on the next task. A renamed file or a changed description
+// reaches 3Min API on '3minapi reload' (or the next '3minapi start').`;
+export const SETTINGS = `/**
+ * What this worker does (max 500 characters). This is the only thing the AI sees
+ * about the worker: it decides when to call it and what input to send from this text.
+ * To tell the AI the input shape, write it here (inputSchema below is not sent).
+ * EXAMPLE — describe your own worker.
+ */
+export const description = 'Echo back the message it receives. input: { message: string }';
+
+/** Optional. The run is stopped and reported as failed after this long (default 60s). */
+export const timeoutMs = 60_000;
+
+/**
+ * Optional. JSON Schema for the task input — an EXAMPLE matching the handler below.
+ * Replace it with your own fields, or delete it to accept any input.
+ * Checked on this machine only: it is not sent to 3Min API, so the AI does not see it.
+ * A task whose input does not match is reported as failed before the handler runs.
+ * Supported keywords: type, properties, required, enum, items.
+ */
+export const inputSchema = {
+	type: 'object',
+	properties: {
+		message: { type: 'string', description: 'Text to echo' } // example field
+	},
+	required: ['message']
+};`;
+export const HANDLER_DOC = `/**
+ * Runs once per task.
+ *
+ * input — the JSON the AI sent with the task (any shape, up to 100 KB).
+ *
+ * How the task ends:
+ *   return value      → completed; the value becomes the result (JSON). Every result
+ *                       is saved in the project's data.db ('3minapi worker results').
+ *                       Over 100 KB: a local worker sends the AI a summary instead;
+ *                       a public worker's task fails. A top-level "_3minapi" key is
+ *                       reserved — the task fails.
+ *   throw new Error() → failed; only the message is sent to the AI, with its causes
+ *                       (err.cause) on the same line, cut at 4,000 characters. The
+ *                       stack trace stays in the local log.
+ *   timeoutMs passed  → failed
+ *   cancelled         → set by the requester, not by the worker. ctx.signal fires:
+ *                       stop work and return. The return value is ignored.
+ *
+ * ctx:
+ *   ctx.log(msg)        write to this worker's log ('3minapi worker logs <name>')
+ *   await ctx.report(m) send a progress message to the AI while working
+ *                       (max 256 characters; each report counts as one API call)
+ *   ctx.signal          AbortSignal — aborted on cancel or timeout
+ *   ctx.env             environment variables, including the project's .env
+ *                       (THREEMINAPI_* variables are removed)
+ *
+ * Need to keep data between tasks? Use the project's data.db (made by '3minapi init').
+ * 3minapi saves results there in tables starting with _3minapi_ — read them if you
+ * like, but do not write them. Open it with Node's built-in node:sqlite:
+ *   import { DatabaseSync } from 'node:sqlite';
+ *   const db = new DatabaseSync(new URL('../data.db', import.meta.url), { timeout: 5000 });
+ *   db.exec('PRAGMA journal_mode = WAL'); // tasks can run at the same time
+ *   try { ... } finally { db.close(); }
+ * The URL is relative to this file (default workers/ folder), so it does not depend on
+ * the current folder.
+ */`;
+const HANDLER_BODY = `	ctx.log(\`received: \${input.message}\`);
+
+	// await ctx.report('halfway there');
+	// if (!input.message.trim()) throw new Error('message is empty');
+
+	return { echo: input.message };
+}
+`;
+export function jsTemplate(name) {
+    return `${HEADER(name)}
+
+${SETTINGS}
+
+${HANDLER_DOC}
+export async function handler(input, ctx) {
+${HANDLER_BODY}`;
+}
+export function tsTemplate(name) {
+    return `${HEADER(name)}
+// TypeScript runs without a build step (Node type stripping): use plain type
+// annotations, not enums or namespaces. Types are not checked at run time.
+
+interface Context {
+	log(message: string): void;
+	report(message: string): Promise<void>;
+	signal: AbortSignal;
+	env: Record<string, string | undefined>;
+}
+
+${SETTINGS}
+
+${HANDLER_DOC}
+export async function handler(input: any, ctx: Context) {
+${HANDLER_BODY}`;
+}

package/dist/modules/workers/worker-set.js

@@ -0,0 +1,122 @@
+export class WorkerSet {
+    local;
+    rejected = new Map();
+    pushServed = new Set();
+    deleted = new Set();
+    unsent = new Set();
+    serverSeen = false;
+    server = new Set();
+    builtinName;
+    constructor(localNames, builtin = null) {
+        this.local = new Set(localNames);
+        this.builtinName = builtin;
+    }
+    get builtin() {
+        return this.builtinName;
+    }
+    get builtinActive() {
+        return this.builtinName !== null && this.isActive(this.builtinName);
+    }
+    applySync(res, ctx, unsent = []) {
+        for (const name of unsent)
+            this.unsent.add(name);
+        const real = [];
+        for (const r of res.rejected) {
+            if (ctx.public &&
+                r.code === 'worker_name_taken' &&
+                r.conflict?.kind === 'push' &&
+                ctx.hasPushKeys(r.name)) {
+                this.pushServed.add(r.name);
+            }
+            else {
+                this.rejected.set(r.name, r);
+                real.push(r);
+            }
+        }
+        this.server = new Set(res.workers.map((w) => w.name));
+        return real;
+    }
+    resync(localNames, res, ctx, unsent = [], builtin = this.builtinName) {
+        this.local = new Set(localNames);
+        this.builtinName = builtin;
+        this.rejected.clear();
+        this.pushServed.clear();
+        this.unsent.clear();
+        for (const w of res.workers)
+            this.deleted.delete(w.name);
+        this.serverSeen = false;
+        return this.applySync(res, ctx, unsent);
+    }
+    applyServerList(names) {
+        const before = this.activeNames({ builtin: true });
+        const first = !this.serverSeen;
+        this.server = new Set(names);
+        this.serverSeen = true;
+        const deleted = [];
+        const unregistered = [];
+        for (const name of before) {
+            if (this.isActive(name))
+                continue;
+            if (first && this.unsent.has(name)) {
+                unregistered.push(name);
+            }
+            else {
+                this.deleted.add(name);
+                deleted.push(name);
+            }
+        }
+        return { deleted, unregistered };
+    }
+    dropLocal(names) {
+        const dropped = [];
+        for (const name of names) {
+            if (!this.isActive(name))
+                continue;
+            this.deleted.add(name);
+            this.server.delete(name);
+            dropped.push(name);
+        }
+        return dropped.sort();
+    }
+    pendingNames() {
+        return this.serverSeen ? [] : [...this.unsent].filter((n) => this.local.has(n)).sort();
+    }
+    isActive(name) {
+        if (!this.local.has(name) && name !== this.builtinName)
+            return false;
+        if (this.pushServed.has(name))
+            return true;
+        if (this.rejected.has(name) || this.deleted.has(name))
+            return false;
+        if (!this.serverSeen && this.unsent.has(name))
+            return true;
+        return this.server.has(name);
+    }
+    inactiveReason(name) {
+        if (this.isActive(name))
+            return null;
+        if (this.rejected.has(name))
+            return 'rejected';
+        if (this.deleted.has(name))
+            return 'deleted_on_server';
+        return 'not_on_server';
+    }
+    activeNames({ builtin = false } = {}) {
+        const names = [...this.local];
+        if (builtin && this.builtinName !== null)
+            names.push(this.builtinName);
+        return names.filter((n) => this.isActive(n)).sort();
+    }
+    get activeCount() {
+        return this.activeNames().length;
+    }
+    get pullActiveCount() {
+        return this.activeNames().filter((n) => !this.pushServed.has(n)).length;
+    }
+    pushServedNames() {
+        return [...this.pushServed].sort();
+    }
+    deletedNames() {
+        return [...this.deleted].sort();
+    }
+}

package/dist/modules/workers/workers.js

@@ -0,0 +1,66 @@
+import { readdirSync } from 'node:fs';
+import path from 'node:path';
+import { CliError, WORKER_DESCRIPTION_MAX_CHARS, WORKER_EXTENSIONS } from "../../core/domain/index.js";
+import { checkWorkerName } from "../../core/names.js";
+import { inspectWorker } from "./runtime/inspect.js";
+const INSPECT_CONCURRENCY = 4;
+export function workerFiles(dir) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch (err) {
+        throw new CliError(`cannot read workers folder ${dir}: ${err.message}`);
+    }
+    const byName = new Map();
+    for (const entry of entries.sort()) {
+        const ext = path.extname(entry);
+        if (!WORKER_EXTENSIONS.includes(ext))
+            continue;
+        const name = entry.slice(0, -ext.length);
+        byName.set(name, [...(byName.get(name) ?? []), path.join(dir, entry)]);
+    }
+    return byName;
+}
+export async function collectWorkers(dir, env) {
+    const workers = [...workerFiles(dir)].map(([name, files]) => ({
+        name,
+        files,
+        problem: null,
+        message: null,
+        meta: null
+    }));
+    const toInspect = [];
+    for (const w of workers) {
+        const check = checkWorkerName(w.name);
+        if (!check.ok) {
+            w.problem = 'invalid_name';
+            w.message = `not a valid worker name (${check.reason}) — tasks cannot reach it`;
+        }
+        else if (w.files.length > 1) {
+            w.problem = 'duplicate';
+            w.message = 'more than one file with this name — keep only one';
+        }
+        else {
+            toInspect.push(w);
+        }
+    }
+    let next = 0;
+    const lane = async () => {
+        while (next < toInspect.length) {
+            const w = toInspect[next++];
+            const r = await inspectWorker(w.files[0], env);
+            if (r.ok)
+                w.meta = r.meta;
+            else {
+                w.problem = 'load_failed';
+                w.message = `${r.reason}: ${r.message}`;
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(INSPECT_CONCURRENCY, toInspect.length) }, lane));
+    return workers;
+}
+export function descriptionTooLong(description) {
+    return Array.from(description).length > WORKER_DESCRIPTION_MAX_CHARS;
+}

package/package.json

@@ -1,6 +1,49 @@
 {
-  "name": "@3minapi/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@3minapi/cli",
+	"version": "0.22.0",
+	"description": "Run your machine as a 3Min API host — the CLI that fetches tasks from your AI and runs them with your own worker files",
+	"keywords": [
+		"3minapi",
+		"mcp",
+		"ai",
+		"worker",
+		"cli",
+		"tasks"
+	],
+	"license": "MIT",
+	"author": "Maverick Works",
+	"homepage": "https://3minapi.com",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/maverick-works-dev/3minapi-cli.git"
+	},
+	"bugs": {
+		"url": "https://github.com/maverick-works-dev/3minapi-cli/issues"
+	},
+	"type": "module",
+	"bin": {
+		"3minapi": "dist/bin.js"
+	},
+	"files": [
+		"dist"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"engines": {
+		"node": ">=24.12.0"
+	},
+	"scripts": {
+		"dev": "node src/bin.ts",
+		"build": "node -e \"fs.rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
+		"prepack": "npm run build",
+		"test": "node --test --test-timeout=60000",
+		"lint": "tsc --noEmit && prettier --check .",
+		"format": "prettier --write ."
+	},
+	"devDependencies": {
+		"@types/node": "24.10.1",
+		"prettier": "3.7.3",
+		"typescript": "5.9.3"
+	}
+}