@3minapi/cli 0.0.0-stage → 0.22.0

package/dist/commands/doctor.js

@@ -0,0 +1,326 @@
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { BIN, ConfigError, NewerSchemaError, DOCTOR_API_TIMEOUT_MS, ENV, ExitCode, MIN_NODE_VERSION, PROXY_ENV_VARS, isTrustedLiveUrl } from "../core/domain/index.js";
+import { ControlDb, LIVE_META } from "../core/control-db.js";
+import { resolveHostToken } from "../core/credentials.js";
+import { looseMode } from "../core/secure-fs.js";
+import { satisfiesMinNode } from "../core/version.js";
+import { initHint } from "../core/project.js";
+import { recordedLatest, updateCommand, updateInfo } from "../core/update-notice.js";
+import { readRunner } from "../core/host/runner-lock.js";
+export const doctor = {
+    name: 'doctor',
+    summary: 'Check Node.js, config, network and OS settings',
+    usage: '',
+    description: 'Does not send your token anywhere and does not count against your quota. The live check\n' +
+        'opens a WebSocket to the address the last start recorded, without the token.\n' +
+        'Exits with code 3 if any check fails.',
+    options: {},
+    args: { min: 0, max: 0 },
+    async run(ctx) {
+        const checks = [checkVersion(ctx), checkNode(), await checkSqlite()];
+        let config;
+        try {
+            config = ctx.loadConfig();
+            checks.push(...checkConfig(config, ctx.home));
+        }
+        catch (err) {
+            if (!(err instanceof ConfigError))
+                throw err;
+            checks.push({ name: 'config', status: 'fail', detail: err.message });
+        }
+        checks.push(checkDirs(ctx), checkToken(ctx), checkProxy(ctx.env));
+        if (config)
+            checks.push(await checkApi(config), await checkLive(ctx, config));
+        if (ctx.platform === 'win32')
+            checks.push(checkExecutionPolicy());
+        const failed = checks.some((c) => c.status === 'fail');
+        ctx.out.result({ ok: !failed, checks }, render(checks, ctx));
+        return failed ? ExitCode.Environment : ExitCode.Ok;
+    }
+};
+function checkVersion(ctx) {
+    const name = 'version';
+    let latest = null;
+    try {
+        const db = ControlDb.openReadOnly(ctx.dirs.data);
+        try {
+            latest = db ? recordedLatest(db) : null;
+        }
+        finally {
+            db?.close();
+        }
+    }
+    catch (err) {
+        if (err instanceof NewerSchemaError) {
+            return { name, status: 'warn', detail: err.message, fix: `Run: ${updateCommand()}` };
+        }
+        return {
+            name,
+            status: 'warn',
+            detail: `${BIN} ${ctx.version} — could not read the recorded latest version: ${err.message}`
+        };
+    }
+    let running;
+    try {
+        running = readRunner(ctx.dirs.data).state === 'running';
+    }
+    catch {
+        running = null;
+    }
+    const info = updateInfo(ctx.version, latest, running);
+    if (info.available) {
+        return {
+            name,
+            status: 'warn',
+            detail: `${BIN} ${info.current} (latest ${info.latest})`,
+            fix: `Run: ${info.command}${info.note ? ` — ${info.note}` : ''}`
+        };
+    }
+    return latest === null
+        ? {
+            name,
+            status: 'info',
+            detail: `${BIN} ${info.current} (latest unknown until the next server call)`
+        }
+        : { name: 'version', status: 'ok', detail: `${BIN} ${info.current} (latest)` };
+}
+function checkNode() {
+    const current = process.versions.node;
+    return satisfiesMinNode(current)
+        ? { name: 'node', status: 'ok', detail: `v${current}` }
+        : {
+            name: 'node',
+            status: 'fail',
+            detail: `v${current} (needs ${MIN_NODE_VERSION}+)`,
+            fix: 'Install the current Node.js 24 LTS from https://nodejs.org'
+        };
+}
+async function checkSqlite() {
+    try {
+        const { DatabaseSync } = await import('node:sqlite');
+        new DatabaseSync(':memory:').close();
+        return { name: 'sqlite', status: 'ok', detail: 'node:sqlite available' };
+    }
+    catch (err) {
+        return {
+            name: 'sqlite',
+            status: 'fail',
+            detail: `node:sqlite unavailable: ${err.message}`,
+            fix: `Use the official Node.js ${MIN_NODE_VERSION}+ build`
+        };
+    }
+}
+function checkConfig(config, home) {
+    const checks = [
+        {
+            name: 'config',
+            status: 'ok',
+            detail: config.projectFile
+                ? `project ${config.projectFile}`
+                : `this host has no project. ${initHint(home)}`
+        },
+        {
+            name: 'api url',
+            status: 'info',
+            detail: `${config.values.apiUrl} (from ${config.sources.apiUrl})`
+        }
+    ];
+    for (const warning of config.warnings)
+        checks.push({ name: 'config', status: 'warn', detail: warning });
+    return checks;
+}
+function checkDirs({ dirs, env }) {
+    const home = env[ENV.home];
+    const moved = home && path.isAbsolute(home)
+        ? ` (${ENV.home} is set — not this PC's default host folder; for development and tests)`
+        : '';
+    return {
+        name: 'folders',
+        status: 'info',
+        detail: `config ${dirs.config} · data ${dirs.data} · logs ${dirs.logs}${moved}`
+    };
+}
+function checkToken({ dirs, env }) {
+    let token;
+    try {
+        token = resolveHostToken(dirs.config, env);
+    }
+    catch (err) {
+        return { name: 'token', status: 'fail', detail: err.message };
+    }
+    if (!token) {
+        return { name: 'token', status: 'info', detail: "not logged in (run '3minapi login')" };
+    }
+    if (token.source === 'env')
+        return {
+            name: 'token',
+            status: 'ok',
+            detail: `from ${token.location} — not the token saved by '3minapi login' (for development, CI and tests)`
+        };
+    const mode = looseMode(token.location);
+    return mode === null
+        ? { name: 'token', status: 'ok', detail: `saved in ${token.location}` }
+        : {
+            name: 'token',
+            status: 'warn',
+            detail: `${token.location} is readable by other users (mode ${mode.toString(8)})`,
+            fix: `Run: chmod 600 "${token.location}"`
+        };
+}
+function checkProxy(env) {
+    const name = PROXY_ENV_VARS.find((v) => env[v]);
+    if (!name)
+        return { name: 'proxy', status: 'ok', detail: 'no proxy configured' };
+    const shown = `${name}=${redactUrl(env[name])}`;
+    const enabled = env.NODE_USE_ENV_PROXY === '1' || process.execArgv.includes('--use-env-proxy');
+    return enabled
+        ? { name: 'proxy', status: 'ok', detail: `${shown} (NODE_USE_ENV_PROXY=1)` }
+        : {
+            name: 'proxy',
+            status: 'warn',
+            detail: `${shown} is set, but Node.js ignores it`,
+            fix: 'Set NODE_USE_ENV_PROXY=1 so connections go through the proxy'
+        };
+}
+function redactUrl(value) {
+    try {
+        const u = new URL(value);
+        if (u.username || u.password) {
+            u.username = '***';
+            u.password = '';
+        }
+        return u.toString();
+    }
+    catch {
+        return '(unparseable)';
+    }
+}
+async function checkApi(config) {
+    const url = config.values.apiUrl;
+    try {
+        const res = await fetch(url, {
+            redirect: 'manual',
+            signal: AbortSignal.timeout(DOCTOR_API_TIMEOUT_MS)
+        });
+        await res.body?.cancel();
+        return { name: 'api', status: 'ok', detail: `${url} reachable (HTTP ${res.status})` };
+    }
+    catch (err) {
+        const e = err;
+        const reason = e.name === 'TimeoutError'
+            ? `no response within ${DOCTOR_API_TIMEOUT_MS / 1000}s`
+            : (e.cause?.code ?? e.cause?.message ?? e.message);
+        return {
+            name: 'api',
+            status: 'fail',
+            detail: `${url} unreachable: ${reason}`,
+            fix: 'Check your network, firewall or proxy settings'
+        };
+    }
+}
+async function checkLive(ctx, config) {
+    const name = 'live';
+    let url = null;
+    try {
+        const db = ControlDb.openReadOnly(ctx.dirs.data);
+        try {
+            url = db?.getMeta(LIVE_META.url) ?? null;
+        }
+        finally {
+            db?.close();
+        }
+    }
+    catch (err) {
+        return {
+            name,
+            status: 'warn',
+            detail: `could not read the recorded live address: ${err.message}`,
+            fix: "Run '3minapi doctor' again after 'start' stops, or check the permissions of the data folder ('3minapi paths')"
+        };
+    }
+    if (url === null) {
+        return {
+            name,
+            status: 'info',
+            detail: `not checked yet — '3minapi start' records the address`
+        };
+    }
+    if (!isTrustedLiveUrl(url, config.values.apiUrl)) {
+        return {
+            name,
+            status: 'info',
+            detail: `not checked — the recorded address is for another API URL`
+        };
+    }
+    const opened = await new Promise((resolve) => {
+        let ws;
+        try {
+            ws = new WebSocket(url);
+        }
+        catch {
+            resolve(false);
+            return;
+        }
+        const timer = setTimeout(() => {
+            done(false);
+        }, DOCTOR_API_TIMEOUT_MS);
+        const done = (ok) => {
+            clearTimeout(timer);
+            try {
+                ws.close();
+            }
+            catch {
+            }
+            resolve(ok);
+        };
+        ws.addEventListener('open', () => done(true), { once: true });
+        ws.addEventListener('close', () => done(false), { once: true });
+    });
+    if (opened)
+        return { name, status: 'ok', detail: `${url} reachable (WebSocket)` };
+    const proxy = PROXY_ENV_VARS.find((v) => ctx.env[v]);
+    return {
+        name,
+        status: 'warn',
+        detail: `could not open a WebSocket to ${url} — a proxy, firewall or the network may block it` +
+            (proxy ? ` (proxy ${proxy} is set)` : ''),
+        fix: "Run '3minapi start --mode poll' to fetch tasks at an interval instead"
+    };
+}
+function checkExecutionPolicy() {
+    const { PSModulePath: _inherited, ...env } = process.env;
+    const r = spawnSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', 'Get-ExecutionPolicy'], { encoding: 'utf8', timeout: 10_000, windowsHide: true, env });
+    const policy = r.stdout?.trim();
+    if (r.status !== 0 || !policy) {
+        const reason = (r.error?.message ?? r.stderr?.trim().split(/\r?\n/)[0]) || `exit ${r.status}`;
+        return {
+            name: 'powershell',
+            status: 'info',
+            detail: `could not read the execution policy (${reason})`
+        };
+    }
+    if (policy === 'Restricted' || policy === 'AllSigned') {
+        return {
+            name: 'powershell',
+            status: 'warn',
+            detail: `execution policy is ${policy}: '3minapi' will not start from PowerShell`,
+            fix: "Run 'Set-ExecutionPolicy -Scope CurrentUser RemoteSigned', or use '3minapi.cmd'"
+        };
+    }
+    return { name: 'powershell', status: 'ok', detail: `execution policy ${policy}` };
+}
+function render(checks, { out }) {
+    const label = {
+        ok: out.out.green('ok  '),
+        warn: out.out.yellow('warn'),
+        fail: out.out.red('FAIL'),
+        info: out.out.dim('info')
+    };
+    const width = Math.max(...checks.map((c) => c.name.length)) + 2;
+    const lines = checks.flatMap((c) => {
+        const line = `${label[c.status]}  ${c.name.padEnd(width)}${c.detail}`;
+        return c.fix ? [line, `      ${' '.repeat(width)}${out.out.dim('-> ' + c.fix)}`] : [line];
+    });
+    return lines.join('\n');
+}

