min-agent 0.3.0 → 0.4.0

package/dist/cli/commands/serve.js

@@ -0,0 +1,9 @@
+import { isConfigured } from "../../config.js";
+import { CliError } from "../errors.js";
+export async function runServeCommand(opts) {
+    if (!isConfigured()) {
+        throw new CliError("Not configured.", { hint: "Run: min-agent setup" });
+    }
+    const { runServe } = await import("../../serve.js");
+    await runServe({ port: opts.port, host: opts.host });
+}

package/dist/cli/commands/setup.js

@@ -0,0 +1,4 @@
+import { runSetup } from "../../config.js";
+export async function runSetupCommand() {
+    await runSetup();
+}

package/dist/cli/commands/shared.js

@@ -0,0 +1,16 @@
+import { isConfigured } from "../../config.js";
+import { CliError } from "../errors.js";
+export async function startTuiSession(input) {
+    if (!isConfigured()) {
+        throw new CliError("Not configured.", { hint: "Run: min-agent setup" });
+    }
+    const { runTui } = await import("../../tui-chat.js");
+    const prompt = input.positionals.join(" ").trim();
+    await runTui({
+        modelId: input.model,
+        providerName: input.provider,
+        resumeSessionId: input.resume,
+        images: input.images,
+        initialPrompt: prompt || undefined,
+    });
+}

package/dist/cli/commands/skills.js

