@voidlabs.gg/voidshift 0.0.0-stage → 0.4.1

package/dist/commands/doctor.js

@@ -0,0 +1,52 @@
+import { baseChecks, run } from "../checks.js";
+import { context, readConfig } from "../config.js";
+import { loadTool } from "../loader.js";
+import { findTool } from "../registry.js";
+import { CLI_PKG, cliVersion, isNewer } from "../version.js";
+import { parseFlags } from "./args.js";
+import { usages } from "./help.js";
+import { latestVersion } from "./update.js";
+const mark = { ok: '✓', warn: '!', fail: '✗' };
+export function formatChecks(checks) {
+    const width = Math.max(...checks.map((c) => c.name.length));
+    return checks
+        .map((c) => {
+        const line = `${mark[c.status]} ${c.name.padEnd(width)}  ${c.detail}`;
+        return c.fix && c.status !== 'ok' ? `${line}\n  ${' '.repeat(width)}  ${c.fix}` : line;
+    })
+        .join('\n');
+}
+export async function doctor(args = []) {
+    const parsed = parseFlags(args, { json: { type: 'boolean' } }, usages.doctor);
+    if (!parsed)
+        return 2;
+    if (parsed.values.help) {
+        console.log(usages.doctor);
+        return 0;
+    }
+    const checks = baseChecks(process.platform, process.version, run);
+    const ctx = context();
+    for (const name of readConfig().tools) {
+        const entry = findTool(name);
+        if (!entry) {
+            checks.push({ name: 'config', status: 'warn', detail: `unknown tool ${name} in your config`, fix: `vsf remove ${name}` });
+            continue;
+        }
+        try {
+            checks.push(...(await (await loadTool(entry, ctx.configDir)).checks(ctx)));
+        }
+        catch (err) {
+            checks.push({ name, status: 'fail', detail: err.message });
+        }
+    }
+    const latest = latestVersion(CLI_PKG);
+    if (latest && isNewer(latest, cliVersion())) {
+        checks.push({ name: 'VoidShift', status: 'warn', detail: `${latest} is out (you have ${cliVersion()})`, fix: 'vsf update' });
+    }
+    else {
+        checks.push({ name: 'VoidShift', status: 'ok', detail: cliVersion() });
+    }
+    const ok = !checks.some((c) => c.status === 'fail');
+    console.log(parsed.values.json ? JSON.stringify({ ok, checks }, null, 2) : formatChecks(checks));
+    return ok ? 0 : 1;
+}

package/dist/commands/help.d.ts

@@ -0,0 +1,3 @@
+export declare const usages: Record<string, string>;
+export declare function mainHelp(): string;
+export declare function help(args: string[]): Promise<number>;

package/dist/commands/help.js

