aiden-runtime 4.0.1 → 4.1.0

package/dist/core/v4/logger/sinks/nullSink.js

@@ -0,0 +1,53 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/logger/sinks/nullSink.ts — Phase v4.1-1.3a
+ *
+ * Discard every record. The default for `'test'` mode so vitest output
+ * stays clean even when the code under test emits warnings — and the
+ * fallback when a module is constructed without a logger (the
+ * `noopLogger` factory in `../factory.ts` uses this).
+ *
+ * `MemorySink` is also here: it captures records into an in-process
+ * array so tests can assert on log output without any I/O. Two surfaces
+ * in one file because they share the "nothing leaves this process"
+ * property.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemorySink = exports.NullSink = void 0;
+/** Drops every record. */
+class NullSink {
+    write(_record) { }
+}
+exports.NullSink = NullSink;
+/**
+ * Captures every record into `records`. Tests use this:
+ *
+ *   const sink = new MemorySink();
+ *   const log = new CoreLogger({ sinks: [sink] });
+ *   log.info('hello');
+ *   expect(sink.records[0].msg).toBe('hello');
+ *
+ * `clear()` resets between assertions; `findScope()` is a small
+ * convenience for "did the channels.telegram scope log anything?".
+ */
+class MemorySink {
+    constructor() {
+        this.records = [];
+    }
+    write(r) {
+        this.records.push(r);
+    }
+    clear() {
+        this.records.length = 0;
+    }
+    findScope(scope) {
+        return this.records.filter((r) => r.scope === scope || r.scope.startsWith(`${scope}.`));
+    }
+}
+exports.MemorySink = MemorySink;

package/dist/core/v4/logger/sinks/stdSink.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/logger/sinks/stdSink.ts — Phase v4.1-1.3a
+ *
+ * Stdout / stderr sinks. Two flavours:
+ *
+ *   - StderrSink     — pretty single-line format; used in cli-headless
+ *                      mode for warnings + errors so the user sees them
+ *                      without polluting stdout (which scripts may pipe).
+ *   - StdoutJsonSink — NDJSON one-record-per-line; used in `serve` mode
+ *                      so log aggregators (systemd-journald, docker logs,
+ *                      Loki, etc.) get structured fields.
+ *
+ * No StdoutPrettySink in 3a — `cli-interactive` deliberately wires no
+ * stdout sink at all (REPL is sacred), and `cli-headless` uses the
+ * stderr flavour so stdout stays free for tool output piping. If a
+ * future mode needs colourful stdout (e.g. `aiden status` one-shot),
+ * add it then.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StdoutJsonSink = exports.StderrSink = void 0;
+const LEVEL_THRESHOLD = {
+    debug: 10, info: 20, warn: 30, error: 40,
+};
+class StderrSink {
+    constructor(opts = {}) {
+        this.minLevel = LEVEL_THRESHOLD[opts.minLevel ?? 'warn'];
+    }
+    write(r) {
+        if (LEVEL_THRESHOLD[r.level] < this.minLevel)
+            return;
+        const scope = r.scope ? ` [${r.scope}]` : '';
+        try {
+            process.stderr.write(`${r.ts.toISOString()} [${r.level}]${scope} ${r.msg}\n`);
+        }
+        catch { /* dropped */ }
+    }
+}
+exports.StderrSink = StderrSink;
+/**
+ * NDJSON stdout for `serve` mode. One record per line, structured
+ * fields preserved. Aggregators love this; humans don't. Headless
+ * scripts that want pretty output use the file sink instead and tail
+ * the log file.
+ */
+class StdoutJsonSink {
+    constructor(opts = {}) {
+        this.minLevel = LEVEL_THRESHOLD[opts.minLevel ?? 'debug'];
+    }
+    write(r) {
+        if (LEVEL_THRESHOLD[r.level] < this.minLevel)
+            return;
+        const payload = {
+            ts: r.ts.toISOString(),
+            level: r.level,
+            scope: r.scope || undefined,
+            msg: r.msg,
+        };
+        if (r.ctx)
+            Object.assign(payload, r.ctx);
+        try {
+            process.stdout.write(safeJson(payload) + '\n');
+        }
+        catch { /* dropped */ }
+    }
+}
+exports.StdoutJsonSink = StdoutJsonSink;
+function safeJson(obj) {
+    try {
+        return JSON.stringify(obj);
+    }
+    catch {
+        return '{"err":"unserializable"}';
+    }
+}