package/dist/commands/guide.js

@@ -0,0 +1,84 @@
+import { AGENTS_FILE, BIN, CLAUDE_FILE, CONTROL_DB_FILE, CREDENTIALS_FILE, DEFAULT_WORKERS_DIR, ExitCode, LOCAL_SERVER_TOKEN_FILE, PROJECT_CONFIG_FILE, PROJECT_RECORD_FILE, RESULT_TABLE_PREFIX, USER_DB_FILE } from "../core/domain/index.js";
+import { DOTENV_FILE } from "../modules/workers/runtime/env.js";
+import { HANDLER_DOC, SETTINGS } from "../modules/workers/template.js";
+export const GENERATED_MARKER = `<!-- generated by ${BIN}`;
+export function agentGuide(version) {
+    return `# ${BIN} project — guide for AI agents
+
+This folder is a ${BIN} project. The user's machine runs as a 3Min API host: an AI creates tasks, and
+\`${BIN} start\` fetches them and runs them with the worker files here. You help the user write, test and run
+those workers. Every command below works from any folder and takes \`--json\` for machine-readable output.
+
+## Edit
+
+- **Worker files** — \`${DEFAULT_WORKERS_DIR}/<name>.mjs\` (or \`.mts\`, \`.js\`, \`.ts\`); one file is one worker.
+  Start one with \`${BIN} worker new <name>\` (\`--ts\` for TypeScript) instead of writing it from scratch.
+  \`${BIN} paths\` shows the workers folder if \`${PROJECT_CONFIG_FILE}\` moved it.
+- **\`${DOTENV_FILE}\`** — secrets the workers read through \`ctx.env\`. Write the values the user gives you, but never
+  print them back, log them or put them in a result.
+- **\`${PROJECT_CONFIG_FILE}\`** — project settings. \`receiveMode\` is \`live\` (default) or \`poll\`; in poll mode
+  \`pollIntervalMs\` sets how often \`start\` fetches, and every fetch is an API call counted against the quota.
+- **\`package.json\`** — only when a worker needs a library. \`npm init -y\` writes \`"type": "commonjs"\`, which
+  breaks \`.js\`/\`.ts\` workers that use \`export\`: keep workers as \`.mjs\`/\`.mts\`, or set \`"type": "module"\`.
+
+## Run
+
+| Command | Use |
+|---|---|
+| \`${BIN} worker run <name> --input '<json>'\` | Test a worker on this machine — no task, no API call (\`--input-file\` avoids shell quoting) |
+| \`${BIN} worker list\` | Check that every worker file loads |
+| \`${BIN} reload\` | After adding or renaming a worker, or changing a \`description\` — until then the AI sees the old one |
+| \`${BIN} status\` | Whether \`start\` is running, its workers, the quota left |
+| \`${BIN} logs\` / \`${BIN} worker logs <name>\` | The CLI's log / one worker's log |
+| \`${BIN} worker results list\` / \`show <task_id>\` / \`query "<SQL>"\` | Results saved in \`${USER_DB_FILE}\` |
+| \`${BIN} start --detach\` / \`${BIN} stop\` | Run the host in the background / stop it |
+| \`${BIN} doctor\` | Check Node.js, config, network and proxy settings |
+| \`${BIN} paths\` | Absolute paths of the files on this page |
+
+Handler code and \`${DOTENV_FILE}\` edits apply to the next task with no reload. Ask the user before
+\`${BIN} worker delete <name> --yes\` (it also deletes the worker and its task history on 3Min API) and before any
+\`prune --yes\`.
+
+## Do not touch
+
+- **\`${CREDENTIALS_FILE}\`** (the host token) — never read, print or copy it. The user runs \`${BIN} login\` and types
+  the token at its masked prompt; never ask for the token in the chat.
+- **\`${CONTROL_DB_FILE}\`, \`runner.*\`, \`${PROJECT_RECORD_FILE}\`** — internal state. Use \`${BIN} tasks prune\` to clear history.
+- **\`${LOCAL_SERVER_TOKEN_FILE}\`** — only for a local script that calls \`${BIN} start --serve\`.
+- **Tables starting with \`${RESULT_TABLE_PREFIX}\` in \`${USER_DB_FILE}\`** — read them, never write them.
+
+## Worker file
+
+\`\`\`js
+${SETTINGS}
+
+${HANDLER_DOC}
+export async function handler(input, ctx) {
+	// ...
+	return { ok: true };
+}
+\`\`\`
+
+This text matches ${BIN} v${version}. Run \`${BIN} guide\` for the version installed now.
+`;
+}
+export function agentsFileText(version) {
+    return (`${GENERATED_MARKER} v${version}. '${BIN} init' replaces this file while this line is here — ` +
+        `delete the line to keep your own edits. -->\n\n${agentGuide(version)}`);
+}
+export const CLAUDE_FILE_TEXT = `@${AGENTS_FILE}\n`;
+export const guide = {
+    name: 'guide',
+    summary: 'Print the guide for AI agents working in this project (also written to AGENTS.md by init)',
+    usage: '',
+    description: 'Which files an AI agent edits, which commands it runs, which files it never touches, and how a\n' +
+        `worker file is shaped. '${BIN} init' writes the same text to ${AGENTS_FILE}, plus a ${CLAUDE_FILE} that\n` +
+        'imports it for Claude Code. No API call; works without a project.',
+    options: {},
+    args: { min: 0, max: 0 },
+    async run(ctx) {
+        const text = agentGuide(ctx.version);
+        ctx.out.result({ version: ctx.version, guide: text }, text.trimEnd());
+        return ExitCode.Ok;
+    }
+};