@@ -0,0 +1,59 @@
+import { findTool, registry } from "../registry.js";
+import { toolHelp } from "./tools.js";
+// Usage lines per umbrella command, shared by `vsf help <command>` and each
+// command's own --help.
+export const usages = {
+    setup: 'Usage: vsf setup [tool] [--defaults]\n\nPick your tools and configure them, or set up one tool.\n--defaults takes every default and asks only what has none.',
+    ui: 'Usage: vsf ui\n\nOpen the dashboard. Plain vsf opens it too. Needs a terminal.',
+    status: 'Usage: vsf status [--json]\n\nShow what each added tool is doing.',
+    doctor: 'Usage: vsf doctor [--json]\n\nCheck this Mac is ready. Exits 1 when a check fails.',
+    config: 'Usage:\n  vsf config [tool] [--json]     Show saved settings\n  vsf config get KEY             Print one setting, e.g. awake.battery\n  vsf config set KEY VALUE       Change a setting (VALUE is JSON, or plain text)\n                                 Negative numbers: vsf config set KEY -- -5\n  vsf config unset KEY           Remove a setting\n  vsf config edit [tool]         Edit a tool\'s settings in $EDITOR',
+    tools: 'Usage: vsf tools\n\nList available tools.',
+    add: 'Usage: vsf add <tool>\n\nInstall and set up a tool.',
+    remove: 'Usage: vsf remove <tool>\n\nTake a tool down and uninstall it.',
+    update: 'Usage: vsf update\n\nUpdate VoidShift and every tool you added.',
+    help: 'Usage: vsf help [command or tool]\n\nShow every command, or the usage of one command or tool.',
+};
+export function mainHelp() {
+    const width = Math.max(...registry.map((t) => t.name.length));
+    const tools = registry.map((t) => `  ${t.name.padEnd(width)}  ${t.summary}`).join('\n');
+    return `vsf: one CLI for the Void dev tools
+
+Usage
+  vsf                          Open the dashboard (also: vsf ui)
+  vsf setup [tool] [--defaults]  Pick your tools and configure them
+  vsf status [--json]          What each tool is doing
+  vsf doctor [--json]          Check this Mac is ready
+  vsf config [tool] [--json]   Show saved settings
+  vsf config get|set|unset KEY [VALUE]
+  vsf config edit [tool]       Edit a tool's settings in $EDITOR
+  vsf tools                    List available tools
+  vsf add|remove <tool>        Install or take down a tool
+  vsf update                   Update VoidShift and every tool you added
+  vsf help [command or tool]   Show help
+  vsf --version                Print the version
+
+Tools
+${tools}
+
+vsf <tool> help lists a tool's commands.
+`;
+}
+export async function help(args) {
+    const [name] = args;
+    if (!name) {
+        console.log(mainHelp());
+        return 0;
+    }
+    if (Object.hasOwn(usages, name)) {
+        const usage = usages[name];
+        console.log(usage);
+        return 0;
+    }
+    const entry = findTool(name);
+    if (!entry) {
+        console.error(`unknown command or tool: ${name}. Run vsf help.`);
+        return 2;
+    }
+    return toolHelp(entry, args.slice(1));
+}

package/dist/commands/setup.d.ts

@@ -0,0 +1,2 @@
+export declare function setupCommand(args: string[]): Promise<number>;
+export declare function setup(defaults?: boolean): Promise<number>;

package/dist/commands/setup.js

