fauxnix-cli 0.9.3 → 0.12.0

package/dist/install.js

@@ -0,0 +1,247 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { claudeUserConfigPath, codexConfigPath, fauxnixServerNames, hasCodexFauxnix, hasOpenCodeFauxnix, isServerMap, openCodeConfigPath, serverMapHasFauxnix, } from './doctor.js';
+import { resolveQwenLaunchTuple, sameQwenLaunchTuple } from './qwen-launch.js';
+export const INSTALL_FLAGS = ['claude', 'codex', 'opencode', 'kimi', 'qwen'];
+const STDIO = { command: 'fauxnix', args: ['mcp'] };
+const OPENCODE_STDIO = { type: 'local', command: ['fauxnix', 'mcp'] };
+export function kimiConfigPath(home, env) {
+    const root = env.KIMI_CODE_HOME?.trim() || join(home, '.kimi-code');
+    return join(root, 'mcp.json');
+}
+export function qwenConfigPath(home, env) {
+    return join(home, '.qwen', 'settings.json');
+}
+export function runInstall(argv, opts = {}) {
+    const parsed = parseHarnessFlags(argv);
+    if (parsed.help)
+        return { lines: installUsageLines(), ok: true };
+    if (parsed.error)
+        return { lines: [parsed.error, ...installUsageLines()], ok: false };
+    const ctx = {
+        home: opts.home ?? homedir(),
+        env: opts.env ?? process.env,
+    };
+    const lines = [];
+    let ok = true;
+    for (const name of parsed.harnesses) {
+        const one = installHarness(name, ctx);
+        lines.push(one.line);
+        if (!one.ok)
+            ok = false;
+    }
+    return { lines, ok };
+}
+function parseHarnessFlags(argv) {
+    if (argv.some((a) => a === '--help' || a === '-h'))
+        return { help: true, harnesses: [] };
+    if (argv.length === 0) {
+        return { error: 'select a harness: --claude --codex --opencode --kimi --qwen', harnesses: [] };
+    }
+    const harnesses = [];
+    const seen = new Set();
+    for (const a of argv) {
+        if (!a.startsWith('--') || a === '--') {
+            return { error: `unknown argument: ${a}`, harnesses: [] };
+        }
+        const name = a.slice(2);
+        if (!isHarness(name))
+            return { error: `unknown harness: ${a}`, harnesses: [] };
+        if (!seen.has(name)) {
+            seen.add(name);
+            harnesses.push(name);
+        }
+    }
+    return { harnesses };
+}
+function isHarness(s) {
+    return INSTALL_FLAGS.includes(s);
+}
+function installUsageLines() {
+    return ['Usage:', '  fauxnix install --claude|--codex|--opencode|--kimi|--qwen'];
+}
+function installHarness(name, ctx) {
+    switch (name) {
+        case 'claude':
+            return patchMcpServers(claudeUserConfigPath(ctx.home, ctx.env), 'claude');
+        case 'codex':
+            return patchCodex(codexConfigPath(ctx.home, ctx.env));
+        case 'opencode':
+            return patchOpenCode(openCodeConfigPath(ctx.home, ctx.env));
+        case 'kimi':
+            return patchMcpServers(kimiConfigPath(ctx.home, ctx.env), 'kimi');
+        case 'qwen':
+            return patchQwen(qwenConfigPath(ctx.home, ctx.env));
+    }
+}
+function patchQwen(path) {
+    const launch = resolveQwenLaunchTuple();
+    if (!launch.ok)
+        return { ok: false, line: `qwen: ${launch.reason} — not modified` };
+    const read = readJsonObject(path);
+    if (read.state === 'invalid') {
+        return { ok: false, line: `qwen: ${path} is ${read.reason} — not modified` };
+    }
+    const existed = read.state !== 'missing';
+    const data = read.state === 'ok' ? read.data : {};
+    if (data.mcpServers != null && !isServerMap(data.mcpServers)) {
+        return { ok: false, line: `qwen: ${path} mcpServers is not an object — not modified` };
+    }
+    if (!isServerMap(data.mcpServers))
+        data.mcpServers = {};
+    const servers = data.mcpServers;
+    const extraNames = fauxnixServerNames(servers).filter((name) => name !== 'fauxnix');
+    if (extraNames.length) {
+        return {
+            ok: false,
+            line: `qwen: ${path} has another fauxnix MCP entry (${extraNames.join(', ')}) — remove the extra entry, then retry; not modified`,
+        };
+    }
+    const current = servers.fauxnix;
+    if (current != null && !isServerMap(current)) {
+        return {
+            ok: false,
+            line: `qwen: ${path} mcpServers.fauxnix is not an object — not modified`,
+        };
+    }
+    if (sameQwenLaunchTuple(current, launch.value)) {
+        return { ok: true, line: `qwen: already configured with an absolute launcher (${path})` };
+    }
+    servers.fauxnix = {
+        ...(isServerMap(current) ? current : {}),
+        command: launch.value.command,
+        args: [...launch.value.args],
+    };
+    return writeJson(path, data, 'qwen', existed, current == null ? 'added mcpServers.fauxnix' : 'updated mcpServers.fauxnix launcher');
+}
+function patchMcpServers(path, harness) {
+    const read = readJsonObject(path);
+    if (read.state === 'invalid') {
+        return { ok: false, line: `${harness}: ${path} is ${read.reason} — not modified` };
+    }
+    const existed = read.state !== 'missing';
+    const data = read.state === 'ok' ? read.data : {};
+    if (serverMapHasFauxnix(data.mcpServers)) {
+        return { ok: true, line: `${harness}: already configured (${path})` };
+    }
+    if (data.mcpServers != null && !isServerMap(data.mcpServers)) {
+        return { ok: false, line: `${harness}: ${path} mcpServers is not an object — not modified` };
+    }
+    if (!isServerMap(data.mcpServers))
+        data.mcpServers = {};
+    data.mcpServers.fauxnix = {
+        command: STDIO.command,
+        args: [...STDIO.args],
+    };
+    return writeJson(path, data, harness, existed, 'added mcpServers.fauxnix');
+}
+function patchOpenCode(path) {
+    const read = readJsonObject(path);
+    if (read.state === 'invalid') {
+        return { ok: false, line: `opencode: ${path} is ${read.reason} — not modified` };
+    }
+    const existed = read.state !== 'missing';
+    const data = read.state === 'ok' ? read.data : {};
+    if (hasOpenCodeFauxnix(data)) {
+        return { ok: true, line: `opencode: already configured (${path})` };
+    }
+    if (data.mcp != null && !isServerMap(data.mcp)) {
+        return { ok: false, line: `opencode: ${path} mcp is not an object — not modified` };
+    }
+    if (!isServerMap(data.mcp))
+        data.mcp = {};
+    const mcp = data.mcp;
+    const payload = { type: OPENCODE_STDIO.type, command: [...OPENCODE_STDIO.command] };
+    if (isServerMap(mcp.servers)) {
+        mcp.servers.fauxnix = payload;
+        return writeJson(path, data, 'opencode', existed, 'added mcp.servers.fauxnix');
+    }
+    mcp.fauxnix = payload;
+    return writeJson(path, data, 'opencode', existed, 'added mcp.fauxnix');
+}
+function patchCodex(path) {
+    const existed = existsSync(path);
+    if (!existed) {
+        const written = writeText(path, tomlTable('\n'));
+        if (!written.ok)
+            return { ok: false, line: `codex: failed to write ${path}: ${written.error}` };
+        return { ok: true, line: `codex: created ${path}` };
+    }
+    const text = readText(path);
+    if (text === undefined) {
+        return { ok: false, line: `codex: ${path} is unreadable — not modified` };
+    }
+    if (hasCodexFauxnix(stripBom(text))) {
+        return { ok: true, line: `codex: already configured (${path})` };
+    }
+    const nl = text.includes('\r\n') ? '\r\n' : '\n';
+    if (stripBom(text).trim() === '') {
+        const written = writeText(path, tomlTable(nl));
+        if (!written.ok)
+            return { ok: false, line: `codex: failed to write ${path}: ${written.error}` };
+        return { ok: true, line: `codex: patched ${path} (appended [mcp_servers.fauxnix])` };
+    }
+    let body = text;
+    if (!body.endsWith('\n'))
+        body += nl;
+    if (!body.endsWith(nl + nl))
+        body += nl;
+    const written = writeText(path, body + tomlTable(nl));
+    if (!written.ok)
+        return { ok: false, line: `codex: failed to write ${path}: ${written.error}` };
+    return { ok: true, line: `codex: patched ${path} (appended [mcp_servers.fauxnix])` };
+}
+function tomlTable(nl) {
+    return `[mcp_servers.fauxnix]${nl}command = "fauxnix"${nl}args = ["mcp"]${nl}`;
+}
+function writeJson(path, data, harness, existed, change) {
+    const written = writeText(path, JSON.stringify(data, null, 2) + '\n');
+    if (!written.ok) {
+        return { ok: false, line: `${harness}: failed to write ${path}: ${written.error}` };
+    }
+    if (existed)
+        return { ok: true, line: `${harness}: patched ${path} (${change})` };
+    return { ok: true, line: `${harness}: created ${path}` };
+}
+function writeText(path, contents) {
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, contents, 'utf8');
+        return { ok: true };
+    }
+    catch (e) {
+        return { ok: false, error: e instanceof Error ? e.message : String(e) };
+    }
+}
+function readJsonObject(path) {
+    if (!existsSync(path))
+        return { state: 'missing' };
+    const text = readText(path);
+    if (text === undefined)
+        return { state: 'invalid', reason: 'unreadable' };
+    const stripped = stripBom(text).trim();
+    if (stripped === '')
+        return { state: 'empty' };
+    try {
+        const data = JSON.parse(stripped);
+        if (!data || typeof data !== 'object' || Array.isArray(data)) {
+            return { state: 'invalid', reason: 'not a JSON object' };
+        }
+        return { state: 'ok', data: data };
+    }
+    catch {
+        return { state: 'invalid', reason: 'not valid JSON' };
+    }
+}
+function stripBom(text) {
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+function readText(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/mcp.d.ts

@@ -19,5 +19,24 @@ export declare function bashToolResult(r: ExecResult, sessionId: string, infra:
         sessionId: string;
     };
 };
+export declare function translateToolResult(command: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: undefined;
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+};
+export declare function positionalCountFromEnv(env: Record<string, string>): number;
+export declare function formatSessionStatus(session: {
+    cwd: string | null;
+    env: Record<string, string>;
+    id: string;
+}): string;
 export declare function startMcpServer(): Promise<void>;
 export { translatePipelineBody };

package/dist/mcp.js

@@ -3,7 +3,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod';
 import { FauxnixSession } from './executor.js';
 import { parseCommand } from './parser.js';
-import { translateCommandList, wrapScript, translatePipelineBody } from './translator.js';
+import { EXECUTE_TRANSLATION, PURE_TRANSLATION, translateCommandList, wrapScript, translatePipelineBody, } from './translator.js';
 import { registeredNames } from './registry.js';
 import { packageVersion } from './version.js';
 import './commands/install-all.js';
@@ -31,11 +31,10 @@ const TOOL_DESCRIPTION = `Execute a Linux/bash-style command on this Windows mac
 Commands are deterministically translated to PowerShell and executed natively — no WSL or VM.
 Output is formatted to look like GNU/Linux tooling (ls -l, ps aux, df -h ...), errors look like bash errors, and text encoding (UTF-8/GBK) is handled automatically.
 
-Supported: pipes (|), && / || / ;, redirections (> >> 2> 2>&1 < /dev/null), variables ($VAR $HOME ~), command substitution $(...), and ${registeredNames().length}+ coreutils-style commands (${registeredNames().slice(0, 18).join(', ')}...).
+Supported: pipes (|), && / || / ;, redirections (> >> 2> 2>&1 < /dev/null), variables ($VAR $HOME $1 $# "$@" ~), set -- / shift, array assignment A=(x y z), \${name[n]} \${#name[@]} \${name//pat/str} \${name:off:len}, command substitution $(...), and ${registeredNames().length}+ coreutils-style commands (${registeredNames().slice(0, 18).join(', ')}...).
 Unknown commands (git, node, npm, python, cargo...) are passed through and executed natively with argv-style quoting.
-Not supported: heredocs, while/until/case, env -i/--ignore-environment, background jobs. if/then/elif/else/fi, for-in loops, and word-level \$((...)) arithmetic expansion are supported.
-
-CWD, environment variables, export/unset and cd persist across calls within this session — a resident PowerShell 5.1 host is started when the MCP session begins (and after reset), so the first bash tool call is already warm.
+Not supported: heredocs, env -i/--ignore-environment, background jobs. if/then/elif/else/fi, for-in loops, while/until, case ... esac, and word-level \$((...)) arithmetic expansion are supported.
+CWD, environment variables, export/unset, cd, and positional parameters (set -- / $1 / "$@") persist across calls within this session — a resident PowerShell 5.1 host is started when the MCP session begins (and after reset), so the first bash tool call is already warm.
 Exit codes follow bash conventions (0 ok, 1 fail, 2 usage/serious, 127 command not found, 124 timeout, 130 cancelled). The tool also returns structuredContent (schemaVersion 1) with stdout/stderr/exitCode/timedOut/cancelled/truncated/sessionId.
 
 Platform requirement: the execution backend is native Windows PowerShell 5.1+. On hosts without PowerShell on PATH (e.g. Linux containers/sandboxes), the bash tool returns exit code 127 with an actionable error instead of running the command.`;
@@ -70,7 +69,47 @@ export function bashToolResult(r, sessionId, infra) {
         ...(infra ? { isError: true } : {}),
     };
 }