@@ -0,0 +1,119 @@
+import { discoverSkills } from "../../skills.js";
+import { existsSync, writeFileSync, mkdirSync } from "fs";
+import path from "path";
+import os from "os";
+import { CliError } from "../errors.js";
+/** One-line, length-capped text for list output. */
+function truncate(text, max) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length <= max ? flat : `${flat.slice(0, max - 1)}…`;
+}
+export async function runSkillsList(json) {
+    discoverSkills({ silent: true });
+    const { getAllSkills, getStaleDisabledSkills } = await import("../../skills.js");
+    const all = getAllSkills().sort((a, b) => a.name.localeCompare(b.name));
+    const stale = getStaleDisabledSkills();
+    if (json) {
+        console.log(JSON.stringify({
+            count: all.length,
+            enabled_count: all.filter((s) => s.enabled).length,
+            stale_disabled: stale,
+            skills: all.map((s) => ({
+                name: s.name,
+                description: s.description,
+                location: s.location,
+                enabled: s.enabled,
+                ...(s.disabledScope ? { disabled_scope: s.disabledScope } : {}),
+                ...(s.version ? { version: s.version } : {}),
+                ...(s.allowedTools.length ? { allowed_tools: s.allowedTools } : {}),
+                ...(s.requiredBins.length ? { requires_bins: s.requiredBins } : {}),
+                ...(s.builtin ? { builtin: true } : {}),
+                ...(s.alwaysLoad ? { always_load: true } : {}),
+            })),
+        }, null, 2));
+        return;
+    }
+    if (all.length === 0 && stale.length === 0) {
+        console.log("No skills found. Add SKILL.md files in .min-agent/skills/<name>/");
+        return;
+    }
+    console.log(`Skills (${all.filter((s) => s.enabled).length} enabled, ${all.filter((s) => !s.enabled).length} disabled):`);
+    for (const skill of all) {
+        const status = skill.enabled
+            ? "\x1b[32menabled \x1b[0m"
+            : `\x1b[90mdisabled(${skill.disabledScope === "project" ? "proj" : "glob"})\x1b[0m`;
+        const origin = skill.builtin ? "  \x1b[90mbuiltin\x1b[0m" : "";
+        console.log(`  ${skill.name}  ${status}${origin}  \x1b[90m${truncate(skill.description, 60)}\x1b[0m`);
+        console.log(`    \x1b[90m${skill.location}\x1b[0m`);
+    }
+    if (stale.length > 0) {
+        console.log(`\n\x1b[33m⚠ disabledSkills/enabledSkills entries matching no skill: ${stale.join(", ")}\x1b[0m`);
+        console.log(`\x1b[33m  Remove them with: min-agent skills enable ${stale.join(" ")} (add --project if the entry is project-scoped)\x1b[0m`);
+    }
+    console.log("\nUse: min-agent skills info <name>  for details");
+}
+export async function runSkillsInfo(name, json) {
+    discoverSkills({ silent: true });
+    const { getSkill, getAllSkills } = await import("../../skills.js");
+    const skill = getSkill(name);
+    if (!skill) {
+        const names = getAllSkills().map((s) => s.name);
+        throw new CliError(`Skill "${name}" not found.${names.length ? ` Available: ${names.join(", ")}` : " No skills discovered."}`);
+    }
+    if (json) {
+        console.log(JSON.stringify(skill, null, 2));
+        return;
+    }
+    console.log(`Name:        ${skill.name}`);
+    console.log(`Status:      ${skill.enabled ? "enabled" : `disabled (${skill.disabledScope} scope)`}`);
+    if (skill.builtin)
+        console.log("Source:      builtin");
+    if (skill.version)
+        console.log(`Version:     ${skill.version}`);
+    console.log(`Description: ${skill.description}`);
+    console.log(`Location:    ${skill.location}`);
+    if (skill.allowedTools.length > 0)
+        console.log(`Tools:       ${skill.allowedTools.join(", ")}`);
+    if (skill.requiredBins.length > 0)
+        console.log(`Requires:    ${skill.requiredBins.join(", ")}`);
+    if (skill.content.trim()) {
+        console.log("\n--- Content ---\n");
+        console.log(skill.content.trim());
+    }
+}
+export async function runSkillsToggle(names, enabled, scope) {
+    const verb = enabled ? "enable" : "disable";
+    if (names.length === 0)
+        throw new CliError(`Usage: min-agent skills ${verb} <name...> [--project]`);
+    discoverSkills({ silent: true });
+    const { getAllSkills, setSkillEnabled, getStaleDisabledSkills } = await import("../../skills.js");
+    const known = new Set(getAllSkills().map((s) => s.name));
+    const stale = new Set(getStaleDisabledSkills());
+    // `enable` must accept stale names so they can be cleaned up from config;
+    // `disable` on an unknown name is always an error.
+    const unknown = names.filter((n) => !known.has(n) && !(enabled && stale.has(n)));
+    if (unknown.length > 0) {
+        throw new CliError(`Skill${unknown.length > 1 ? "s" : ""} not found: ${unknown.join(", ")}`, {
+            hint: known.size ? `Available: ${[...known].join(", ")}` : "No skills discovered.",
+        });
+    }
+    for (const result of setSkillEnabled(names, enabled, scope)) {
+        console.log(`✓ Skill "${result.name}" ${verb}d (${scope} scope)`);
+        if (result.blockedBy) {
+            console.log(`\x1b[33m  ⚠ still ${result.enabled ? "enabled" : "disabled"} — overridden by ${result.blockedBy} scope\x1b[0m`);
+        }
+    }
+}
+export async function runSkillsNew(name, global) {
+    if (!/^[\w-]+$/.test(name)) {
+        throw new CliError("Invalid skill name", { hint: "use letters, digits, _ or -" });
+    }
+    const root = global ? path.join(os.homedir(), ".agents", "skills") : path.join(process.cwd(), ".min-agent", "skills");
+    const dir = path.join(root, name);
+    if (existsSync(path.join(dir, "SKILL.md"))) {
+        throw new CliError(`Skill "${name}" already exists at ${dir}`);
+    }
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path.join(dir, "SKILL.md"), `---\nname: ${name}\ndescription: What this skill does\n# version: 1.0.0\n# allowed-tools: [read, grep]\n# metadata:\n#   requires:\n#     bins: ["some-cli"]\n---\n\n# ${name}\n\nWrite the skill instructions here.\n`, "utf-8");
+    console.log(`✓ Created skill "${name}" at ${path.join(dir, "SKILL.md")}`);
+}

package/dist/cli/commands/update.js

@@ -0,0 +1,7 @@
+import { runUpdate } from "../../updater.js";
+export async function runUpdateCommand() {
+    const result = await runUpdate();
+    if (result.status === "check-failed" || result.status === "install-failed") {
+        process.exitCode = 1;
+    }
+}

package/dist/cli/commands/write-config.js