package/dist/core/v4/mcp/server/diagnostics.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/mcp/server/diagnostics.ts — Phase v4.1-mcp
+ *
+ * Build fingerprint + counts surfaced by the `aiden mcp status` CLI
+ * subcommand and the launch log line. The fingerprint follows the same
+ * convention the Telegram adapter set in v4.1-3.2 — a constant string
+ * the user can grep for to verify the build that's actually running
+ * matches the phase they expected.
+ *
+ * Bump on every shipped phase. Format: `v4.1-mcp[+suffix]`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AIDEN_MCP_BUILD = void 0;
+exports.collectMcpDiagnostics = collectMcpDiagnostics;
+const toolBridge_1 = require("./toolBridge");
+/** Build fingerprint — bump per phase. Surfaced in `aiden mcp status`
+ *  and the stderr launch line so it's grep-able from the spawning
+ *  client's log stream. */
+exports.AIDEN_MCP_BUILD = 'v4.1-mcp.2';
+async function collectMcpDiagnostics(registry, loader, env = (0, toolBridge_1.readToolBridgeEnv)()) {
+    const exposed = (0, toolBridge_1.exposedToolNames)(registry, env);
+    const skills = await loader.list();
+    return {
+        build: exports.AIDEN_MCP_BUILD,
+        toolsTotal: registry.list().length,
+        toolsExposed: exposed.length,
+        skillsTotal: skills.length,
+        env: {
+            allowDestructive: env.allowDestructive,
+            allowlist: env.allowlist ? [...env.allowlist].sort() : null,
+        },
+    };
+}