@@ -0,0 +1,135 @@
+import * as p from '@clack/prompts';
+import { baseChecks, run } from "../checks.js";
+import { context, readConfig, writeConfig } from "../config.js";
+import { fetchTool, loadTool } from "../loader.js";
+import { findTool, registry } from "../registry.js";
+import { needsTerminal, parseFlags } from "./args.js";
+import { usages } from "./help.js";
+import { Cancelled } from "../ui.js";
+import { formatChecks } from "./doctor.js";
+// Download, install and record one tool. Shared by `vsf setup` and `vsf setup <tool>`.
+async function installTool(entry, ctx) {
+    if (!fetchTool(entry, ctx.configDir)) {
+        p.log.error(`Could not download ${entry.pkg}.`);
+        return false;
+    }
+    try {
+        await (await loadTool(entry, ctx.configDir)).install(ctx);
+        const tools = readConfig().tools;
+        if (!tools.includes(entry.name))
+            writeConfig({ ...readConfig(), tools: [...tools, entry.name] });
+        return true;
+    }
+    catch (err) {
+        if (err instanceof Cancelled)
+            throw err;
+        p.log.error(`${entry.name}: ${err.message}`);
+        return false;
+    }
+}
+// `vsf setup <tool>`: set up or reconfigure just one tool.
+async function setupTool(name, defaults) {
+    const entry = findTool(name);
+    if (!entry) {
+        console.error(`unknown tool: ${name}. Run vsf tools to see the list.`);
+        return 2;
+    }
+    if (entry.status === 'planned') {
+        console.error(`${entry.name} is not released yet.`);
+        return 1;
+    }
+    p.intro(`VoidShift: ${entry.name}`);
+    try {
+        if (!(await installTool(entry, context(true, defaults))))
+            return 1;
+    }
+    catch (err) {
+        if (err instanceof Cancelled)
+            return 1;
+        throw err;
+    }
+    p.outro(`${entry.name} is set up.`);
+    return 0;
+}
+export async function setupCommand(args) {
+    const parsed = parseFlags(args, { defaults: { type: 'boolean' } }, usages.setup);
+    if (!parsed)
+        return 2;
+    const [tool, extra] = parsed.positionals;
+    if (extra) {
+        console.error(`too many arguments.\n\n${usages.setup}`);
+        return 2;
+    }
+    const defaults = parsed.values.defaults === true;
+    if (!defaults && needsTerminal('setup', 'Run it in a terminal, or use vsf setup --defaults.'))
+        return 2;
+    return tool ? setupTool(tool, defaults) : setup(defaults);
+}
+// `vsf setup` with no tool: check the machine, pick tools, configure
+// each one. Safe to run again; it starts from what is already set up.
+export async function setup(defaults = false) {
+    p.intro(defaults ? 'VoidShift (defaults)' : 'VoidShift');
+    const base = baseChecks(process.platform, process.version, run);
+    const line = base.map((c) => `${c.status === 'ok' ? '✓' : c.status === 'warn' ? '!' : '✗'} ${c.name}`).join('   ');
+    if (base.some((c) => c.status === 'fail')) {
+        p.log.error(formatChecks(base.filter((c) => c.status !== 'ok')));
+        p.outro('Fix the items above, then run vsf setup again.');
+        return 1;
+    }
+    p.log.info(line);
+    for (const c of base.filter((c) => c.status === 'warn'))
+        p.log.warn(`${c.name}: ${c.detail}. ${c.fix ?? ''}`);
+    const ctx = context(true, defaults);
+    const config = readConfig();
+    try {
+        const available = registry.filter((t) => t.status !== 'planned').map((t) => t.name);
+        const picked = defaults
+            ? [...new Set([...config.tools, ...available])]
+            : await p.multiselect({
+                message: 'Which tools do you want?',
+                options: registry.map((t) => ({
+                    value: t.name,
+                    label: t.name,
+                    hint: t.status === 'planned' ? `${t.summary} (coming soon)` : t.summary,
+                    disabled: t.status === 'planned',
+                })),
+                initialValues: config.tools,
+                required: false,
+            });
+        if (p.isCancel(picked))
+            throw (p.cancel('Setup cancelled. Nothing was changed.'), new Cancelled());
+        if (defaults)
+            p.log.info(`Which tools do you want?  ${picked.join(', ')}`);
+        for (const name of config.tools.filter((t) => !picked.includes(t))) {
+            const entry = registry.find((t) => t.name === name);
+            if (!entry)
+                continue;
+            if (!(await ctx.ui.confirm(`Remove ${name}?`, false)))
+                continue;
+            p.log.step(name);
+            try {
+                await (await loadTool(entry, ctx.configDir)).uninstall(ctx);
+            }
+            catch (err) {
+                if (err instanceof Cancelled)
+                    throw err;
+                p.log.warn(`${name}: ${err.message} Removed it from your tools anyway.`);
+            }
+            writeConfig({ tools: readConfig().tools.filter((t) => t !== name) });
+        }
+        for (const name of picked) {
+            const entry = registry.find((t) => t.name === name);
+            if (!entry)
+                continue;
+            p.log.step(name);
+            await installTool(entry, ctx);
+        }
+    }
+    catch (err) {
+        if (err instanceof Cancelled)
+            return 1;
+        throw err;
+    }
+    p.outro('All set. Run vsf setup any time to change this, or vsf doctor to check it.');
+    return 0;
+}

package/dist/commands/status.d.ts

@@ -0,0 +1,2 @@
+export declare function toolStatusJson(code: number, out: string): unknown;
+export declare function status(args: string[]): Promise<number>;

package/dist/commands/status.js