@@ -0,0 +1,30 @@
+import { runSandboxCli } from "../../sandbox-cli.js";
+import { runPermissionCli } from "../../permission-cli.js";
+export async function runWriteConfig(input) {
+    const lines = [];
+    let ok = true;
+    if (input.sandbox !== undefined || input.network !== undefined) {
+        const result = runSandboxCli({
+            positionals: [],
+            flagMode: input.sandbox,
+            flagNetwork: input.network,
+            scope: input.scope,
+        });
+        lines.push(...result.lines);
+        if (!result.ok)
+            ok = false;
+    }
+    if (input.permission !== undefined) {
+        const result = runPermissionCli({
+            positionals: [],
+            flagMode: input.permission,
+            scope: input.scope,
+        });
+        lines.push(...result.lines);
+        if (!result.ok)
+            ok = false;
+    }
+    console.log(lines.join("\n"));
+    if (!ok)
+        process.exitCode = 1;
+}

package/dist/cli/errors.js

@@ -0,0 +1,36 @@
+/**
+ * Unified CLI error contract.
+ *
+ * Exit code convention:
+ *   1 - user error (bad arguments, missing input, not found, validation failure)
+ *   2 - runtime error (network failure, subprocess failure, unexpected exception)
+ */
+export class CliError extends Error {
+    exitCode;
+    hint;
+    constructor(message, options) {
+        super(message);
+        this.name = "CliError";
+        this.exitCode = options?.exitCode ?? 1;
+        this.hint = options?.hint;
+    }
+}
+export function userError(message, hint) {
+    return new CliError(message, { exitCode: 1, hint });
+}
+export function runtimeError(message, hint) {
+    return new CliError(message, { exitCode: 2, hint });
+}
+/** Render a CliError (or any error) as the standard `✖ message` block on stderr. */
+export function formatCliError(err) {
+    if (err instanceof CliError) {
+        return err.hint ? `✖ ${err.message}\n  → ${err.hint}` : `✖ ${err.message}`;
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return `✖ ${message}`;
+}
+export function exitCodeFor(err) {
+    if (err instanceof CliError)
+        return err.exitCode;
+    return 2;
+}

package/dist/cli/exec-prompt.js

@@ -0,0 +1,26 @@
+/**
+ * Resolve the final prompt text for `min-agent exec`, combining positional
+ * arguments with piped stdin according to these rules:
+ *  - `exec -`            reads the entire prompt from stdin.
+ *  - `exec` (no args)    requires piped stdin (non-TTY); errors otherwise.
+ *  - `exec <msg>` + pipe appends piped stdin after the message.
+ *  - `exec <msg>`        uses the message as-is.
+ */
+export function resolveExecPrompt(positionals, stdinText, stdinIsTty) {
+    const joined = positionals.join(" ");
+    const piped = stdinText.length > 0;
+    if (joined === "-") {
+        const prompt = stdinText;
+        if (!prompt.trim())
+            return { ok: false, error: "Usage: min-agent exec <message>" };
+        return { ok: true, prompt };
+    }
+    if (!joined) {
+        if (stdinIsTty || !piped)
+            return { ok: false, error: "Usage: min-agent exec <message>" };
+        return { ok: true, prompt: stdinText };
+    }
+    if (piped && !stdinIsTty)
+        return { ok: true, prompt: `${joined}\n\n${stdinText}` };
+    return { ok: true, prompt: joined };
+}

package/dist/cli/option-helpers.js

@@ -0,0 +1,53 @@
+import { Option } from "commander";
+import { parseNetworkPolicy, parseSandboxMode } from "../sandbox.js";
+import { parsePermissionMode } from "../config.js";
+import { userError } from "./errors.js";
+/** Reusable --project / --global mutually exclusive scope selector. */
+export function scopeOptions() {
+    return [
+        new Option("--project", "Apply to this project only (.min-agent/config.json)").conflicts("global"),
+        new Option("--global", "Apply to every project (~/.min-agent/config.json)").conflicts("project"),
+    ];
+}
+/** Resolve --project/--global into a Scope, given an optional fallback. */
+export function resolveScope(opts, fallback = "global") {
+    if (opts.project)
+        return "project";
+    if (opts.global)
+        return "global";
+    return fallback;
+}
+export function parseSandboxModeArg(value) {
+    const parsed = parseSandboxMode(value);
+    if (!parsed)
+        throw userError(`Invalid --sandbox value: "${value}"`, "use one of: off, workspace, strict");
+    return parsed;
+}
+export function parseNetworkPolicyArg(value) {
+    const parsed = parseNetworkPolicy(value);
+    if (!parsed)
+        throw userError(`Invalid --network value: "${value}"`, "use one of: allow, deny");
+    return parsed;
+}
+export function parsePermissionModeArg(value) {
+    const parsed = parsePermissionMode(value);
+    if (!parsed)
+        throw userError(`Invalid --permission value: "${value}"`, "use one of: ask, accept-edits, allow-all");
+    return parsed;
+}
+export function parsePortArg(value) {
+    const n = Number.parseInt(value, 10);
+    if (!Number.isFinite(n) || n <= 0 || n > 65535) {
+        throw userError(`Invalid --port value: "${value}"`, "use an integer between 1 and 65535");
+    }
+    return n;
+}
+export function parsePositiveIntArg(flagName) {
+    return (value) => {
+        const n = Number.parseInt(value, 10);
+        if (!Number.isFinite(n) || n <= 0) {
+            throw userError(`Invalid ${flagName} value: "${value}"`, "use a positive integer");
+        }
+        return n;
+    };
+}

package/dist/cli/program.js

@@ -0,0 +1,180 @@
+import { Command, Option } from "commander";
+import { setAutoApprove } from "../confirm.js";
+import { CliError, formatCliError, exitCodeFor } from "./errors.js";
+import { parseNetworkPolicyArg, parsePermissionModeArg, parseSandboxModeArg } from "./option-helpers.js";
+import { localVersion } from "../updater.js";
+function collectImage(value, previous) {
+    return [...previous, value];
+}
+/** Options shared across the root command and `exec` (session-affecting flags). */
+export function addSessionOptions(cmd) {
+    return cmd
+        .option("-m, --model <model>", "Override model for this request")
+        .option("--provider <name>", "Use a specific configured provider")
+        .option("--resume <id>", "Resume a previous session by id")
+        .option("-i, --image <path>", "Attach an image (repeatable)", collectImage, [])
+        .addOption(new Option("--sandbox <mode>", "Isolation mode (off, workspace, strict)").argParser(parseSandboxModeArg))
+        .addOption(new Option("--network <policy>", "Network policy (allow, deny)").argParser(parseNetworkPolicyArg))
+        .addOption(new Option("--permission <mode>", "Confirmation mode (ask, accept-edits, allow-all)").argParser(parsePermissionModeArg))
+        .option("--project", "Write --permission/--sandbox to this repo's config")
+        .option("--global", "Write --permission/--sandbox to the global config")
+        .option("-y, --yes", "This session only: same as --permission allow-all");
+}
+export function buildProgram() {
+    const program = new Command("min-agent");
+    program
+        .description("min-agent - Minimal AI coding agent")
+        .version(localVersion(), "-v, --version", "Show version number")
+        .helpOption("-h, --help", "Show help")
+        .allowUnknownOption()
+        .enablePositionalOptions()
+        .configureOutput({
+        writeErr: (str) => process.stderr.write(str),
+        outputError: (str) => process.stderr.write(str),
+    })
+        .exitOverride();
+    addSessionOptions(program);
+    program.argument("[prompt...]", "Prompt to send in an interactive session");
+    program.addHelpText("after", `
+Session:
+  min-agent                          Start interactive session
+  min-agent <message>                Start interactive session and send message
+  min-agent --resume <id>            Resume a previous interactive session
+  min-agent chat | code              Same as interactive session (compat)
+  min-agent exec <message>           Run one message non-interactively
+  min-agent exec --resume <id> <msg> Continue a saved exec session
+
+Setup & config:
+  min-agent setup                    Configure providers (interactively)
+  min-agent init                     Initialize .min-agent/ in current directory
+  min-agent models                   List available models
+  min-agent rules [edit]             Show or edit instruction rules
+  min-agent memory <add|search|delete|list>   Manage saved memories
+  min-agent sandbox [off|workspace|strict]    Show or set isolation mode
+  min-agent sandbox network <allow|deny>      Show or set network policy
+  min-agent permission [ask|accept-edits|allow-all]  Show or set confirmation mode
+
+Integrations:
+  min-agent mcp <list|add|remove|info|check|enable|disable>   Manage MCP servers
+  min-agent skills <list|info|new|enable|disable>             Manage skills
+
+Operations:
+  min-agent serve [--host H] [--port P]   Start the HTTP API (see docs/API.md)
+  min-agent history [delete|rename|export]  Manage saved sessions
+  min-agent update                          Upgrade to the latest npm release
+
+Confirmation modes (default: ask; independent of isolation):
+  ask            Prompt before dangerous operations
+  accept-edits   Auto-approve file writes; still prompt for dangerous commands
+  allow-all      Auto-approve everything
+
+Isolation modes (default: off; independent of confirmation):
+  off        No sandboxing
+  workspace  Restrict file writes to the project workspace
+  strict     Restrict file writes and deny risky commands
+  Env: MIN_AGENT_SANDBOX, MIN_AGENT_SANDBOX_NETWORK
+
+Rules (loaded as system instructions):
+  Global:  ~/.min-agent/rules.md
+  Project: ./AGENTS.md or ./RULES.md or ./.min-agent/AGENTS.md
+  Config:  "instructions" array in ~/.min-agent/config.json
+
+Examples:
+  min-agent setup
+  min-agent
+  min-agent "hello"
+  min-agent exec "hello"
+  min-agent exec --resume <id> "continue"
+  min-agent --resume <id>
+  min-agent --permission ask
+  min-agent serve --port 8787
+  min-agent update
+  min-agent rules edit
+  min-agent mcp add filesystem npx -y @modelcontextprotocol/server-filesystem /tmp
+  min-agent mcp add remote --url https://example.com/mcp --token "$TOKEN"
+`);
+    return program;
+}
+/** Apply --yes/-y for this process. Sandbox/permission overrides are applied per-invocation-kind. */
+export function applySessionOverrides(opts) {
+    if (opts.yes)
+        setAutoApprove(true);
+}
+export function hasSessionIntent(opts, prompt) {
+    return (prompt.length > 0 || Boolean(opts.resume) || opts.image.length > 0 || Boolean(opts.model) || Boolean(opts.provider));
+}
+/** Extract `--unknown` style tokens left over in positionals (from allowUnknownOption) as errors. */
+export function extractUnknownOptionErrors(positionals) {
+    const rest = [];
+    const errors = [];
+    for (const p of positionals) {
+        if (p.startsWith("--"))
+            errors.push(`Unknown option: ${p}`);
+        else
+            rest.push(p);
+    }
+    return { rest, errors };
+}
+async function runRootAction(promptTokens, opts) {
+    applySessionOverrides(opts);
+    const { setSandboxOverride } = await import("../sandbox.js");
+    const { setPermissionOverride } = await import("../confirm.js");
+    const { rest, errors } = extractUnknownOptionErrors(promptTokens);
+    const sessionIntent = hasSessionIntent(opts, rest);
+    const wantsConfigWrite = opts.sandbox !== undefined || opts.network !== undefined || opts.permission !== undefined;
+    if (wantsConfigWrite && !sessionIntent) {
+        const { runWriteConfig } = await import("./commands/write-config.js");
+        await runWriteConfig({
+            sandbox: opts.sandbox,
+            network: opts.network,
+            permission: opts.permission,
+            scope: opts.project ? "project" : opts.global ? "global" : undefined,
+        });
+        return;
+    }
+    if (opts.sandbox !== undefined)
+        setSandboxOverride({ mode: opts.sandbox });
+    if (opts.network !== undefined)
+        setSandboxOverride({ network: opts.network });
+    if (opts.permission !== undefined)
+        setPermissionOverride(opts.permission);
+    if (errors.length > 0) {
+        console.error(errors[0]);
+        process.exitCode = 1;
+        return;
+    }
+    const { startTuiSession } = await import("./commands/shared.js");
+    await startTuiSession({
+        model: opts.model,
+        provider: opts.provider,
+        resume: opts.resume,
+        images: opts.image,
+        positionals: rest,
+    });
+}
+export async function runProgram(argv, registerCommands) {
+    const program = buildProgram();
+    program.action((promptTokens, opts) => runRootAction(promptTokens, opts));
+    registerCommands(program);
+    try {
+        await program.parseAsync(argv, { from: "user" });
+    }
+    catch (err) {
+        if (err instanceof CliError) {
+            console.error(formatCliError(err));
+            process.exitCode = exitCodeFor(err);
+            return;
+        }
+        // Commander throws a CommanderError for --help/--version and for its own
+        // usage errors; those already printed output and set process.exitCode.
+        if (isCommanderExit(err)) {
+            process.exitCode = err.exitCode;
+            return;
+        }
+        console.error(formatCliError(err));
+        process.exitCode = 2;
+    }
+}
+function isCommanderExit(err) {
+    return typeof err === "object" && err !== null && "exitCode" in err && "code" in err;
+}