@3minapi/cli 0.0.0-stage → 0.22.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maverick Works
+
+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

@@ -1,3 +1,89 @@
-# Temporary Holding Version
+# 3minapi
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Run your own machine as a [3Min API](https://3minapi.com) host. An AI you work with (ChatGPT, Claude and other
+MCP clients) creates tasks; this CLI fetches them and runs them with worker files you write — plain JavaScript or
+TypeScript functions on your PC.
+
+- Node.js **24.12 or newer**, no runtime dependencies, no install scripts
+- Works on macOS, Linux and Windows
+
+## Install
+
+```sh
+npm install -g @3minapi/cli
+3minapi --version
+3minapi doctor        # checks Node.js, config, network and proxy settings
+```
+
+`npx @3minapi/cli <command>` runs it without installing. On Windows PowerShell, if scripts are disabled, type
+`3minapi.cmd` in place of `3minapi`.
+
+## Quick start
+
+1. **Create a host token** on the dashboard: [3minapi.com/dashboard/tasks/local](https://3minapi.com/dashboard/tasks/local).
+   It is shown once.
+2. **Log in** — the prompt is masked; the token is saved only on this machine.
+   ```sh
+   3minapi login
+   ```
+3. **Create the project** (default `~/3minapi`) and a worker:
+   ```sh
+   3minapi init
+   3minapi worker new hello
+   3minapi worker run hello --input '{"message":"hi"}'   # runs locally, no API calls
+   ```
+4. **Start the host** — registers the workers and runs tasks until stopped:
+   ```sh
+   3minapi start            # or: 3minapi start --detach, then 3minapi stop
+   ```
+
+Ask your AI to create a task for the `hello` worker; `3minapi status` and `3minapi logs` show what happened.
+
+## A worker
+
+One file in `workers/` is one worker. The AI reads `description`; `handler` gets the input the AI sent.
+
+```js
+export const description = 'Says hello. input: { message: string }';
+
+export async function handler(input, ctx) {
+	ctx.log(`got ${input.message}`);
+	return { reply: `hello, ${input.message}` };
+}
+```
+
+Returning completes the task with that value; throwing fails it with the error message. `ctx.signal` aborts on
+cancel or timeout. `3minapi worker new` writes a template that documents every option.
+
+## Using it from an AI coding agent
+
+`3minapi init` writes `AGENTS.md` (and a `CLAUDE.md` that imports it) into the project, so Claude Code, Codex and
+other agents know which files to edit, which commands to run and which files never to touch. The same text is
+printed by:
+
+```sh
+3minapi guide
+```
+
+Every command takes `--json` for machine-readable output. Log in yourself — never paste the host token into a chat.
+
+## Update
+
+```sh
+3minapi stop                 # if start is running
+npm install -g @3minapi/cli@latest
+```
+
+The CLI tells you when a newer version is recommended, and stops with exit code 6 when it is too old to connect.
+
+## Where releases come from
+
+Releases are built and published by GitHub Actions from the public repository
+[maverick-works-dev/3minapi-cli](https://github.com/maverick-works-dev/3minapi-cli), with npm provenance. The
+**Provenance** section on the npm package page links each version to the commit and workflow run that built it.
+
+## Links
+
+- Guide: [3minapi.com](https://3minapi.com)
+- Security policy: [SECURITY.md](SECURITY.md)
+- License: [MIT](LICENSE)

package/dist/bin.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import { EXIT_GRACE_MS, MIN_NODE_VERSION } from "./core/domain/constants.js";
+import { raiseConnectAttemptTimeout } from "./core/network.js";
+import { satisfiesMinNode } from "./core/version.js";
+import { suppressSqliteExperimentalWarning } from "./core/warnings.js";
+if (!satisfiesMinNode(process.versions.node)) {
+    const message = `3minapi requires Node.js ${MIN_NODE_VERSION} or later (you have ${process.versions.node}).\n` +
+        'Install the current Node.js 24 LTS from https://nodejs.org and try again.';
+    process.stderr.write(`error: ${message}\n`);
+    if (process.argv.includes('--json'))
+        process.stdout.write(JSON.stringify({ error: { kind: 'config', message, exitCode: 3 } }, null, 2) + '\n');
+    process.exit(3);
+}
+suppressSqliteExperimentalWarning();
+raiseConnectAttemptTimeout({ execArgv: process.execArgv, nodeOptions: process.env.NODE_OPTIONS });
+const interrupt = new AbortController();
+let claimed = false;
+const onSignal = () => {
+    if (claimed && !interrupt.signal.aborted)
+        interrupt.abort();
+    else
+        process.exit(130);
+};
+process.on('SIGINT', onSignal);
+process.on('SIGTERM', onSignal);
+for (const stream of [process.stdout, process.stderr]) {
+    stream.on('error', (err) => {
+        if (err.code === 'EPIPE')
+            process.exit(0);
+        throw err;
+    });
+}
+const { main } = await import("./cli.js");
+process.exitCode = await main(process.argv.slice(2), {
+    stdout: process.stdout,
+    stderr: process.stderr,
+    stdin: process.stdin,
+    env: process.env,
+    cwd: process.cwd(),
+    platform: process.platform,
+    home: (await import('node:os')).homedir(),
+    signal: interrupt.signal,
+    claimInterrupt: () => {
+        claimed = true;
+    }
+});
+const exitWhenFlushed = () => {
+    if (process.stdout.writableLength > 0 || process.stderr.writableLength > 0) {
+        setTimeout(exitWhenFlushed, EXIT_GRACE_MS).unref();
+        return;
+    }
+    process.exit();
+};
+setTimeout(exitWhenFlushed, EXIT_GRACE_MS).unref();

package/dist/cli.js

@@ -0,0 +1,241 @@
+import { readFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import { commands } from "./commands/index.js";
+import { loadConfig } from "./core/config.js";
+import { describeError, errorDocument } from "./core/error-report.js";
+import { BIN, CliError, ExitCode, UsageError } from "./core/domain/index.js";
+import { Output } from "./core/output.js";
+import { resolveDirs } from "./core/paths.js";
+import { resolveProject, writeProjectRecord } from "./core/project.js";
+import { GLOBAL_OPTIONS, commandHelp, commandHelpJson, groupHelp, groupHelpJson, rootHelp, rootHelpJson, suggest } from "./help.js";
+export const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+export async function main(argv, io) {
+    const out = new Output({
+        stdout: io.stdout,
+        stderr: io.stderr,
+        env: io.env,
+        json: argv.includes('--json'),
+        color: argv.includes('--no-color') ? false : argv.includes('--color') ? true : undefined
+    });
+    try {
+        return await dispatch(argv, io, out);
+    }
+    catch (err) {
+        const report = describeError(err);
+        if (report.kind === 'bug') {
+            out.error(`unexpected error: ${report.stack}`);
+            out.info('This is a bug in the CLI. Please report it with the output above.');
+        }
+        else {
+            out.error(report.message);
+        }
+        out.errorResult(errorDocument(report));
+        return report.exitCode;
+    }
+}
+async function dispatch(argv, io, out) {
+    const index = commandIndex(argv);
+    const name = index === -1 ? undefined : argv[index];
+    let rest = index === -1 ? argv : [...argv.slice(0, index), ...argv.slice(index + 1)];
+    const showRoot = () => out.result(rootHelpJson(commands, VERSION), rootHelp(commands, VERSION));
+    const showCommand = (c) => c.subcommands
+        ? out.result(groupHelpJson(c), groupHelp(c))
+        : out.result(commandHelpJson(c), commandHelp(c));
+    if (name === undefined) {
+        const { values } = parse(rest, GLOBAL_OPTIONS, false, null);
+        if (values.version) {
+            out.result({ version: VERSION }, VERSION);
+            return ExitCode.Ok;
+        }
+        showRoot();
+        return ExitCode.Ok;
+    }
+    if (name === 'help') {
+        const { positionals } = parse(rest, GLOBAL_OPTIONS, true, null);
+        if (positionals.length === 0) {
+            showRoot();
+            return ExitCode.Ok;
+        }
+        let target = findCommand(positionals[0]);
+        for (const p of positionals.slice(1)) {
+            if (!target.subcommands)
+                break;
+            target = findSub(target, p);
+        }
+        showCommand(target);
+        return ExitCode.Ok;
+    }
+    let cmd = findCommand(name);
+    while (cmd.subcommands) {
+        const i = commandIndex(rest);
+        if (i === -1) {
+            showCommand(cmd);
+            return ExitCode.Ok;
+        }
+        const sub = findSub(cmd, rest[i]);
+        rest = [...rest.slice(0, i), ...rest.slice(i + 1)];
+        cmd = sub;
+    }
+    if (rest.includes('--help') || rest.includes('-h')) {
+        showCommand(cmd);
+        return ExitCode.Ok;
+    }
+    const { values, positionals } = parse(rest, { ...GLOBAL_OPTIONS, ...cmd.options }, true, cmd.name);
+    if (values.version) {
+        out.result({ version: VERSION }, VERSION);
+        return ExitCode.Ok;
+    }
+    if (positionals.length < cmd.args.min || positionals.length > cmd.args.max) {
+        throw new UsageError(`usage: ${BIN} ${cmd.name} ${cmd.usage}\nRun '${BIN} help ${cmd.name}' for details.`);
+    }
+    const dirs = resolveDirs({ platform: io.platform, env: io.env, home: io.home });
+    let resolved;
+    let configWarned = false;
+    const ctx = {
+        positionals,
+        values,
+        out,
+        stdin: io.stdin,
+        env: io.env,
+        cwd: io.cwd,
+        home: io.home,
+        platform: io.platform,
+        dirs,
+        version: VERSION,
+        now: io.now ?? Date.now,
+        signal: io.signal ?? new AbortController().signal,
+        claimInterrupt: () => io.claimInterrupt?.(),
+        chdir: io.chdir ?? ((dir) => process.chdir(dir)),
+        loadConfig: () => {
+            const config = loadConfig({
+                cwd: io.cwd,
+                env: io.env,
+                configDir: dirs.config,
+                configFile: values.config,
+                ...(values.config === undefined ? { projectFile: hostProject() } : {}),
+                flags: configFlags(values, cmd.name)
+            });
+            if (!configWarned && cmd.name !== 'doctor') {
+                configWarned = true;
+                for (const w of config.warnings)
+                    out.warn(w);
+            }
+            return config;
+        }
+    };
+    return cmd.run(ctx);
+    function hostProject() {
+        if (resolved !== undefined)
+            return resolved;
+        const r = resolveProject({
+            cwd: io.cwd,
+            dataDir: dirs.data,
+            platform: io.platform,
+            home: io.home
+        });
+        if (r.record !== null) {
+            try {
+                writeProjectRecord(dirs.data, r.record, (io.now ?? Date.now)());
+            }
+            catch (err) {
+                out.warn(`could not record this host's project: ${err.message}`);
+            }
+        }
+        for (const notice of r.notices)
+            out.warn(notice);
+        resolved = r.projectFile;
+        return resolved;
+    }
+}
+export function configFlags(values, command) {
+    const flags = {};
+    if (typeof values['api-url'] === 'string')
+        flags.apiUrl = values['api-url'];
+    if (command === 'start' && typeof values.port === 'string')
+        flags.localServerPort = values.port;
+    if (command === 'start' && typeof values.mode === 'string')
+        flags.receiveMode = values.mode;
+    return flags;
+}
+function commandIndex(argv) {
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--')
+            return i + 1 < argv.length ? i + 1 : -1;
+        if (!arg.startsWith('-') || arg === '-')
+            return i;
+        const long = arg.startsWith('--') ? arg.slice(2) : undefined;
+        if (long !== undefined && !long.includes('=') && GLOBAL_OPTIONS[long]?.type === 'string')
+            i++;
+    }
+    return -1;
+}
+function findCommand(name) {
+    const cmd = commands.find((c) => c.name === name);
+    if (cmd)
+        return cmd;
+    const guess = suggest(name, commands.map((c) => c.name));
+    throw new UsageError(`unknown command "${name}".` +
+        (guess ? ` Did you mean "${guess}"?` : '') +
+        `\nRun '${BIN} --help' to see all commands.`);
+}
+function findSub(group, name) {
+    const subs = group.subcommands ?? [];
+    const short = (c) => c.name.slice(group.name.length + 1);
+    const sub = subs.find((c) => short(c) === name);
+    if (sub)
+        return sub;
+    const guess = suggest(name, subs.map(short));
+    throw new UsageError(`unknown command "${group.name} ${name}".` +
+        (guess ? ` Did you mean "${group.name} ${guess}"?` : '') +
+        `\nRun '${BIN} ${group.name} --help' to see its commands.`);
+}
+function parse(args, options, allowPositionals, command) {
+    const config = Object.fromEntries(Object.entries(options).map(([k, { description: _d, valueName: _v, negated: _n, ...spec }]) => [
+        k,
+        spec
+    ]));
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args,
+            options: config,
+            strict: true,
+            allowPositionals,
+            allowNegative: true,
+            tokens: true
+        });
+    }
+    catch (err) {
+        if (err instanceof TypeError &&
+            'code' in err &&
+            String(err.code).startsWith('ERR_PARSE_ARGS')) {
+            throw new UsageError(parseErrorMessage(err, String(err.code), options, command));
+        }
+        throw err;
+    }
+    for (const token of parsed.tokens) {
+        if (token.kind !== 'option' || !token.rawName.startsWith('--no-'))
+            continue;
+        const spec = options[token.name];
+        if (spec?.negated || token.name === 'color')
+            continue;
+        throw new UsageError(parseErrorMessage(new Error(`Unknown option '${token.rawName}'`), 'ERR_PARSE_ARGS_UNKNOWN_OPTION', options, command));
+    }
+    return { values: parsed.values, positionals: parsed.positionals };
+}
+function parseErrorMessage(err, code, options, command) {
+    const help = command ? `Run '${BIN} help ${command}' for its options.` : `Run '${BIN} --help'.`;
+    const quoted = /'([^']+)'/.exec(err.message)?.[1];
+    if (code === 'ERR_PARSE_ARGS_UNKNOWN_OPTION' && quoted) {
+        const names = Object.entries(options).flatMap(([name, spec]) => [
+            `--${name}`,
+            ...(spec.short ? [`-${spec.short}`] : []),
+            ...(spec.negated || name === 'color' ? [`--no-${name}`] : [])
+        ]);
+        const guess = suggest(quoted, names);
+        return `unknown option "${quoted}".${guess ? ` Did you mean "${guess}"?` : ''}\n${help}`;
+    }
+    const first = err.message.split(/\.\s/)[0].replace(/\.$/, '');
+    return `${first}.\n${help}`;
+}