package/dist/core/v4/mcp/server/skillBridge.js

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/mcp/server/skillBridge.ts — Phase v4.1-mcp
+ *
+ * Expose Aiden's loaded skills as MCP resources. Skills are inert
+ * markdown playbooks (`SKILL.md` + frontmatter), perfect candidates for
+ * MCP's read-only resource surface.
+ *
+ * URI scheme — `aiden-skill://<name>`. We deliberately namespaced this
+ * (rather than the bare `skill://`) so when a client connects to multiple
+ * agent MCP servers, resource URIs do not collide. The `name` segment is
+ * the SKILL.md frontmatter `name` field, which is already the lookup key
+ * used by the rest of the runtime (`SkillLoader.load(name)`).
+ *
+ * The bridge is intentionally read-only:
+ *   - `resources/list` enumerates every loaded skill
+ *   - `resources/read` returns the raw markdown (frontmatter + body)
+ *
+ * Mutations live behind the `skill_manage` tool; an MCP client that
+ * needs to install or modify a skill must go through that tool path so
+ * the same trust-level checks the REPL uses also apply remotely.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.skillUri = skillUri;
+exports.parseSkillUri = parseSkillUri;
+exports.summaryToResource = summaryToResource;
+exports.buildResourcesList = buildResourcesList;
+exports.readSkillResource = readSkillResource;
+const node_fs_1 = require("node:fs");
+const URI_SCHEME = 'aiden-skill';
+const URI_PREFIX = `${URI_SCHEME}://`;
+function skillUri(name) {
+    return `${URI_PREFIX}${encodeURIComponent(name)}`;
+}
+/** Pull the `<name>` segment back out of an `aiden-skill://<name>` URI.
+ *  Returns null on malformed input — the read handler reports `isError`
+ *  in that case rather than crashing the protocol. */
+function parseSkillUri(uri) {
+    if (!uri.startsWith(URI_PREFIX))
+        return null;
+    const raw = uri.slice(URI_PREFIX.length);
+    if (!raw)
+        return null;
+    try {
+        return decodeURIComponent(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function summaryToResource(s) {
+    return {
+        uri: skillUri(s.name),
+        name: s.name,
+        description: s.description,
+        mimeType: 'text/markdown',
+    };
+}
+/**
+ * Build the resources array advertised on `resources/list`. Walks the
+ * SkillLoader cache (already warmed at boot in the runtime) so this is
+ * just an in-memory map.
+ */
+async function buildResourcesList(loader) {
+    const list = await loader.list();
+    return list.map(summaryToResource);
+}
+/**
+ * `resources/read` handler. Returns the raw SKILL.md content for the
+ * named skill. Throws when the URI is malformed or the skill is unknown
+ * — the stdio-server layer maps those to JSON-RPC errors.
+ */
+async function readSkillResource(loader, uri) {
+    const name = parseSkillUri(uri);
+    if (name === null) {
+        throw new Error(`Malformed resource URI (expected ${URI_PREFIX}<name>): ${uri}`);
+    }
+    const skill = await loader.load(name);
+    if (!skill) {
+        throw new Error(`Skill not found: ${name}`);
+    }
+    // SKILL.md content lives on disk. The loader exposes `filePath`; read
+    // the raw bytes so the client gets frontmatter + body verbatim. (We
+    // could reconstruct from `frontmatter` + `content`, but raw avoids
+    // round-trip drift if the loader ever rewrites YAML on parse.)
+    const text = await node_fs_1.promises.readFile(skill.filePath, 'utf-8');
+    return { uri, mimeType: 'text/markdown', text };
+}

package/dist/core/v4/mcp/server/stdioServer.js

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/mcp/server/stdioServer.ts — Phase v4.1-mcp
+ *
+ * Stand up a Model Context Protocol server over stdio. Three protocol
+ * surfaces are wired:
+ *
+ *   - tools/list      → toolBridge.buildToolsList()
+ *   - tools/call      → toolBridge.buildToolCallHandler()
+ *   - resources/list  → skillBridge.buildResourcesList()
+ *   - resources/read  → skillBridge.readSkillResource()
+ *
+ * stdio invariants:
+ *   - stdout is the JSON-RPC channel — NEVER write to it from this
+ *     process outside the SDK transport. The logger is built in
+ *     `'mcp-stdio'` mode (file + stderr only) and tools should only
+ *     emit through that logger.
+ *   - the launch banner goes to stderr on purpose; spawning clients
+ *     (Claude Desktop, Cursor) capture stderr in their MCP log so the
+ *     user can grep the build fingerprint to verify what's running.
+ *
+ * The server function is a long-running call: it returns a `stop()`
+ * handle but ordinarily blocks until the parent closes the stdio pair.
+ * The CLI's `serve` action awaits a never-resolving promise so the
+ * Node process stays alive.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AIDEN_MCP_BUILD = void 0;
+exports.startStdioMcpServer = startStdioMcpServer;
+// SDK 1.29 ships its public surface via the package `exports` map.
+// Use the SDK's documented import paths verbatim — the wildcard
+// `paths` mapping in tsconfig.json lets the legacy
+// `moduleResolution: "node"` resolver find the type declarations,
+// while at runtime Node's exports-map resolver picks the same files.
+// (An earlier shape — `.../sdk/server/index` — typechecked but failed
+// at runtime: Node's wildcard fallback yielded a path missing the
+// `.js` extension. Phase v4.1-mcp.1 fix.)
+const server_1 = require("@modelcontextprotocol/sdk/server");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const factory_1 = require("../../logger/factory");
+const toolBridge_1 = require("./toolBridge");
+const skillBridge_1 = require("./skillBridge");
+const diagnostics_1 = require("./diagnostics");
+var diagnostics_2 = require("./diagnostics");
+Object.defineProperty(exports, "AIDEN_MCP_BUILD", { enumerable: true, get: function () { return diagnostics_2.AIDEN_MCP_BUILD; } });
+/**
+ * Wire the MCP server up over stdio. Returns once the transport is
+ * connected; the caller is responsible for keeping the process alive
+ * (the `aiden mcp serve` CLI does this with a never-resolving promise).
+ */
+async function startStdioMcpServer(opts) {
+    const logger = opts.logger ?? (0, factory_1.noopLogger)();
+    const env = opts.env ?? (0, toolBridge_1.readToolBridgeEnv)();
+    const server = new server_1.Server({ name: 'aiden', version: diagnostics_1.AIDEN_MCP_BUILD }, { capabilities: { tools: {}, resources: {} } });
+    const callTool = (0, toolBridge_1.buildToolCallHandler)(opts.registry, opts.toolContext, env, logger);
+    // ── tools/list ──────────────────────────────────────────────
+    server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
+        tools: (0, toolBridge_1.buildToolsList)(opts.registry, env),
+    }));
+    // ── tools/call ──────────────────────────────────────────────
+    // SDK 1.29 typed the response as a discriminated union including a
+    // task-style alternative. Aiden returns the non-task `CallToolResult`
+    // shape; the cast widens the return type to the union.
+    server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+        const name = request.params.name;
+        const args = (request.params.arguments ?? {});
+        const result = await callTool(name, args);
+        return result;
+    });
+    // ── resources/list ──────────────────────────────────────────
+    server.setRequestHandler(types_js_1.ListResourcesRequestSchema, async () => ({
+        resources: await (0, skillBridge_1.buildResourcesList)(opts.skillLoader),
+    }));
+    // ── resources/read ──────────────────────────────────────────
+    server.setRequestHandler(types_js_1.ReadResourceRequestSchema, async (request) => {
+        const uri = request.params.uri;
+        try {
+            const content = await (0, skillBridge_1.readSkillResource)(opts.skillLoader, uri);
+            return { contents: [content] };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            logger.warn('mcp resources/read failed', { scope: 'mcp', uri, error: message });
+            throw err;
+        }
+    });
+    // ── connect transport ──────────────────────────────────────
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    // Diagnostics — emitted to stderr (logger in mcp-stdio mode), grep-able
+    // from the spawning client's MCP log. Build fingerprint included so the
+    // user can verify the running version matches the phase they expected.
+    const diag = await (0, diagnostics_1.collectMcpDiagnostics)(opts.registry, opts.skillLoader, env);
+    logger.warn(`mcp launched build=${diag.build}`, {
+        scope: 'mcp',
+        build: diag.build,
+        toolsTotal: diag.toolsTotal,
+        toolsExposed: diag.toolsExposed,
+        skillsTotal: diag.skillsTotal,
+        allowDestructive: diag.env.allowDestructive,
+        allowlist: diag.env.allowlist,
+    });
+    return {
+        server,
+        stop: async () => {
+            try {
+                await server.close();
+            }
+            catch { /* already closed */ }
+        },
+    };
+}