@@ -0,0 +1,60 @@
+import { context, readConfig } from "../config.js";
+import { loadTool } from "../loader.js";
+import { findTool } from "../registry.js";
+import { CLI_PKG, cliVersion, isNewer } from "../version.js";
+import { parseFlags } from "./args.js";
+import { usages } from "./help.js";
+import { latestVersion } from "./update.js";
+// A tool's captured --json output, or its error text when it failed.
+export function toolStatusJson(code, out) {
+    return code === 0 ? JSON.parse(out) : { error: out.trim() || `status exited ${code}` };
+}
+function newer() {
+    const latest = latestVersion(CLI_PKG, 3_000);
+    return latest && isNewer(latest, cliVersion()) ? { current: cliVersion(), latest } : null;
+}
+export async function status(args) {
+    const parsed = parseFlags(args, { json: { type: 'boolean' } }, usages.status);
+    if (!parsed)
+        return 2;
+    if (parsed.values.help) {
+        console.log(usages.status);
+        return 0;
+    }
+    const json = parsed.values.json === true;
+    const base = context();
+    const tools = {};
+    for (const name of readConfig().tools) {
+        const entry = findTool(name);
+        if (!entry)
+            continue;
+        try {
+            const tool = await loadTool(entry, base.configDir);
+            const command = tool.commands?.status;
+            if (!command)
+                continue;
+            if (json) {
+                let out = '';
+                const code = await command(['--json'], { ...base, log: (line) => (out += line + '\n') });
+                tools[name] = toolStatusJson(code, out);
+            }
+            else {
+                console.log(name);
+                await command([], { ...base, log: (line) => console.log(line.split('\n').map((l) => `  ${l}`).join('\n')) });
+            }
+        }
+        catch (err) {
+            const message = err.message;
+            if (json)
+                tools[name] = { error: message };
+            else
+                console.log(`${name}: ${message}`);
+        }
+    }
+    const update = newer();
+    if (json)
+        console.log(JSON.stringify({ tools, update }, null, 2));
+    else if (update)
+        console.log(`Update: ${update.latest} is out (you have ${update.current}). Run vsf update.`);
+    return 0;
+}

package/dist/commands/tools.d.ts

@@ -0,0 +1,9 @@
+import { type ToolEntry } from '../registry.ts';
+import type { Tool } from '../tool.ts';
+export declare function listTools(): number;
+export declare function addTool(name: string | undefined): Promise<number>;
+export declare function removeTool(name: string | undefined): Promise<number>;
+export declare function toolUsage(name: string, tool: Tool): string;
+export declare function routeTool(sub: string | undefined, commands: Record<string, unknown> | undefined): 'help' | 'unknown' | 'run';
+export declare function toolHelp(entry: ToolEntry, args: string[]): Promise<number>;
+export declare function runToolCommand(entry: ToolEntry, args: string[]): Promise<number>;

package/dist/commands/tools.js

