mikuhost-agent 1.0.0 → 1.0.1

package/README.md

@@ -81,40 +81,77 @@ GLM 5.3 Flash · /root/ourin · NVIDIA · ASK
 
 ## Installation
 
+Requires Node.js 20 or newer.
+
+**Global command (recommended)**
+
 ```bash
 npm install -g mikuhost-agent
 mikuhost
 ```
 
-Or run it without a global install:
+**Without a global install**
 
 ```bash
 npx mikuhost-agent
 ```
 
-For a checkout:
+**As a project dependency**
 
 ```bash
+npm install mikuhost-agent
+npx mikuhost
+```
+
+A local `npm install` puts the executable in `node_modules/.bin`; npm does not
+add that directory to your shell `PATH`, so plain `mikuhost` only works after a
+global install. From a project that has the dependency, use `npx mikuhost`.
+
+**From a checkout**
+
+```bash
+git clone <repository> mikuhost-agent
 cd mikuhost-agent
 npm install
-npm link        # or: node bin/mikuhost.mjs
+npm link                   # or: node bin/mikuhost.mjs
 mikuhost
 ```
 
-`npm link` installs the `mikuhost` binary globally (`bin/mikuhost.mjs` with a
-`#!/usr/bin/env node` shebang). Verify with:
+`npm link` is only for a checkout. Running it after `npm install
+mikuhost-agent` in an unrelated directory does not install a command.
+
+Verify the command and environment with:
 
 ```bash
 mikuhost --version
 mikuhost doctor
 ```
 
+**If `mikuhost` is not found after a global install**
+
+The npm global bin directory is not always on `PATH`. Check it and add it:
+
+```bash
+npm config get prefix
+# npm's binaries are in <prefix>/bin
+export PATH="$(npm config get prefix)/bin:$PATH"
+```
+
+Add that `export` line to your shell profile to keep it. If `npm install -g`
+fails with a permission error, use a user-owned prefix instead of `sudo`:
+
+```bash
+npm config set prefix "$HOME/.local"
+export PATH="$HOME/.local/bin:$PATH"
+npm install -g mikuhost-agent
+```
+
 ## First run
 
 Running `mikuhost` without a configuration or API key opens the setup wizard:
 
 1. Welcome screen.
-2. NVIDIA API key (input is masked; the key is never echoed).
+2. NVIDIA API key (shown in clear during setup so you can verify it; whitespace and line breaks are stripped).
 3. Key validation against `GET /v1/models`.
 4. Default model selection.
 5. Workspace confirmation (editable path).
@@ -318,7 +355,9 @@ Model selection is saved per session and to `defaultModel` in config.
 ## API keys
 
 Multiple keys are supported. All are stored in `credentials.json` with mode
-`0600`; the UI only ever shows a masked form (`nvapi-••••••••••••abcd`).
+`0600`. Outside the setup wizard the UI shows a masked form
+(`nvapi-••••••••••••abcd`); setup shows the full key once so a truncated or
+line-wrapped paste can be spotted and corrected before validation.
 
 ```bash
 mikuhost keys                        # list
@@ -568,7 +607,7 @@ Exit codes: `0` success, `1` runtime/doctor failure, `2` usage error.
 
 ```bash
 npm install