package/dist/core/v4/mcp/server/toolBridge.js

@@ -0,0 +1,168 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/mcp/server/toolBridge.ts — Phase v4.1-mcp
+ *
+ * Bridge between Aiden's `ToolRegistry` and the MCP wire format. The
+ * registry already stores schemas in the exact shape MCP wants
+ * (`{ name, description, inputSchema: { type: 'object', properties, required? } }`),
+ * so this layer is a thin pass-through plus three filters:
+ *
+ *   1. `mutates` filter — read-only tools by default. Set
+ *      `AIDEN_MCP_ALLOW_DESTRUCTIVE=1` to expose write/execute tools too.
+ *      Phase-9 approval engine still gates them at execution time
+ *      (defense in depth).
+ *   2. Allowlist filter — `AIDEN_MCP_TOOL_ALLOWLIST=tool_a,tool_b`
+ *      restricts the surface to a CSV-named subset. Applied AFTER the
+ *      mutates filter, so a user cannot allowlist `shell_exec` past the
+ *      destructive gate without also setting `ALLOW_DESTRUCTIVE=1`.
+ *   3. The handler wrapper coerces every dispatch outcome into MCP's
+ *      `CallToolResult` shape `{ content, isError }`. The agent loop's
+ *      executor returns `ToolCallResult` whose `.error` field is set when
+ *      the underlying handler threw or the moat layers refused the call;
+ *      that becomes `isError: true` here. We NEVER throw out of the
+ *      handler — protocol-level errors bypass the model's recovery path.
+ *
+ * The bridge is dependency-injected with the ToolRegistry + ToolContext
+ * the runtime already built. It does not own a logger; the stdio server
+ * passes one through for the env-config diagnostic line.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readToolBridgeEnv = readToolBridgeEnv;
+exports.exposedToolNames = exposedToolNames;
+exports.aidenToolToMCP = aidenToolToMCP;
+exports.buildToolsList = buildToolsList;
+exports.buildToolCallHandler = buildToolCallHandler;
+const factory_1 = require("../../logger/factory");
+function readToolBridgeEnv(env = process.env) {
+    const allowDestructive = env.AIDEN_MCP_ALLOW_DESTRUCTIVE === '1' ||
+        env.AIDEN_MCP_ALLOW_DESTRUCTIVE === 'true';
+    const raw = (env.AIDEN_MCP_TOOL_ALLOWLIST ?? '').trim();
+    const allowlist = raw
+        ? new Set(raw.split(',').map((s) => s.trim()).filter(Boolean))
+        : null;
+    return { allowDestructive, allowlist };
+}
+/**
+ * Compute the set of tool names exposed under the current env. Pure
+ * function over the registry snapshot; safe to call on every
+ * `tools/list` request (the registry is built once at boot).
+ */
+function exposedToolNames(registry, env) {
+    const out = [];
+    for (const name of registry.list()) {
+        const handler = registry.get(name);
+        if (!handler)
+            continue;
+        if (handler.mutates && !env.allowDestructive)
+            continue;
+        if (env.allowlist && !env.allowlist.has(name))
+            continue;
+        out.push(name);
+    }
+    return out;
+}
+/** Pass-through schema convert. The shapes are already aligned. */
+function aidenToolToMCP(handler) {
+    const s = handler.schema;
+    return {
+        name: s.name,
+        description: s.description,
+        inputSchema: {
+            type: 'object',
+            properties: s.inputSchema.properties,
+            required: s.inputSchema.required,
+        },
+    };
+}
+/** Build the tools array advertised on `tools/list`. */
+function buildToolsList(registry, env) {
+    const out = [];
+    for (const name of exposedToolNames(registry, env)) {
+        const handler = registry.get(name);
+        if (handler)
+            out.push(aidenToolToMCP(handler));
+    }
+    return out;
+}
+/**
+ * Build a `tools/call` handler closed over the registry's executor and
+ * the per-process env. Each call:
+ *
+ *   1. Re-checks exposure (env may have shifted is irrelevant — we read
+ *      it at server start — but this guards against allowlist drift if
+ *      a future caller passes a fresh env snapshot).
+ *   2. Synthesises a `ToolCallRequest` for the executor; uses a stable
+ *      id so logs cross-correlate.
+ *   3. Maps the executor's `ToolCallResult` to MCP's `{content,isError}`.
+ *
+ * Failures the executor reports via `result.error` become `isError: true`
+ * with the error message in the text payload — the model on the client
+ * side reads it and recovers. We never throw protocol-level.
+ */
+function buildToolCallHandler(registry, context, env, logger = (0, factory_1.noopLogger)()) {
+    const exposed = new Set(exposedToolNames(registry, env));
+    const execute = registry.buildExecutor(context);
+    return async (name, args) => {
+        if (!exposed.has(name)) {
+            logger.warn('mcp tools/call refused — tool not exposed', {
+                scope: 'mcp',
+                tool: name,
+                allowDestructive: env.allowDestructive,
+            });
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            error: `Tool "${name}" is not exposed via MCP.`,
+                            hint: env.allowDestructive
+                                ? 'Tool may not be in AIDEN_MCP_TOOL_ALLOWLIST.'
+                                : 'Set AIDEN_MCP_ALLOW_DESTRUCTIVE=1 to include mutating tools.',
+                        }),
+                    }],
+                isError: true,
+            };
+        }
+        const id = `mcp-${name}-${Date.now().toString(36)}`;
+        const call = { id, name, arguments: args ?? {} };
+        let result;
+        try {
+            result = await execute(call);
+        }
+        catch (err) {
+            // The executor itself swallows handler exceptions, but a bug in
+            // the executor (or a moat layer hard-throw) would land here.
+            const message = err instanceof Error ? err.message : String(err);
+            logger.error('mcp tools/call executor crashed', {
+                scope: 'mcp',
+                tool: name,
+                error: message,
+            });
+            return {
+                content: [{ type: 'text', text: `Internal error: ${message}` }],
+                isError: true,
+            };
+        }
+        if (result.error) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ error: result.error }, null, 2),
+                    }],
+                isError: true,
+            };
+        }
+        const text = typeof result.result === 'string'
+            ? result.result
+            : JSON.stringify(result.result ?? null, null, 2);
+        return {
+            content: [{ type: 'text', text }],
+            isError: false,
+        };
+    };
+}