@@ -0,0 +1,111 @@
+import { context, readConfig, writeConfig } from "../config.js";
+import { fetchTool, loadTool } from "../loader.js";
+import { findTool, registry } from "../registry.js";
+import { needsTerminal, wantsHelp } from "./args.js";
+export function listTools() {
+    const installed = new Set(readConfig().tools);
+    const width = Math.max(...registry.map((t) => t.name.length));
+    for (const t of registry) {
+        const tag = installed.has(t.name) ? ' (added)' : t.status === 'planned' ? ' (coming soon)' : '';
+        console.log(`${t.name.padEnd(width)}  ${t.summary}${tag}`);
+    }
+    return 0;
+}
+function lookup(name, verb) {
+    if (!name) {
+        console.error(`usage: vsf ${verb} <tool>`);
+        return null;
+    }
+    const tool = findTool(name);
+    if (!tool)
+        console.error(`unknown tool: ${name}. Run vsf tools to see the list.`);
+    return tool ?? null;
+}
+export async function addTool(name) {
+    if (needsTerminal('add', 'Run it in a terminal.'))
+        return 2;
+    const entry = lookup(name, 'add');
+    if (!entry)
+        return 2;
+    if (entry.status === 'planned') {
+        console.error(`${entry.name} is not released yet.`);
+        return 1;
+    }
+    const ctx = context();
+    if (!fetchTool(entry, ctx.configDir)) {
+        console.error(`could not download ${entry.pkg}`);
+        return 1;
+    }
+    try {
+        await (await loadTool(entry, ctx.configDir)).install(ctx);
+    }
+    catch (err) {
+        console.error(`${entry.name}: ${err.message}`);
+        return 1;
+    }
+    const config = readConfig();
+    if (!config.tools.includes(entry.name))
+        writeConfig({ ...config, tools: [...config.tools, entry.name] });
+    return 0;
+}
+export async function removeTool(name) {
+    if (needsTerminal('remove', 'Run it in a terminal.'))
+        return 2;
+    const entry = lookup(name, 'remove');
+    if (!entry)
+        return 2;
+    const ctx = context();
+    const config = readConfig();
+    if (!config.tools.includes(entry.name)) {
+        console.error(`${entry.name} is not added.`);
+        return 1;
+    }
+    await (await loadTool(entry, ctx.configDir)).uninstall(ctx);
+    writeConfig({ ...config, tools: config.tools.filter((t) => t !== entry.name) });
+    console.log(`${entry.name} removed.`);
+    return 0;
+}
+const INTERNAL = ['tick', 'recall', 'steps'];
+export function toolUsage(name, tool) {
+    const names = Object.keys(tool.commands ?? {}).filter((n) => !INTERNAL.includes(n));
+    return `Usage: vsf ${name} <${names.join('|')}>\n\nvsf ${name} <command> --help shows a command's usage.`;
+}
+// Decide what `vsf <tool> <sub>` means: help, an unknown command, or run it.
+export function routeTool(sub, commands) {
+    if (sub === undefined || sub === 'help' || sub === '--help' || sub === '-h')
+        return 'help';
+    return commands && Object.hasOwn(commands, sub) ? 'run' : 'unknown';
+}
+// The tool's own help command if it has one, else a generated listing.
+export async function toolHelp(entry, args) {
+    const ctx = context();
+    const tool = await loadTool(entry, ctx.configDir);
+    if (tool.commands && Object.hasOwn(tool.commands, 'help'))
+        return tool.commands.help(args, ctx);
+    console.log(toolUsage(entry.name, tool));
+    return 0;
+}
+export async function runToolCommand(entry, args) {
+    const ctx = context();
+    const [sub, ...rest] = args;
+    // Help never needs the tool to be added; it is fetched as needed.
+    const asksHelp = sub === 'help' || sub === '--help' || sub === '-h' || (sub !== undefined && wantsHelp(rest));
+    if (!asksHelp && !readConfig().tools.includes(entry.name)) {
+        console.error(`${entry.name} is not added. Run vsf add ${entry.name}`);
+        return 1;
+    }
+    const tool = await loadTool(entry, ctx.configDir);
+    const route = routeTool(sub, tool.commands);
+    if (route === 'help')
+        return toolHelp(entry, sub === undefined ? [] : rest);
+    if (route === 'unknown') {
+        console.error(`unknown command: ${entry.name} ${sub}\n\n${toolUsage(entry.name, tool)}`);
+        return 2;
+    }
+    // Internal commands are run by schedulers, not people: help shows the tool's usage.
+    if (INTERNAL.includes(sub) && wantsHelp(rest)) {
+        console.log(toolUsage(entry.name, tool));
+        return 0;
+    }
+    return tool.commands[sub](rest, ctx);
+}

package/dist/commands/update.d.ts

@@ -0,0 +1,2 @@
+export declare function latestVersion(pkg: string, timeout?: number): string | null;
+export declare function update(): Promise<number>;

package/dist/commands/update.js