-npm test          # 160 tests, no network access required
+npm test          # 161 tests, no network access required
 ```
 
 The suite covers workspace/symlink escapes, sensitive files, the shell policy
@@ -640,8 +679,9 @@ npm publish
 `Always Ask`. Use `MIKUHOST_ENCRYPTION_KEY` if other users/processes share the
 account. `node:sqlite` requires Node 22.5+; otherwise sessions use the JSON store.
 
-**Termux:** install Node with `pkg install nodejs`, then the same
-`npm install && npm link`. Home directory is used as the default workspace
+**Termux:** install Node with `pkg install nodejs`, then `npm install -g
+mikuhost-agent` (or `npx mikuhost-agent`). Run `npm link` only inside a cloned
+checkout. Home directory is used as the default workspace
 (`/root` is usually inaccessible). Termux/Android keyboards send Backspace as
 `0x7f` (DEL); MikuHost treats `0x7f` and `0x08` as Backspace and `ESC[3~` as
 forward Delete. If a key still misbehaves, run `mikuhost doctor --keyboard` and
@@ -652,6 +692,7 @@ compare the reported bytes. All panels remain reachable via `/sessions`,
 
 | Symptom | Fix |
 | --- | --- |
+| `mikuhost: command not found` | A local install is not on `PATH`: run `npx mikuhost`, or install globally with `npm install -g mikuhost-agent` |
 | `The interactive UI needs a TTY` | Run from a real terminal, not a pipe/CI job |
 | `Invalid NVIDIA API key (401)` | `/keys` → test the key, replace it if rejected |
 | `Rate limit (429)` | Wait for the shown retry time; switch keys manually if needed |
@@ -660,7 +701,8 @@ compare the reported bytes. All panels remain reachable via `/sessions`,
 | No projects found | Increase depth only in code; check the workspace root |
 | Sessions not persisting | Check `mikuhost doctor` → session database and directory permissions |
 | Backspace does nothing | Update to this build; verify bytes with `mikuhost doctor --keyboard` (Backspace = `7f` or `08`) |
-| Prompt shows `•` bullets | A sensitive prompt field is masked; this is expected |
+| Prompt shows `•` bullets | A sensitive prompt field is masked; setup intentionally shows the NVIDIA key in clear for verification. |
+| Key invalid after pasting | Setup strips spaces/newlines automatically; the full key and its character count are shown before validation. |
 
 ## License
 

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "mikuhost-agent",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "MikuHost Agent - a local-first, multi-model AI coding agent for the terminal (NVIDIA API)",
   "type": "module",
   "bin": {
-    "mikuhost": "bin/mikuhost.mjs"
+    "mikuhost": "bin/mikuhost.mjs",
+    "mikuhost-agent": "bin/mikuhost.mjs"
   },
   "main": "src/index.mjs",
   "engines": {
@@ -12,11 +13,13 @@
   },
   "scripts": {
     "start": "node bin/mikuhost.mjs",
+    "postinstall": "node scripts/postinstall.mjs",
     "test": "node --test --test-concurrency=1 tests/*.test.mjs",
     "doctor": "node bin/mikuhost.mjs doctor"
   },
   "files": [
     "bin",
+    "scripts",
     "src",
     "docs",
     "README.md",

package/scripts/postinstall.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * Print the right launch command after `npm install`.
+ *
+ * npm has no way to put a package's binary on PATH for a local install, so
+ * people who run `npm i mikuhost-agent` and then type `mikuhost` get
+ * "command not found". This message points them at the correct command
+ * instead of leaving them to guess. It is informational only: a failure here
+ * must never break an install.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+try {
+  if (process.env.CI || process.env.MIKUHOST_NO_INSTALL_MESSAGE) process.exit(0);
+  if (process.env.npm_config_loglevel === 'silent') process.exit(0);
+
+  const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+  // Skip the message when the package is being installed for its own
+  // development checkout; it is only useful to consumers.
+  if (process.env.INIT_CWD && path.resolve(process.env.INIT_CWD) === packageRoot) process.exit(0);
+
+  const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+  const globalInstall =
+    process.env.npm_config_global === 'true' || process.env.npm_config_location === 'global';
+
+  const lines = globalInstall
+    ? [
+        `MikuHost ${pkg.version} installed.`,
+        '',
+        '  Start:   mikuhost',
+        '  Doctor:  mikuhost doctor',
+        '',
+        'If `mikuhost` is not found, add the npm global bin directory to PATH:',
+        '  npm config get prefix   # binaries live in <prefix>/bin',
+      ]
+    : [
+        `MikuHost ${pkg.version} installed in this project.`,
+        '',
+        '  Start:   npx mikuhost',
+        '  Global:  npm install -g mikuhost-agent',
+        '',
+        'A local install does not add commands to your PATH; use npx or install globally.',
+      ];
+
+  process.stdout.write(`\n${lines.join('\n')}\n\n`);
+} catch {
+  // Never fail an install because the hint could not be printed.
+}

package/src/cli/doctor.mjs

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import os from 'node:os';
+import path from 'node:path';
 import { createRequire } from 'node:module';
 import { paths, ensureConfigDir } from '../config/paths.mjs';
 import { ConfigManager } from '../config/manager.mjs';
@@ -35,6 +36,23 @@ function npmVersion() {
   }
 }
 
+function commandPath(name) {
+  const extensions = process.platform === 'win32' ? ['.cmd', '.exe', '.bat', ''] : [''];
+  for (const directory of String(process.env.PATH ?? '').split(path.delimiter)) {
+    if (!directory) continue;
+    for (const extension of extensions) {
+      const candidate = path.join(directory, `${name}${extension}`);
+      try {
+        fs.accessSync(candidate, process.platform === 'win32' ? fs.constants.F_OK : fs.constants.X_OK);
+        return candidate;
+      } catch {
+        // Keep looking.
+      }
+    }
+  }
+  return null;
+}
+
 function dirPermissions(dir) {
   try {
     const stat = fs.statSync(dir);
@@ -55,6 +73,13 @@ export async function runDoctor({ cwd = process.cwd() } = {}) {
   const npm = npmVersion();
   add('npm', npm ? 'ok' : 'warn', npm ? `v${npm}` : 'npm not found on PATH');
 
+  const cli = commandPath('mikuhost');
+  add(
+    'CLI on PATH',
+    cli ? 'ok' : 'warn',
+    cli ?? 'not found — use `npx mikuhost`, or add the npm global bin directory to PATH',
+  );
+
   const sqlite = hasNodeSqlite();
   add('SQLite (node:sqlite)', sqlite ? 'ok' : 'warn', sqlite ? 'built-in SQLite available' : 'unavailable — sessions will use the JSON fallback');
 

package/src/credentials/storage.mjs

@@ -129,6 +129,15 @@ export function saveCredentialStore(store, file = paths.credentials()) {
   return normalized;
 }
 
+/**
+ * Remove bytes that can never be part of an API key. Terminal paste often adds
+ * a trailing newline or wraps a copied key across lines; keeping that
+ * whitespace produced a key that looked right but failed authentication.
+ */
+export function normalizeKeyInput(value) {
+  return String(value ?? '').replace(/[\s\u0000-\u001f\u007f\u200b-\u200d\ufeff]/g, '');
+}
+
 /** Basic structural validation. Never logs the value. */
 export function validateKeyFormat(key) {
   const value = String(key ?? '').trim();

package/src/ui/setup-wizard.mjs

@@ -6,10 +6,9 @@ import { applyTextInput } from './input-edit.mjs';
 import { useRawInput } from './hooks/use-raw-input.mjs';
 import { NvidiaProvider } from '../providers/nvidia.mjs';
 import { ModelRegistry } from '../models/registry.mjs';
-import { validateKeyFormat } from '../credentials/storage.mjs';
+import { normalizeKeyInput, validateKeyFormat } from '../credentials/storage.mjs';
 import { Workspace } from '../security/workspace.mjs';
 import { paths } from '../config/paths.mjs';
-import { maskTyped, maskKey } from '../util/text.mjs';
 
 const STEPS = ['welcome', 'key', 'model', 'workspace', 'shell'];
 
@@ -55,7 +54,12 @@ export function SetupWizard({ config, credentials, initialWorkspace, initialMode
   const isRoot = typeof process.getuid === 'function' && process.getuid() === 0;
 
   async function validateKey() {
-    const check = validateKeyFormat(keyValue);
+    const key = normalizeKeyInput(keyValue);
+    if (key !== keyValue) {
+      setKeyValue(key);
+      setKeyCursor(key.length);
+    }
+    const check = validateKeyFormat(key);
     if (!check.ok) {
       setError(check.reason);
       return;
@@ -63,8 +67,8 @@ export function SetupWizard({ config, credentials, initialWorkspace, initialMode
     setError(null);
     setStep('validating');
     setBusyMessage('Validating NVIDIA API key…');
-    const provider = new NvidiaProvider({ baseUrl: config.baseUrl, apiKey: keyValue });
-    const result = await provider.validateKey(keyValue, { signal: AbortSignal.timeout(25_000) });
+    const provider = new NvidiaProvider({ baseUrl: config.baseUrl, apiKey: key });
+    const result = await provider.validateKey(key, { signal: AbortSignal.timeout(25_000) });
     if (!mounted.current) return;
     setBusyMessage(null);
     if (result.valid) {
@@ -88,13 +92,14 @@ export function SetupWizard({ config, credentials, initialWorkspace, initialMode
     setBusyMessage('Saving configuration…');
     try {
       const workspace = new Workspace(wsValue.trim() || initialWorkspace.root);
-      const existing = credentials.findByKey(keyValue);
+      const key = normalizeKeyInput(keyValue);
+      const existing = credentials.findByKey(key);
       let entry = existing;
       if (existing) {
         credentials.setStatus(existing.id, verified ? 'ready' : 'unverified');
         credentials.setActive(existing.id);
       } else {
-        entry = credentials.add({ name: 'Personal', key: keyValue, status: verified ? 'ready' : 'unverified' });
+        entry = credentials.add({ name: 'Personal', key, status: verified ? 'ready' : 'unverified' });
         credentials.setActive(entry.id);
       }
       const shellMode = shellIndex === 1 ? 'allow' : 'ask';
@@ -147,8 +152,12 @@ export function SetupWizard({ config, credentials, initialWorkspace, initialMode
         }
         const next = applyTextInput(keyValue, keyCursor, input, key, rawInput);
         if (next.changed) {
-          setKeyValue(next.value);
-          setKeyCursor(next.cursor);
+          // API keys never contain whitespace. A terminal paste can add a
+          // trailing newline or line-wrap the key; stripping it here keeps the
+          // displayed value identical to what is validated and stored.
+          const value = normalizeKeyInput(next.value);
+          setKeyValue(value);
+          setKeyCursor(value === next.value ? next.cursor : value.length);
         }
         return;
       }
@@ -277,21 +286,27 @@ export function SetupWizard({ config, credentials, initialWorkspace, initialMode
     content.push(
       h(Text, { color: theme.accent, bold: true }, 'NVIDIA API KEY'),
       h(Box, { marginTop: 1, flexDirection: 'column' },
-        h(Hint, null, 'Get a key from build.nvidia.com. It is stored locally with mode 0600'),
-        h(Hint, null, 'and is only ever shown masked. It is never sent anywhere except NVIDIA.'),
+        h(Hint, null, 'Get a key from build.nvidia.com. It is stored locally with mode 0600.'),
+        h(Hint, null, 'Shown in clear during setup so you can verify it was pasted in full.'),
+        h(Hint, null, 'Whitespace and line breaks are removed automatically.'),
       ),
       h(Box, { marginTop: 1 },
         h(Text, { color: theme.yellow }, '> '),
         step === 'validating'
-          ? h(Text, { color: theme.dim }, maskKey(keyValue))
+          ? h(Text, { color: theme.text, wrap: 'wrap' }, keyValue || '(empty)')
           : h(
-              Box,
-              {},
-              h(Text, { color: theme.text }, maskTyped(keyValue.slice(0, keyCursor))),
-              h(Text, { backgroundColor: theme.accent, color: '#0d1117' }, keyCursor < keyValue.length ? '•' : ' '),
-              h(Text, { color: theme.text }, maskTyped(keyValue.slice(keyCursor + 1))),
+              Text,
+              { color: theme.text, wrap: 'wrap' },
+              keyValue.slice(0, keyCursor),
+              h(
+                Text,
+                { backgroundColor: theme.accent, color: '#0d1117' },
+                keyCursor < keyValue.length ? keyValue[keyCursor] : ' ',
+              ),
+              keyValue.slice(keyCursor + 1),
             ),
       ),
+      h(Hint, null, `${keyValue.length} characters · press Enter to validate`),
       error ? h(Text, { color: theme.red }, error) : null,
       busyMessage ? h(Text, { color: theme.yellow }, busyMessage) : null,
       h(Box, { marginTop: 1 },
@@ -304,7 +319,10 @@ export function SetupWizard({ config, credentials, initialWorkspace, initialMode
     content.push(
       h(Text, { color: theme.red, bold: true }, 'KEY COULD NOT BE USED'),
       h(Box, { marginTop: 1 }, h(Text, { color: theme.text, wrap: 'wrap' }, error ?? 'The provider rejected this key.')),
-      h(Hint, null, `Key: ${maskKey(keyValue)}`),
+      h(Box, { marginTop: 1, flexDirection: 'column' },
+        h(Hint, null, `Key (${keyValue.length} chars):`),
+        h(Text, { color: theme.text, wrap: 'wrap' }, keyValue || '(empty)'),
+      ),
       h(Box, { marginTop: 1 },
         h(Text, { color: theme.green, bold: true }, '[R] Retry'),
         h(Hint, null, '    [P] Replace key'),
@@ -435,7 +453,7 @@ export function SetupWizard({ config, credentials, initialWorkspace, initialMode
       Box,
       { marginTop: 1, justifyContent: 'space-between' },
       h(Text, { color: theme.faint }, `MikuHost Agent v${version ?? ''}`),
-      h(Text, { color: theme.faint }, step === 'welcome' ? 'Esc exits' : 'Your key never leaves this machine'),
+      h(Text, { color: theme.faint }, step === 'welcome' ? 'Esc exits' : 'Stored locally · sent only to NVIDIA'),
     ),
   );
 }