+export function translateToolResult(command) {
+    try {
+        const list = parseCommand(command);
+        const plans = translateCommandList(list, PURE_TRANSLATION);
+        const script = wrapScript(plans.map((p) => p.script).join('\n# ---- next segment ----\n'));
+        return { content: [{ type: 'text', text: script }] };
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        return { content: [{ type: 'text', text: msg }], isError: true };
+    }
+}
+/** Packed FAUXNIX_POS uses char-30 separators (same as array sidecar). */
+const POS_SEP = '\x1e';
+export function positionalCountFromEnv(env) {
+    let packed;
+    for (const [k, v] of Object.entries(env)) {
+        if (k.toUpperCase() === 'FAUXNIX_POS') {
+            packed = v;
+            break;
+        }
+    }
+    if (packed == null || packed === '')
+        return 0;
+    return packed.split(POS_SEP).length;
+}
+export function formatSessionStatus(session) {
+    const envKeys = Object.keys(session.env).sort();
+    return ('cwd: ' +
+        (session.cwd ?? '(inherit from server start)') +
+        '\nenv keys: ' +
+        (envKeys.length ? envKeys.join(', ') : '(none tracked)') +
+        '\npositionals: ' +
+        positionalCountFromEnv(session.env) +
+        '\nsession: ' +
+        session.id +
+        '\ncommands registered: ' +
+        registeredNames().length);
+}
 export async function startMcpServer() {
+    process.env.FAUXNIX_ARG0 = TOOL_NAME;
     const server = new McpServer({ name: 'fauxnix', version: packageVersion }, { capabilities: { tools: {} } });
     const session = new FauxnixSession();
     await session.prewarm();
@@ -85,7 +124,7 @@ export async function startMcpServer() {
             .describe('Timeout in milliseconds (default 120000)'),
     }, EXEC_ANNOTATIONS, async ({ command, timeout_ms }, extra) => {
         try {
-            const plans = translateCommandList(parseCommand(command));
+            const plans = translateCommandList(parseCommand(command), EXECUTE_TRANSLATION);
             const result = await session.run(plans, {
                 timeoutMs: timeout_ms,
                 signal: extra.signal,
@@ -105,34 +144,18 @@ export async function startMcpServer() {
             }, session.id, true);
         }
     });
-    server.tool('fauxnix_translate', 'Translate a bash-style command into the equivalent PowerShell script WITHOUT executing it. Useful for learning/debugging what fauxnix does under the hood.', { command: z.string().describe('The bash-style command line to translate (never executed)') }, TRANSLATE_ANNOTATIONS, async ({ command }) => {
-        try {
-            const list = parseCommand(command);
-            const plans = translateCommandList(list);
-            const script = wrapScript(plans.map((p) => p.script).join('\n# ---- next segment ----\n'));
-            return { content: [{ type: 'text', text: script }] };
-        }
-        catch (e) {
-            const msg = e instanceof Error ? e.message : String(e);
-            return { content: [{ type: 'text', text: msg }], isError: true };
-        }
-    });
-    server.tool('fauxnix_session', 'Inspect or reset the persistent fauxnix shell session (current directory, environment, session id). Actions: "status" (default) or "reset".', {
+    server.tool('fauxnix_translate', 'Translate a bash-style command into the equivalent PowerShell script WITHOUT executing it. Useful for learning/debugging what fauxnix does under the hood.', { command: z.string().describe('The bash-style command line to translate (never executed)') }, TRANSLATE_ANNOTATIONS, async ({ command }) => translateToolResult(command));
+    server.tool('fauxnix_session', 'Inspect or reset the persistent fauxnix shell session (current directory, environment, positional count, session id). Actions: "status" (default) or "reset".', {
         action: z
             .enum(['status', 'reset'])
             .default('status')
-            .describe('"status" shows the session state (cwd, tracked env keys); "reset" clears it back to a fresh shell'),
+            .describe('"status" shows the session state (cwd, tracked env keys, positional count); "reset" clears it back to a fresh shell'),
     }, SESSION_ANNOTATIONS, async ({ action }) => {
         if (action === 'reset') {
             await session.reset();
             return { content: [{ type: 'text', text: 'fauxnix: session reset' }] };
         }
-        const envKeys = Object.keys(session.env).sort();
-        const text = 'cwd: ' + (session.cwd ?? '(inherit from server start)') +
-            '\nenv keys: ' + (envKeys.length ? envKeys.join(', ') : '(none tracked)') +
-            '\nsession: ' + session.id +
-            '\ncommands registered: ' + registeredNames().length;
-        return { content: [{ type: 'text', text }] };
+        return { content: [{ type: 'text', text: formatSessionStatus(session) }] };
     });
     const transport = new StdioServerTransport();
     let shuttingDown = false;