@@ -0,0 +1,79 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { configDir, readConfig } from "../config.js";
+import { npm } from "../loader.js";
+import { findTool } from "../registry.js";
+import { CLI_PKG, cliVersion, isNewer } from "../version.js";
+// --prefer-online: right after a release npm's local metadata cache can still
+// name the previous version as latest.
+const QUIET = ['--silent', '--no-audit', '--no-fund', '--prefer-online'];
+export function latestVersion(pkg, timeout = 15_000) {
+    const r = spawnSync('npm', ['view', '--prefer-online', pkg, 'version'], { encoding: 'utf8', timeout });
+    return r.status === 0 ? r.stdout.trim() || null : null;
+}
+function installedToolVersion(pkg) {
+    const path = join(configDir(), 'tools', 'node_modules', pkg, 'package.json');
+    return existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')).version : null;
+}
+// Running from a checkout of the repo rather than an npm install.
+const fromSource = () => fileURLToPath(import.meta.url).endsWith('.ts');
+export async function update() {
+    let failed = false;
+    let changed = false;
+    // One install for every outdated tool: they share a folder, so npm may move
+    // the others too. Report by comparing versions before and after.
+    const tools = readConfig().tools.map((name) => findTool(name)).filter((e) => !!e);
+    const before = new Map(tools.map((e) => [e.name, installedToolVersion(e.pkg)]));
+    const targets = [];
+    for (const entry of tools) {
+        const latest = latestVersion(entry.pkg);
+        if (!latest) {
+            console.log(`${entry.name}: could not check npm`);
+            failed = true;
+            continue;
+        }
+        const current = before.get(entry.name);
+        if (!current || isNewer(latest, current))
+            targets.push(`${entry.pkg}@${latest}`);
+    }
+    if (targets.length) {
+        if (!npm(['install', ...QUIET, '--prefix', join(configDir(), 'tools'), ...targets])) {
+            console.log('Tool update failed.');
+            failed = true;
+        }
+    }
+    for (const entry of tools) {
+        const was = before.get(entry.name);
+        const now = installedToolVersion(entry.pkg);
+        if (now && now !== was) {
+            console.log(`${entry.name} ${was ?? 'not downloaded'} → ${now}`);
+            changed = true;
+        }
+    }
+    const current = cliVersion();
+    const latest = latestVersion(CLI_PKG);
+    if (!latest) {
+        console.log('vsf: could not check npm');
+        failed = true;
+    }
+    else if (isNewer(latest, current)) {
+        if (fromSource()) {
+            console.log(`vsf ${latest} is out; this copy runs from source, so pull the repo instead.`);
+        }
+        else {
+            if (npm(['install', '-g', ...QUIET, `${CLI_PKG}@${latest}`])) {
+                console.log(`vsf ${current} → ${latest}`);
+                changed = true;
+            }
+            else {
+                console.log(`vsf: update failed. Run: npm i -g ${CLI_PKG}@latest`);
+                failed = true;
+            }
+        }
+    }
+    if (!changed && !failed)
+        console.log(`Already up to date (vsf ${current}).`);
+    return failed ? 1 : 0;
+}

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+import type { ToolContext } from './tool.ts';
+export declare function configDir(): string;
+interface Config {
+    tools: string[];
+}
+export declare function readConfig(): Config;
+export declare function writeConfig(config: Config): void;
+export declare function context(quiet?: boolean, defaults?: boolean): ToolContext;
+export {};

package/dist/config.js

@@ -0,0 +1,29 @@
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { defaultsUi, ui } from "./ui.js";
+// ~/.config/voidshift, not ~/.voidshift: the older private daemon owns that.
+export function configDir() {
+    return process.env.VOIDSHIFT_HOME ?? join(homedir(), '.config', 'voidshift');
+}
+const configPath = () => join(configDir(), 'config.json');
+export function readConfig() {
+    if (!existsSync(configPath()))
+        return { tools: [] };
+    return JSON.parse(readFileSync(configPath(), 'utf8'));
+}
+export function writeConfig(config) {
+    mkdirSync(configDir(), { recursive: true });
+    writeFileSync(configPath(), JSON.stringify(config, null, 2) + '\n');
+}
+// `quiet` routes tool output through the setup UI instead of plain lines.
+export function context(quiet = false, defaults = false) {
+    return {
+        defaults,
+        home: homedir(),
+        configDir: configDir(),
+        selfCommand: [process.execPath, realpathSync(process.argv[1] ?? '')],
+        log: quiet ? (line) => ui.info(line) : (line) => console.log(line),
+        ui: defaults ? defaultsUi : ui,
+    };
+}

package/dist/dotted.d.ts