package/dist/commands/index.js

@@ -0,0 +1,28 @@
+import { login, logout, status } from "./auth.js";
+import { dashboard } from "./dashboard.js";
+import { doctor } from "./doctor.js";
+import { guide } from "./guide.js";
+import { init } from "./init.js";
+import { logs } from "./logs.js";
+import { paths } from "./paths.js";
+import { reload } from "./reload.js";
+import { start } from "./start.js";
+import { stop } from "./stop.js";
+import { tasks } from "./tasks.js";
+import { worker } from "./worker.js";
+export const commands = [
+    login,
+    init,
+    worker,
+    start,
+    reload,
+    stop,
+    status,
+    logs,
+    dashboard,
+    tasks,
+    paths,
+    guide,
+    logout,
+    doctor
+];

package/dist/commands/init.js

@@ -0,0 +1,248 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { AGENTS_FILE, BIN, CLAUDE_FILE, CliError, ConfigError, DEFAULT_WORKERS_DIR, ExitCode, GITIGNORE_ENTRIES, PROJECT_CONFIG_FILE, USER_DB_FILE, UsageError } from "../core/domain/index.js";
+import { readRunner } from "../core/host/runner-lock.js";
+import { findProjectFile } from "../core/config.js";
+import { confirm } from "../core/prompt.js";
+import { readUserText } from "../core/text-file.js";
+import { shellArg } from "../core/text.js";
+import { defaultProjectRoot, projectAlive, readProjectRecord, samePath, writeProjectRecord } from "../core/project.js";
+import { ResultStore } from "../modules/workers/results/store.js";
+import { DOTENV_FILE } from "../modules/workers/runtime/env.js";
+import { agentsFileText, CLAUDE_FILE_TEXT, GENERATED_MARKER } from "./guide.js";
+export const init = {
+    name: 'init',
+    summary: `Create the host's project (default ~/3minapi): ${PROJECT_CONFIG_FILE}, a workers/ folder, ${USER_DB_FILE} and ${AGENTS_FILE}`,
+    usage: '[folder] [--move] [--yes]',
+    description: 'A host has one project. Other commands use it from any folder — no need to cd into it.\n' +
+        '  3minapi init           ~/3minapi (Windows: %USERPROFILE%\\3minapi). Asks first; without a terminal pass --yes\n' +
+        '  3minapi init <folder>  that folder, created if missing\n' +
+        '  3minapi init .         the current folder\n' +
+        'Inside the project (or once the host has one) plain init repairs it. Making your home folder or /\n' +
+        'the project asks first.\n' +
+        'Safe to run again: existing files are left untouched and only missing parts are added.\n' +
+        `${AGENTS_FILE} tells AI coding agents how to work here (the '${BIN} guide' text); ${CLAUDE_FILE} imports it\n` +
+        `for Claude Code. init refreshes ${AGENTS_FILE} to this version while its first line is the generated marker.\n` +
+        'AI agents and scripts: name the folder or pass --yes, and read the absolute paths from --json (root).\n' +
+        '\n' +
+        'Moving the project:\n' +
+        "  with its files     '3minapi stop', move the folder, then run any command inside it ('3minapi status')\n" +
+        '                     — the new place is picked up automatically\n' +
+        "  to another folder  '3minapi init <folder> --move' — nothing is copied: the old folder keeps its\n" +
+        '                     data.db, workers and .env\n' +
+        '\n' +
+        `${USER_DB_FILE} is a SQLite file. 'start' saves every task result in it (tables starting with\n` +
+        "_3minapi_), and your workers can keep their own data there — see the note in 'worker new' files.\n" +
+        'Saved results may contain personal data; nothing deletes them automatically.',
+    options: {
+        move: {
+            type: 'boolean',
+            description: "Make the folder the host's project instead of the current one"
+        },
+        yes: {
+            type: 'boolean',
+            description: 'Create the project without asking (~/3minapi, your home folder or /)'
+        }
+    },
+    args: { min: 0, max: 1 },
+    async run(ctx) {
+        const { out, dirs, platform, values, now } = ctx;
+        const record = readProjectRecord(dirs.data);
+        const recordAlive = record !== null && projectAlive(record.root);
+        const target = initTarget(ctx, recordAlive ? record.root : null);
+        const root = target.root;
+        const stat = statSync(root, { throwIfNoEntry: false });
+        if (stat && !stat.isDirectory()) {
+            throw new ConfigError(`${root} is a file, not a folder. Run '${BIN} init <folder>'.`);
+        }
+        const isProject = projectAlive(root);
+        if (target.kind === 'default' && stat && !isProject && hasUserFiles(root)) {
+            throw new ConfigError(`${root} already exists and is not a 3minapi project. ` +
+                `Run '${BIN} init <folder>' to use another folder, or '${BIN} init ${shellArg(root)}' to use it anyway.`);
+        }
+        const other = recordAlive && !samePath(record.root, root, platform) ? record.root : null;
+        if (other !== null && !values.move) {
+            throw new ConfigError(`this host's project is ${other} — a host has one project.\n` +
+                `To make ${root} the project instead, run '${BIN} init ${shellArg(root)} --move' ` +
+                `(nothing is copied: ${other} keeps its ${USER_DB_FILE}, workers and .env).`);
+        }
+        if (other !== null && readRunner(dirs.data).state !== 'stopped') {
+            throw new CliError(`'${BIN} start' is running with the project ${other}. Run '${BIN} stop' first, then '${BIN} init ${shellArg(root)} --move'.`);
+        }
+        if (target.kind === 'default' && record !== null && !recordAlive && !isProject) {
+            out.warn(`this host's project ${record.root} no longer exists. If you moved it, run '${BIN} status' ` +
+                'inside the new folder instead of creating a new project.');
+        }
+        if (!isProject && needsConfirm(ctx, target.kind, root)) {
+            await agree(ctx, target.kind, root);
+        }
+        if (!stat)
+            mkdirSync(root, { recursive: true });
+        const created = stat ? [] : [root + path.sep];
+        const kept = [];
+        const configFile = path.join(root, PROJECT_CONFIG_FILE);
+        let workersDir = DEFAULT_WORKERS_DIR;
+        if (existsSync(configFile)) {
+            kept.push(configFile);
+            try {
+                const dir = JSON.parse(readUserText(configFile)).workersDir;
+                if (typeof dir === 'string' && dir.trim() !== '' && !path.isAbsolute(dir))
+                    workersDir = dir;
+            }
+            catch (err) {
+                out.warn(err instanceof ConfigError
+                    ? err.message
+                    : `${PROJECT_CONFIG_FILE} is not valid JSON — run '3minapi doctor'`);
+            }
+        }
+        else {
+            writeFileSync(configFile, JSON.stringify({ workersDir }, null, '\t') + '\n', { flag: 'wx' });
+            created.push(configFile);
+        }
+        const workersPath = path.resolve(root, workersDir);
+        if (existsSync(workersPath)) {
+            kept.push(workersPath + path.sep);
+        }
+        else {
+            mkdirSync(workersPath, { recursive: true });
+            created.push(workersPath + path.sep);
+        }
+        const db = path.join(root, USER_DB_FILE);
+        let dbCreated = false;
+        if (existsSync(db)) {
+            kept.push(db);
+        }
+        else {
+            ResultStore.open(root).store.close();
+            created.push(db);
+            dbCreated = true;
+        }
+        const gitignore = path.join(root, '.gitignore');
+        const current = existsSync(gitignore) ? readFileSync(gitignore, 'utf8') : null;
+        const lines = new Set((current ?? '').split(/\r?\n/).map((l) => l.trim()));
+        const missing = GITIGNORE_ENTRIES.filter((entry) => !lines.has(entry));
+        if (missing.length === 0) {
+            kept.push(gitignore);
+        }
+        else {
+            const prefix = current === null || current === '' || current.endsWith('\n') ? '' : '\n';
+            writeFileSync(gitignore, `${current ?? ''}${prefix}${missing.join('\n')}\n`);
+            created.push(current === null ? gitignore : `${gitignore} (added ${missing.join(', ')})`);
+        }
+        const agents = writeAgentFiles(root, ctx.version);
+        created.push(...agents.created);
+        kept.push(...agents.kept);
+        const recorded = record === null || !samePath(record.root, root, platform);
+        if (recorded)
+            writeProjectRecord(dirs.data, root, now());
+        const env = path.join(root, DOTENV_FILE);
+        const output = [
+            ...(other !== null
+                ? [
+                    `${out.out.green('moved')}    this host's project is now ${root}`,
+                    out.out.dim(`         ${other} was left as is — its ${USER_DB_FILE} (saved results), workers and .env were not moved.`)
+                ]
+                : []),
+            ...created.map((f) => `${out.out.green('created')}  ${f}`),
+            ...agents.updated.map((f) => `${out.out.green('updated')}  ${f}`),
+            ...kept.map((f) => `${out.out.dim('exists')}   ${f}`),
+            `${out.out.dim('env')}      ${env}${existsSync(env) ? '' : out.out.dim(' (create it when a worker needs secrets)')}`
+        ];
+        if (agents.claudeWithoutImport) {
+            output.push('', `${CLAUDE_FILE} exists without '@${AGENTS_FILE}' — Claude Code reads ${AGENTS_FILE} only through it. Add that line to use the guide.`);
+        }
+        if (dbCreated) {
+            output.push('', `${USER_DB_FILE} keeps every task result this machine runs — they may contain personal data and`, `are never deleted automatically ('${BIN} worker results prune'). It is in .gitignore.`);
+        }
+        if (created.includes(configFile) || created.includes(workersPath + path.sep)) {
+            output.push('', `Next: ${BIN} worker new <name>   ${out.out.dim('(works from any folder)')}`, `      edit workers in ${workersPath}`);
+        }
+        out.result({
+            root,
+            workersDir: workersPath,
+            configFile,
+            env,
+            db,
+            agentsFile: path.join(root, AGENTS_FILE),
+            created,
+            updated: agents.updated,
+            kept,
+            moved: other !== null,
+            previousRoot: other
+        }, output.join('\n'));
+        return ExitCode.Ok;
+    }
+};
+const OS_METADATA_FILES = new Set(['.DS_Store', 'Thumbs.db', 'desktop.ini']);
+function hasUserFiles(dir) {
+    return readdirSync(dir).some((name) => !OS_METADATA_FILES.has(name));
+}
+function initTarget(ctx, recorded) {
+    const arg = ctx.positionals[0];
+    if (arg !== undefined)
+        return { root: path.resolve(ctx.cwd, arg), kind: 'explicit' };
+    const found = findProjectFile(ctx.cwd);
+    if (found)
+        return { root: path.dirname(found), kind: 'existing' };
+    if (recorded !== null && !ctx.values.move)
+        return { root: recorded, kind: 'existing' };
+    return { root: defaultProjectRoot(ctx.home), kind: 'default' };
+}
+function needsConfirm(ctx, kind, root) {
+    if (kind === 'default')
+        return true;
+    return samePath(root, ctx.home, ctx.platform) || path.parse(root).root === root;
+}
+async function agree(ctx, kind, root) {
+    const { out } = ctx;
+    if (ctx.values.yes)
+        return;
+    const rerun = kind === 'default' ? `${BIN} init --yes` : `${BIN} init ${shellArg(root)} --yes`;
+    if (out.json || !ctx.stdin.isTTY) {
+        throw new UsageError(`init creates the project in ${root} and needs agreement. Nothing was created. ` +
+            `Once the user has agreed, run: ${rerun} — or name another folder: ${BIN} init <folder>`);
+    }
+    const where = kind === 'default'
+        ? root
+        : `${root} (${path.parse(root).root === root ? 'the filesystem root' : 'your home folder'})`;
+    const yes = await confirm(ctx.stdin, out, `Create the 3minapi project in ${where}? It adds ${PROJECT_CONFIG_FILE}, workers/, ${USER_DB_FILE}, .gitignore, ${AGENTS_FILE} and ${CLAUDE_FILE}.`);
+    if (!yes) {
+        throw new CliError(`cancelled — nothing was created. To use another folder: ${BIN} init <folder>`);
+    }
+}
+function writeAgentFiles(root, version) {
+    const result = {
+        created: [],
+        updated: [],
+        kept: [],
+        claudeWithoutImport: false
+    };
+    const agents = path.join(root, AGENTS_FILE);
+    const text = agentsFileText(version);
+    const current = existsSync(agents)
+        ? readFileSync(agents, 'utf8')
+            .replace(/^\uFEFF/, '')
+            .replace(/\r\n/g, '\n')
+        : null;
+    if (current === null) {
+        writeFileSync(agents, text, { flag: 'wx' });
+        result.created.push(agents);
+    }
+    else if (current.startsWith(GENERATED_MARKER) && current !== text) {
+        writeFileSync(agents, text);
+        result.updated.push(agents);
+    }
+    else {
+        result.kept.push(agents);
+    }
+    const claude = path.join(root, CLAUDE_FILE);
+    if (!existsSync(claude)) {
+        writeFileSync(claude, CLAUDE_FILE_TEXT, { flag: 'wx' });
+        result.created.push(claude);
+    }
+    else {
+        result.kept.push(claude);
+        result.claudeWithoutImport = !/^\s*@AGENTS\.md\s*$/m.test(readFileSync(claude, 'utf8'));
+    }
+    return result;
+}