package/dist/core/v4/platformPaths.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod). Licensed under AGPL-3.0.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/platformPaths.ts — Phase v4.1-cross-platform
+ *
+ * Cross-platform helpers for path normalisation, home expansion,
+ * shell selection, and writability checks. Centralising these so
+ * every other module can import a single canonical surface — and
+ * so the path audit has one place to scan for OS-specific bugs.
+ *
+ * Most of the work delegates to Node's built-in `path` module; the
+ * value-add is the small bit of glue (`expandHome`, `platformShell`,
+ * `isWritable`) that's easy to get wrong if redone ad-hoc.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizePath = normalizePath;
+exports.joinPaths = joinPaths;
+exports.expandHome = expandHome;
+exports.platformShell = platformShell;
+exports.isWritable = isWritable;
+exports.isReadable = isReadable;
+exports.classifyPlatform = classifyPlatform;
+const node_path_1 = __importDefault(require("node:path"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_fs_1 = __importDefault(require("node:fs"));
+/** Idiomatic platform-aware path normalisation. */
+function normalizePath(p) {
+    if (typeof p !== 'string' || p.length === 0)
+        return p;
+    return node_path_1.default.normalize(p);
+}
+/** Re-export `path.join` under a stable name so callers don't have to import path directly. */
+function joinPaths(...parts) {
+    return node_path_1.default.join(...parts);
+}
+/**
+ * Expand `~/` and `~` to the current user's home directory. Pass
+ * paths through unchanged if they don't start with the tilde token.
+ *
+ *   expandHome('~/foo')  → `${os.homedir()}/foo`
+ *   expandHome('~')      → `${os.homedir()}`
+ *   expandHome('/abs/p') → '/abs/p'
+ *   expandHome('./rel')  → './rel'
+ */
+function expandHome(p) {
+    if (typeof p !== 'string' || p.length === 0)
+        return p;
+    if (p === '~')
+        return node_os_1.default.homedir();
+    if (p.startsWith('~/') || p.startsWith('~\\')) {
+        return node_path_1.default.join(node_os_1.default.homedir(), p.slice(2));
+    }
+    return p;
+}
+function platformShell() {
+    if (process.platform === 'win32')
+        return 'powershell';
+    // POSIX: prefer bash when present, otherwise sh. We don't probe at
+    // runtime — bash is ubiquitous on macOS/Linux and `sh` is the
+    // POSIX-mandated fallback. Callers that need certainty can call
+    // `which bash` themselves.
+    return 'bash';
+}
+/**
+ * Cross-platform writability check. Returns true if the path exists
+ * AND the current process can write to it, false otherwise. Catches
+ * EACCES/EPERM/ENOENT silently — never throws.
+ */
+function isWritable(p) {
+    try {
+        node_fs_1.default.accessSync(p, node_fs_1.default.constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Cross-platform readability check — paired with isWritable for
+ * doctor's filesystem audit.
+ */
+function isReadable(p) {
+    try {
+        node_fs_1.default.accessSync(p, node_fs_1.default.constants.R_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function classifyPlatform() {
+    switch (process.platform) {
+        case 'win32': return 'win32';
+        case 'darwin': return 'darwin';
+        case 'linux': return 'linux';
+        default: return 'other';
+    }
+}