@@ -0,0 +1,9 @@
+type Obj = Record<string, unknown>;
+export declare function getPath(obj: unknown, path: string[]): unknown;
+export declare function setPath(obj: Obj, path: string[], value: unknown): Obj;
+export declare function unsetPath(obj: Obj, path: string[]): Obj;
+export declare function flatten(obj: unknown, prefix?: string): [string, unknown][];
+export declare function parseValue(text: string): unknown;
+export declare function mask(key: string, value: unknown): unknown;
+export declare function maskDeep(value: unknown, key?: string): unknown;
+export {};

package/dist/dotted.js

@@ -0,0 +1,86 @@
+// Helpers for `vsf config`: address nested settings by a dotted key.
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const isIndex = (k) => /^\d+$/.test(k);
+const isContainer = (v) => typeof v === 'object' && v !== null;
+export function getPath(obj, path) {
+    let cur = obj;
+    for (const k of path) {
+        if (Array.isArray(cur)) {
+            if (!isIndex(k) || Number(k) >= cur.length)
+                return undefined;
+            cur = cur[Number(k)];
+        }
+        else if (isObj(cur) && Object.hasOwn(cur, k)) {
+            cur = cur[k];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return cur;
+}
+// Returns a new object; the input is left alone. Non-container values on the way are replaced.
+// A numeric segment into an array addresses that element (memory.homes.0.dir).
+export function setPath(obj, path, value) {
+    const out = structuredClone(obj);
+    let cur = out;
+    const slot = (c, k) => (Array.isArray(c) && isIndex(k) ? Number(k) : k);
+    for (const k of path.slice(0, -1)) {
+        const at = slot(cur, k);
+        const next = cur[at];
+        if (!isContainer(next))
+            cur[at] = {};
+        cur = cur[at];
+    }
+    const last = path[path.length - 1];
+    if (last !== undefined)
+        cur[slot(cur, last)] = value;
+    return out;
+}
+export function unsetPath(obj, path) {
+    const out = structuredClone(obj);
+    const parent = path.length > 1 ? getPath(out, path.slice(0, -1)) : out;
+    const last = path[path.length - 1];
+    if (last === undefined)
+        return out;
+    if (Array.isArray(parent)) {
+        if (isIndex(last) && Number(last) < parent.length)
+            parent.splice(Number(last), 1);
+    }
+    else if (isObj(parent)) {
+        delete parent[last];
+    }
+    return out;
+}
+// Arrays and empty objects are leaves.
+export function flatten(obj, prefix = '') {
+    if (!isObj(obj) || Object.keys(obj).length === 0)
+        return prefix ? [[prefix, obj]] : [];
+    return Object.entries(obj).flatMap(([k, v]) => flatten(v, prefix ? `${prefix}.${k}` : k));
+}
+export function parseValue(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+// Matched against one key segment, anchored so maxTokens, keywords and
+// keyboard stay visible while apiKey, key, accessToken, clientSecret hide.
+const SECRET = /key$|token$|secret|password|passphrase/i;
+const last = (key) => key.split('.').pop() ?? key;
+export function mask(key, value) {
+    return SECRET.test(last(key)) ? '****' : value;
+}
+// Mask secrets inside a nested value. A secret-looking key hides its whole
+// subtree; arrays are walked too. `key` is the key the value sits under.
+export function maskDeep(value, key = '') {
+    if (key && SECRET.test(last(key)))
+        return '****';
+    if (Array.isArray(value))
+        return value.map((v) => maskDeep(v));
+    if (isObj(value))
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, maskDeep(v, k)]));
+    return value;
+}

package/dist/loader.d.ts

@@ -0,0 +1,6 @@
+import type { ToolEntry } from './registry.ts';
+import type { Tool } from './tool.ts';
+export declare function locate(entry: ToolEntry, configDir: string): string | null;
+export declare function npm(args: string[]): boolean;
+export declare function fetchTool(entry: ToolEntry, configDir: string): boolean;
+export declare function loadTool(entry: ToolEntry, configDir: string): Promise<Tool>;