verbalcoding 0.2.0

package/app-node/install_config.mjs

@@ -0,0 +1,263 @@
+import { languagePreset, normalizeLanguageKey } from './language_config.mjs';
+
+export const SUPPORTED_HARNESSES = [
+  'hermes',
+  'claude-code',
+  'claude',
+  'codex',
+  'gemini',
+  'opencode',
+  'openclaw',
+  'custom',
+];
+
+export const DEFAULT_DISCORD_BOT_PERMISSIONS = 277028604928;
+
+function clean(value, fallback = '') {
+  const v = value == null ? '' : String(value).trim();
+  return v || fallback;
+}
+
+export function normalizeInstallAnswers(input = {}) {
+  const harness = clean(input.harness || input.AGENT_BACKEND, 'hermes').toLowerCase();
+  const normalizedHarness = SUPPORTED_HARNESSES.includes(harness) ? harness : 'custom';
+  const language = normalizeLanguageKey(input.language || input.VOICE_LANGUAGE || input.WHISPER_CPP_LANGUAGE || input.STT_LANGUAGE || 'ko');
+  const preset = languagePreset(language);
+  const out = {
+    AGENT_BACKEND: normalizedHarness,
+    DISCORD_BOT_TOKEN: clean(input.discordBotToken || input.DISCORD_BOT_TOKEN),
+    DISCORD_ALLOWED_USERS: clean(input.allowedUsers || input.DISCORD_ALLOWED_USERS),
+    AUTO_JOIN_VOICE_CHANNELS: clean(input.autoJoinVoiceChannels || input.AUTO_JOIN_VOICE_CHANNELS, '일반,General,general'),
+    TRANSCRIPT_CHANNEL_ID: clean(input.transcriptChannelId || input.TRANSCRIPT_CHANNEL_ID),
+    TTS_BACKEND: ['edge', 'openvoice', 'speechswift', 'supertonic'].includes(clean(input.ttsBackend || input.TTS_BACKEND, 'edge').toLowerCase())
+      ? clean(input.ttsBackend || input.TTS_BACKEND, 'edge').toLowerCase()
+      : 'edge',
+    EDGE_TTS_COMMAND: clean(input.edgeTtsCommand || input.EDGE_TTS_COMMAND || input.TTS_EDGE_COMMAND, 'edge-tts'),
+    VOICE_LANGUAGE: clean(input.voiceLanguage || input.VOICE_LANGUAGE, preset.voiceLanguage),
+    WHISPER_CPP_LANGUAGE: clean(input.whisperLanguage || input.WHISPER_CPP_LANGUAGE || input.STT_LANGUAGE, preset.sttLanguage),
+    STT_LANGUAGE: clean(input.sttLanguage || input.STT_LANGUAGE || input.WHISPER_CPP_LANGUAGE, preset.sttLanguage),
+    TTS_VOICE: clean(input.ttsVoice || input.TTS_VOICE, preset.ttsVoice),
+    TTS_RATE: clean(input.ttsRate || input.TTS_RATE, '+10%'),
+    TTS_MAX_CHARS: clean(input.ttsMaxChars || input.TTS_MAX_CHARS, '495'),
+    TTS_VOLUME: clean(input.ttsVolume || input.TTS_VOLUME, '1.0'),
+    SUPERTONIC_COMMAND: clean(input.supertonicCommand || input.SUPERTONIC_COMMAND, 'supertonic'),
+    SUPERTONIC_VOICE: clean(input.supertonicVoice || input.SUPERTONIC_VOICE, 'M1'),
+    SUPERTONIC_LANGUAGE: clean(input.supertonicLanguage || input.SUPERTONIC_LANGUAGE, 'ko'),
+    SUPERTONIC_STEPS: clean(input.supertonicSteps || input.SUPERTONIC_STEPS, '2'),
+    SUPERTONIC_SPEED: clean(input.supertonicSpeed || input.SUPERTONIC_SPEED, '1.0'),
+    SUPERTONIC_MAX_CHUNK_LENGTH: clean(input.supertonicMaxChunkLength || input.SUPERTONIC_MAX_CHUNK_LENGTH, '300'),
+    SUPERTONIC_SILENCE_DURATION: clean(input.supertonicSilenceDuration || input.SUPERTONIC_SILENCE_DURATION, '0.15'),
+    SUPERTONIC_PROGRESS: input.supertonicProgress === true || input.SUPERTONIC_PROGRESS === '1' ? '1' : '0',
+    OPENVOICE_DIR: clean(input.openvoiceDir || input.OPENVOICE_DIR, './vendor/OpenVoice'),
+    OPENVOICE_VENV: clean(input.openvoiceVenv || input.OPENVOICE_VENV, './.venv-openvoice'),
+    OPENVOICE_REF_AUDIO: clean(input.openvoiceRefAudio || input.OPENVOICE_REF_AUDIO, './voice-samples/user-reference.wav'),
+    OPENVOICE_LANGUAGE: clean(input.openvoiceLanguage || input.OPENVOICE_LANGUAGE, 'KR'),
+    OPENVOICE_STYLE: clean(input.openvoiceStyle || input.OPENVOICE_STYLE, 'default'),
+    OPENVOICE_TIMEOUT_MS: clean(input.openvoiceTimeoutMs || input.OPENVOICE_TIMEOUT_MS, '90000'),
+    OPENVOICE_PROGRESS: input.openvoiceProgress === true || input.OPENVOICE_PROGRESS === '1' ? '1' : '0',
+    REQUIRE_WAKE_WORD: input.requireWakeWord === true || input.REQUIRE_WAKE_WORD === '1' ? '1' : '0',
+    MIN_UTTERANCE_SECONDS: clean(input.minUtteranceSeconds || input.MIN_UTTERANCE_SECONDS, '1.0'),
+    UTTERANCE_IDLE_MS: clean(input.utteranceIdleMs || input.UTTERANCE_IDLE_MS, '2000'),
+    HERMES_TASK_TIMEOUT_MS: clean(input.taskTimeoutMs || input.HERMES_TASK_TIMEOUT_MS, '0'),
+    HERMES_CHAT_TIMEOUT_MS: clean(input.chatTimeoutMs || input.HERMES_CHAT_TIMEOUT_MS, '45000'),
+    AGENT_VERBOSE_PROGRESS: input.verboseProgress === true || input.AGENT_VERBOSE_PROGRESS === '1' ? '1' : '0',
+    LATENCY_LOG_PATH: clean(input.latencyLogPath || input.LATENCY_LOG_PATH, './.logs/latency.jsonl'),
+  };
+  if (input.agentLabel || input.AGENT_LABEL) out.AGENT_LABEL = clean(input.agentLabel || input.AGENT_LABEL);
+  if (input.agentCommand || input.AGENT_COMMAND) out.AGENT_COMMAND = clean(input.agentCommand || input.AGENT_COMMAND);
+  return out;
+}
+
+function quoteEnv(value) {
+  return JSON.stringify(String(value ?? ''));
+}
+
+export function buildDiscordBotInviteUrl(input = {}) {
+  const clientId = clean(input.clientId || input.DISCORD_CLIENT_ID || input.applicationId || input.APPLICATION_ID);
+  if (!clientId) throw new Error('Discord application/client ID is required.');
+  if (!/^\d{15,25}$/.test(clientId)) throw new Error('Discord application/client ID must be a numeric snowflake.');
+  const permissions = clean(input.permissions || input.DISCORD_BOT_PERMISSIONS, String(DEFAULT_DISCORD_BOT_PERMISSIONS));
+  const url = new URL('https://discord.com/oauth2/authorize');
+  url.searchParams.set('client_id', clientId);
+  url.searchParams.set('permissions', permissions);
+  url.searchParams.set('scope', 'bot applications.commands');
+  const guildId = clean(input.guildId || input.DISCORD_GUILD_ID);
+  if (guildId) {
+    url.searchParams.set('guild_id', guildId);
+    url.searchParams.set('disable_guild_select', 'true');
+  }
+  return url.toString();
+}
+
+export function slugifyInstanceName(name) {
+  return String(name || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}_.-]+/gu, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 64) || 'default';
+}
+
+export function buildEnvFile(values = {}) {
+  const ordered = [
+    'DISCORD_BOT_TOKEN',
+    'DISCORD_ALLOWED_USERS',
+    'AUTO_JOIN_VOICE_CHANNELS',
+    'TRANSCRIPT_CHANNEL_ID',
+    'AGENT_BACKEND',
+    'AGENT_LABEL',
+    'AGENT_COMMAND',
+    'VOICE_LANGUAGE',
+    'WHISPER_CPP_LANGUAGE',
+    'STT_LANGUAGE',
+    'TTS_BACKEND',
+    'EDGE_TTS_COMMAND',
+    'TTS_VOICE',
+    'TTS_RATE',
+    'TTS_MAX_CHARS',
+    'TTS_VOLUME',
+    'SUPERTONIC_COMMAND',
+    'SUPERTONIC_VOICE',
+    'SUPERTONIC_LANGUAGE',
+    'SUPERTONIC_STEPS',
+    'SUPERTONIC_SPEED',
+    'SUPERTONIC_MAX_CHUNK_LENGTH',
+    'SUPERTONIC_SILENCE_DURATION',
+    'SUPERTONIC_PROGRESS',
+    'OPENVOICE_DIR',
+    'OPENVOICE_VENV',
+    'OPENVOICE_REF_AUDIO',
+    'OPENVOICE_LANGUAGE',
+    'OPENVOICE_STYLE',
+    'OPENVOICE_TIMEOUT_MS',
+    'OPENVOICE_PROGRESS',
+    'REQUIRE_WAKE_WORD',
+    'MIN_UTTERANCE_SECONDS',
+    'UTTERANCE_IDLE_MS',
+    'HERMES_TASK_TIMEOUT_MS',
+    'HERMES_CHAT_TIMEOUT_MS',
+    'AGENT_VERBOSE_PROGRESS',
+    'LATENCY_LOG_PATH',
+  ];
+  const lines = [
+    '# Generated by VerbalCoding installer.',
+    '# Secrets stay local; do not commit this file.',
+  ];
+  for (const key of ordered) {
+    if (values[key] == null || values[key] === '') continue;
+    lines.push(`${key}=${quoteEnv(values[key])}`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+export function normalizeInstanceAnswers(input = {}) {
+  const instanceNameRaw = clean(input.instanceName || input.INSTANCE_NAME, 'example');
+  const instanceName = slugifyInstanceName(instanceNameRaw);
+  const displayName = clean(input.displayName || input.agentLabel || input.AGENT_LABEL, instanceNameRaw);
+  const workdir = clean(input.workdir || input.AGENT_CWD || input.AGENT_WORKDIR, '');
+  const projectContext = clean(input.projectContext || input.AGENT_PROJECT_CONTEXT, `Project session: ${displayName}`);
+  const out = {
+    INSTANCE_NAME: instanceName,
+    DISCORD_TOKEN: clean(input.discordBotToken || input.DISCORD_TOKEN || input.DISCORD_BOT_TOKEN),
+    DISCORD_CLIENT_ID: clean(input.discordClientId || input.DISCORD_CLIENT_ID || input.applicationId || input.APPLICATION_ID),
+    DISCORD_ALLOWED_USERS: clean(input.allowedUsers || input.DISCORD_ALLOWED_USERS),
+    AUTO_JOIN_VOICE_CHANNELS: clean(input.autoJoinVoiceChannels || input.AUTO_JOIN_VOICE_CHANNELS, displayName),
+    TRANSCRIPT_CHANNEL_ID: clean(input.transcriptChannelId || input.TRANSCRIPT_CHANNEL_ID),
+    PROJECT_SESSIONS_FILE: clean(input.projectSessionsFile || input.PROJECT_SESSIONS_FILE, `config/project-sessions.${instanceName}.json`),
+    BRIDGE_LOG_PATH: clean(input.bridgeLogPath || input.BRIDGE_LOG_PATH, `/tmp/verbalcoding-${instanceName}.log`),
+    NODE_AUDIO_DEBUG_DIR: clean(input.nodeAudioDebugDir || input.NODE_AUDIO_DEBUG_DIR, `/tmp/verbalcoding-${instanceName}-debug`),
+    HERMES_SESSION_FILE: clean(input.hermesSessionFile || input.HERMES_SESSION_FILE, `.agent-sessions/hermes/${instanceName}.session`),
+    HERMES_HOME: clean(input.hermesHome || input.HERMES_HOME),
+    AGENT_LABEL: clean(input.agentLabel || input.AGENT_LABEL, `Hermes Agent · ${displayName}`),
+    AGENT_CWD: workdir,
+    AGENT_PROJECT_CONTEXT: projectContext,
+  };
+  return out;
+}
+
+export function buildInstanceEnvFile(values = {}) {
+  const ordered = [
+    'INSTANCE_NAME',
+    'DISCORD_TOKEN',
+    'DISCORD_CLIENT_ID',
+    'DISCORD_ALLOWED_USERS',
+    'AUTO_JOIN_VOICE_CHANNELS',
+    'TRANSCRIPT_CHANNEL_ID',
+    'PROJECT_SESSIONS_FILE',
+    'BRIDGE_LOG_PATH',
+    'NODE_AUDIO_DEBUG_DIR',
+    'HERMES_SESSION_FILE',
+    'HERMES_HOME',
+    'AGENT_LABEL',
+    'AGENT_CWD',
+    'AGENT_PROJECT_CONTEXT',
+  ];
+  const lines = [
+    '# Generated by `verbalcoding instance setup`.',
+    '# Secrets stay local; do not commit this file.',
+  ];
+  for (const key of ordered) {
+    if (values[key] == null || values[key] === '') continue;
+    lines.push(`${key}=${quoteEnv(values[key])}`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+export function renderInstanceSetupSummary(values = {}) {
+  const name = values.INSTANCE_NAME || 'example';
+  const inviteUrl = values.DISCORD_CLIENT_ID ? buildDiscordBotInviteUrl({ clientId: values.DISCORD_CLIENT_ID }) : '';
+  return [
+    `Configured VerbalCoding instance: ${name}`,
+    `Env file: instances/${name}.env`,
+    ...(inviteUrl ? ['', 'Discord bot invite URL:', `  ${inviteUrl}`] : ['', 'Discord bot invite URL: run `vc bot invite <client-id>` after creating the Discord application.']),
+    '',
+    'Next commands:',
+    '  vc doctor',
+    `  vc instance start ${name}`,
+    `  vc instance status ${name}`,
+    '',
+    `Voice channel: ${values.AUTO_JOIN_VOICE_CHANNELS || '(not set)'}`,
+    `Transcript target: ${values.TRANSCRIPT_CHANNEL_ID || '(not set)'}`,
+    `Log: ${values.BRIDGE_LOG_PATH || `/tmp/verbalcoding-${name}.log`}`,
+  ].join('\n');
+}
+
+export function parseKeyValueEnv(text) {
+  const out = {};
+  for (const raw of String(text || '').split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#') || !line.includes('=')) continue;
+    const idx = line.indexOf('=');
+    const key = line.slice(0, idx).trim().replace(/^export\s+/, '');
+    let value = line.slice(idx + 1).trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    try {
+      if (line.slice(idx + 1).trim().startsWith('"')) value = JSON.parse(line.slice(idx + 1).trim());
+    } catch {}
+    out[key] = value;
+  }
+  return out;
+}
+
+export function renderInstallSummary(values = {}) {
+  const backend = values.AGENT_BACKEND || 'hermes';
+  return [
+    `Configured Discord voice bridge for harness: ${backend}`,
+    '',
+    'Next commands:',
+    '  npm install -g .   # or ./scripts/install.sh to install the vc command',
+    '  vc doctor',
+    '  ./run.sh',
+    '',
+    'Legacy project-local equivalents still work:',
+    '  npm install',
+    '  npm run doctor',
+    '',
+    `Auto-join voice channels: ${values.AUTO_JOIN_VOICE_CHANNELS || '일반,General,general'}`,
+    `TTS backend: ${values.TTS_BACKEND || 'edge'}`,
+    `Verbose progress: ${values.AGENT_VERBOSE_PROGRESS === '1' ? 'on' : 'off'} (toggle later with !verbose on/off)`,
+    'Use !ask <text>, !session, !reset-session, !join, !leave, !verbose, !voice-test, and !sensitivity in Discord.',
+  ].join('\n');
+}

package/app-node/install_config.test.mjs

@@ -0,0 +1,205 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  DEFAULT_DISCORD_BOT_PERMISSIONS,
+  buildDiscordBotInviteUrl,
+  buildEnvFile,
+  buildInstanceEnvFile,
+  normalizeInstallAnswers,
+  normalizeInstanceAnswers,
+  parseKeyValueEnv,
+  renderInstallSummary,
+  renderInstanceSetupSummary,
+} from './install_config.mjs';
+
+test('buildDiscordBotInviteUrl creates bot invite with voice and text permissions', () => {
+  const url = buildDiscordBotInviteUrl({ clientId: '123456789012345678' });
+  const parsed = new URL(url);
+
+  assert.equal(parsed.origin, 'https://discord.com');
+  assert.equal(parsed.pathname, '/oauth2/authorize');
+  assert.equal(parsed.searchParams.get('client_id'), '123456789012345678');
+  assert.equal(parsed.searchParams.get('scope'), 'bot applications.commands');
+  assert.equal(parsed.searchParams.get('permissions'), String(DEFAULT_DISCORD_BOT_PERMISSIONS));
+});
+
+test('buildDiscordBotInviteUrl can pin a guild and disables guild selection', () => {
+  const url = buildDiscordBotInviteUrl({ clientId: '123456789012345678', guildId: '987654321098765432' });
+  const parsed = new URL(url);
+
+  assert.equal(parsed.searchParams.get('guild_id'), '987654321098765432');
+  assert.equal(parsed.searchParams.get('disable_guild_select'), 'true');
+});
+
+test('normalizeInstallAnswers maps supported harnesses to backend env', () => {
+  const answers = normalizeInstallAnswers({
+    harness: 'opencode',
+    discordBotToken: 'token-123',
+    allowedUsers: '111,222',
+    autoJoinVoiceChannels: '일반,General',
+    transcriptChannelId: '333',
+    language: 'en',
+    ttsVoice: '',
+    ttsRate: '',
+    requireWakeWord: false,
+  });
+
+  assert.equal(answers.AGENT_BACKEND, 'opencode');
+  assert.equal(answers.DISCORD_BOT_TOKEN, 'token-123');
+  assert.equal(answers.DISCORD_ALLOWED_USERS, '111,222');
+  assert.equal(answers.AUTO_JOIN_VOICE_CHANNELS, '일반,General');
+  assert.equal(answers.TRANSCRIPT_CHANNEL_ID, '333');
+  assert.equal(answers.TTS_BACKEND, 'edge');
+  assert.equal(answers.EDGE_TTS_COMMAND, 'edge-tts');
+  assert.equal(answers.VOICE_LANGUAGE, 'en');
+  assert.equal(answers.WHISPER_CPP_LANGUAGE, 'en');
+  assert.equal(answers.STT_LANGUAGE, 'en');
+  assert.equal(answers.TTS_VOICE, 'en-US-GuyNeural');
+  assert.equal(answers.TTS_RATE, '+10%');
+  assert.equal(answers.TTS_VOLUME, '1.0');
+  assert.equal(answers.SUPERTONIC_COMMAND, 'supertonic');
+  assert.equal(answers.SUPERTONIC_SPEED, '1.0');
+  assert.equal(answers.SUPERTONIC_LANGUAGE, 'ko');
+  assert.equal(answers.OPENVOICE_LANGUAGE, 'KR');
+  assert.equal(answers.REQUIRE_WAKE_WORD, '0');
+  assert.equal(answers.UTTERANCE_IDLE_MS, '2000');
+});
+
+test('buildEnvFile writes configurable CLI harness and Discord settings without comments leaking into values', () => {
+  const envText = buildEnvFile({
+    AGENT_BACKEND: 'custom',
+    AGENT_LABEL: 'My Harness',
+    AGENT_COMMAND: 'my-harness run --json',
+    VOICE_LANGUAGE: 'auto',
+    WHISPER_CPP_LANGUAGE: 'auto',
+    STT_LANGUAGE: 'auto',
+    TTS_BACKEND: 'supertonic',
+    EDGE_TTS_COMMAND: './.venv-tts/bin/edge-tts',
+    SUPERTONIC_VOICE: 'M4',
+    SUPERTONIC_STEPS: '3',
+    DISCORD_BOT_TOKEN: 'token-abc',
+    DISCORD_ALLOWED_USERS: '111',
+    AUTO_JOIN_VOICE_CHANNELS: '일반',
+    TRANSCRIPT_CHANNEL_ID: '222',
+    TTS_VOICE: 'ko-KR-SunHiNeural',
+    TTS_RATE: '+10%',
+    TTS_VOLUME: '1.6',
+    REQUIRE_WAKE_WORD: '0',
+    OPENVOICE_REF_AUDIO: './voice-samples/me.wav',
+  });
+  const parsed = parseKeyValueEnv(envText);
+
+  assert.equal(parsed.AGENT_BACKEND, 'custom');
+  assert.equal(parsed.AGENT_LABEL, 'My Harness');
+  assert.equal(parsed.AGENT_COMMAND, 'my-harness run --json');
+  assert.equal(parsed.TTS_BACKEND, 'supertonic');
+  assert.equal(parsed.EDGE_TTS_COMMAND, './.venv-tts/bin/edge-tts');
+  assert.equal(parsed.VOICE_LANGUAGE, 'auto');
+  assert.equal(parsed.WHISPER_CPP_LANGUAGE, 'auto');
+  assert.equal(parsed.STT_LANGUAGE, 'auto');
+  assert.equal(parsed.SUPERTONIC_VOICE, 'M4');
+  assert.equal(parsed.SUPERTONIC_STEPS, '3');
+  assert.equal(parsed.TTS_VOLUME, '1.6');
+  assert.equal(parsed.OPENVOICE_REF_AUDIO, './voice-samples/me.wav');
+  assert.equal(parsed.DISCORD_BOT_TOKEN, 'token-abc');
+  assert.equal(parsed.REQUIRE_WAKE_WORD, '0');
+});
+
+test('renderInstallSummary documents selected harness and next commands', () => {
+  const summary = renderInstallSummary({ AGENT_BACKEND: 'claude-code', AUTO_JOIN_VOICE_CHANNELS: '일반', TTS_BACKEND: 'openvoice' });
+
+  assert.match(summary, /claude-code/);
+  assert.match(summary, /npm install/);
+  assert.match(summary, /\.\/run\.sh/);
+  assert.match(summary, /openvoice/);
+  assert.match(summary, /!voice-test/);
+});
+
+test('normalizeInstanceAnswers derives isolated per-instance env values', () => {
+  const values = normalizeInstanceAnswers({
+    instanceName: 'LLM Wiki',
+    discordBotToken: 'token-instance',
+    discordClientId: '123456789012345678',
+    autoJoinVoiceChannels: 'LLM-Wiki',
+    transcriptChannelId: '123456789012345678',
+    workdir: '/path/to/my-project',
+    projectContext: 'LLM-Wiki graph context',
+    agentLabel: '',
+  });
+
+  assert.equal(values.INSTANCE_NAME, 'llm-wiki');
+  assert.equal(values.DISCORD_TOKEN, 'token-instance');
+  assert.equal(values.DISCORD_CLIENT_ID, '123456789012345678');
+  assert.equal(values.AUTO_JOIN_VOICE_CHANNELS, 'LLM-Wiki');
+  assert.equal(values.TRANSCRIPT_CHANNEL_ID, '123456789012345678');
+  assert.equal(values.PROJECT_SESSIONS_FILE, 'config/project-sessions.llm-wiki.json');
+  assert.equal(values.BRIDGE_LOG_PATH, '/tmp/verbalcoding-llm-wiki.log');
+  assert.equal(values.NODE_AUDIO_DEBUG_DIR, '/tmp/verbalcoding-llm-wiki-debug');
+  assert.equal(values.HERMES_SESSION_FILE, '.agent-sessions/hermes/llm-wiki.session');
+  assert.equal(values.AGENT_LABEL, 'Hermes Agent · LLM Wiki');
+  assert.equal(values.AGENT_CWD, '/path/to/my-project');
+  assert.equal(values.AGENT_PROJECT_CONTEXT, 'LLM-Wiki graph context');
+});
+
+test('buildInstanceEnvFile writes only local per-instance values with token redaction left to callers', () => {
+  const envText = buildInstanceEnvFile(normalizeInstanceAnswers({
+    instanceName: 'verbalcoding',
+    discordBotToken: 'token-vc',
+    autoJoinVoiceChannels: 'VerbalCoding',
+    transcriptChannelId: 'thread-1',
+    allowedUsers: '111,222',
+    discordClientId: '123456789012345678',
+  }));
+  const parsed = parseKeyValueEnv(envText);
+
+  assert.equal(parsed.INSTANCE_NAME, 'verbalcoding');
+  assert.equal(parsed.DISCORD_TOKEN, 'token-vc');
+  assert.equal(parsed.DISCORD_CLIENT_ID, '123456789012345678');
+  assert.equal(parsed.DISCORD_ALLOWED_USERS, '111,222');
+  assert.equal(parsed.AUTO_JOIN_VOICE_CHANNELS, 'VerbalCoding');
+  assert.equal(parsed.TRANSCRIPT_CHANNEL_ID, 'thread-1');
+  assert.equal(parsed.PROJECT_SESSIONS_FILE, 'config/project-sessions.verbalcoding.json');
+  assert.equal(parsed.AGENT_BACKEND, undefined);
+});
+
+test('normalizeInstanceAnswers surfaces HERMES_HOME when provided', () => {
+  const out = normalizeInstanceAnswers({
+    instanceName: 'llm-wiki',
+    discordBotToken: 'token',
+    autoJoinVoiceChannels: 'LLM-Wiki',
+    transcriptChannelId: '123',
+    workdir: '/projects/llm-wiki',
+    projectContext: 'LLM-Wiki agent',
+    hermesHome: '/home/you/.hermes/profiles/my-project',
+  });
+  assert.equal(out.HERMES_HOME, '/home/you/.hermes/profiles/my-project');
+});
+
+test('buildInstanceEnvFile emits HERMES_HOME after HERMES_SESSION_FILE', () => {
+  const text = buildInstanceEnvFile({
+    INSTANCE_NAME: 'llm-wiki',
+    DISCORD_TOKEN: 'token',
+    HERMES_SESSION_FILE: '.agent-sessions/hermes/llm-wiki.session',
+    HERMES_HOME: '/home/you/.hermes/profiles/my-project',
+    AGENT_LABEL: 'Hermes · llm-wiki',
+    AGENT_CWD: '/projects/llm-wiki',
+  });
+  const lines = text.split('\n');
+  const sessionIdx = lines.findIndex(l => l.startsWith('HERMES_SESSION_FILE='));
+  const homeIdx = lines.findIndex(l => l.startsWith('HERMES_HOME='));
+  assert.ok(sessionIdx >= 0 && homeIdx === sessionIdx + 1, `expected HERMES_HOME directly after HERMES_SESSION_FILE; got lines:\n${text}`);
+  assert.match(text, /HERMES_HOME="\/home\/you\/\.hermes\/profiles\/my-project"/);
+});
+
+test('renderInstanceSetupSummary points users at installed vc commands, not npm script wrappers or manual editing', () => {
+  const summary = renderInstanceSetupSummary({ INSTANCE_NAME: 'llm-wiki', DISCORD_CLIENT_ID: '123456789012345678', BRIDGE_LOG_PATH: '/tmp/verbalcoding-llm-wiki.log' });
+
+  assert.match(summary, /instances\/llm-wiki\.env/);
+  assert.match(summary, /vc instance start llm-wiki/);
+  assert.match(summary, /vc instance status llm-wiki/);
+  assert.match(summary, /vc doctor/);
+  assert.match(summary, /Discord bot invite URL:/);
+  assert.match(summary, /client_id=123456789012345678/);
+  assert.doesNotMatch(summary, /npm run vc/);
+});

package/app-node/instance_doctor.mjs

@@ -0,0 +1,137 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { listInstanceEnvFiles, instanceNameFromEnvPath, readInstanceEnv } from './instances.mjs';
+
+export function tokenFingerprint(token) {
+  return crypto.createHash('sha256').update(String(token)).digest('hex').slice(0, 12);
+}
+
+function readProfileTerminalCwdFromConfig(dir, fsDep = fs) {
+  try {
+    const text = fsDep.readFileSync(path.join(dir, 'config.yaml'), 'utf8');
+    const lines = text.split(/\r?\n/);
+    let inTerminal = false;
+    for (const line of lines) {
+      if (/^terminal:\s*$/.test(line)) {
+        inTerminal = true;
+        continue;
+      }
+      if (inTerminal) {
+        if (/^\S/.test(line)) break;
+        const m = line.match(/^\s+cwd:\s*"?([^"\n]+?)"?\s*$/);
+        if (m) return m[1].trim();
+      }
+    }
+    return '';
+  } catch {
+    return '';
+  }
+}
+
+function effectiveInstanceValue(root, instance, key) {
+  const value = String(instance.env[key] || '').trim();
+  if (value) return value;
+  if (key === 'PROJECT_SESSIONS_FILE') return path.join(root, 'config', 'project-sessions.json');
+  if (key === 'BRIDGE_LOG_PATH') return `/tmp/verbalcoding-${instance.name}.log`;
+  if (key === 'NODE_AUDIO_DEBUG_DIR') return '/tmp/verbalcoding-node-debug';
+  if (key === 'HERMES_SESSION_FILE') return path.join(root, '.verbalcoding-session');
+  return '';
+}
+
+function addCollisionIssues({ root, instances, key, messagePrefix }) {
+  const buckets = new Map();
+  for (const instance of instances) {
+    const value = effectiveInstanceValue(root, instance, key);
+    if (!value) continue;
+    const normalized = key.endsWith('FILE') || key.endsWith('PATH') || key.endsWith('DIR')
+      ? path.normalize(value)
+      : value;
+    if (!buckets.has(normalized)) buckets.set(normalized, []);
+    buckets.get(normalized).push(instance.name);
+  }
+  const issues = [];
+  for (const [value, names] of buckets.entries()) {
+    if (names.length > 1) {
+      issues.push(`${messagePrefix} ${key} collision: ${names.join(', ')} -> ${value}`);
+    }
+  }
+  return { issues };
+}
+
+export function checkInstanceConfigs(root, options = {}) {
+  const instancesDir = options.instancesDir || path.join(root, 'instances');
+  const envFiles = listInstanceEnvFiles(instancesDir);
+  const instances = envFiles.map(envPath => ({
+    name: instanceNameFromEnvPath(envPath),
+    envPath,
+    env: readInstanceEnv(envPath),
+  }));
+  const errors = [];
+  const warnings = [];
+
+  for (const instance of instances) {
+    const token = String(instance.env.DISCORD_BOT_TOKEN || instance.env.DISCORD_TOKEN || '').trim();
+    if (!token || /^replace/i.test(token)) {
+      errors.push(`${instance.name}: missing DISCORD_TOKEN or DISCORD_BOT_TOKEN`);
+    }
+    if (!String(instance.env.AUTO_JOIN_VOICE_CHANNELS || '').trim()) {
+      errors.push(`${instance.name}: missing AUTO_JOIN_VOICE_CHANNELS`);
+    }
+    if (!String(instance.env.TRANSCRIPT_CHANNEL_ID || '').trim()) {
+      errors.push(`${instance.name}: missing TRANSCRIPT_CHANNEL_ID`);
+    }
+  }
+
+  const tokenBuckets = new Map();
+  for (const instance of instances) {
+    const token = String(instance.env.DISCORD_BOT_TOKEN || instance.env.DISCORD_TOKEN || '').trim();
+    if (!token || /^replace/i.test(token)) continue;
+    const fp = tokenFingerprint(token);
+    if (!tokenBuckets.has(fp)) tokenBuckets.set(fp, []);
+    tokenBuckets.get(fp).push(instance.name);
+  }
+  for (const [fp, names] of tokenBuckets.entries()) {
+    if (names.length > 1) {
+      errors.push(`duplicate Discord token fingerprint ${fp}: ${names.join(', ')}`);
+    }
+  }
+
+  for (const key of ['PROJECT_SESSIONS_FILE', 'BRIDGE_LOG_PATH', 'NODE_AUDIO_DEBUG_DIR']) {
+    const { issues } = addCollisionIssues({ root, instances, key, messagePrefix: 'instance' });
+    errors.push(...issues);
+  }
+  const { issues: sessionWarnings } = addCollisionIssues({ root, instances, key: 'HERMES_SESSION_FILE', messagePrefix: 'instance' });
+  warnings.push(...sessionWarnings);
+
+  const readTerminalCwd = options.readTerminalCwd || (dir => readProfileTerminalCwdFromConfig(dir));
+  for (const instance of instances) {
+    const home = String(instance.env.HERMES_HOME || '').trim();
+    if (!home) continue;
+    if (!fs.existsSync(path.join(home, 'config.yaml'))) {
+      warnings.push(`${instance.name}: HERMES_HOME points at ${home} which is missing; vc instance start will create it`);
+      continue;
+    }
+    const profileCwd = readTerminalCwd(home);
+    const agentCwd = String(instance.env.AGENT_CWD || '').trim();
+    if (profileCwd && agentCwd && profileCwd !== agentCwd) {
+      errors.push(`${instance.name}: profile terminal.cwd (${profileCwd}) does not match AGENT_CWD (${agentCwd}); re-run vc instance setup to reconcile`);
+    }
+  }
+
+  return { errors, warnings, instances: instances.map(({ name, envPath }) => ({ name, envPath })) };
+}
+
+export function formatInstanceDoctor(result) {
+  const lines = [];
+  if (result.instances.length === 0) {
+    lines.push('• No per-instance env files found in instances/*.env');
+  } else {
+    lines.push(`• Instance env files: ${result.instances.map(i => i.name).join(', ')}`);
+  }
+  for (const error of result.errors) lines.push(`✗ ${error}`);
+  for (const warning of result.warnings) lines.push(`• Warning: ${warning}`);
+  if (result.errors.length === 0) lines.push('✓ Instance configuration checks passed');
+  return lines;
+}