@fastagent-sh/voicenote 0.18.4 → 0.18.6

package/README.md

@@ -158,6 +158,7 @@ vn run --latest                 # process only the latest valid recording
 vn run --latest --force         # re-run the latest one
 vn run --pdf                    # additionally render a PDF after notes
 vn run --dry-run                # print the plan only
+vn run /path/to/audio.m4a       # process one file by path (skips the scan, ignores age/size/duration filters)
 vn list                         # list this month's notes
 vn list --month 2026-05         # specific month
 vn last                         # print the latest processing summary
@@ -194,7 +195,9 @@ The install script writes an editable template:
 }
 ```
 
-Changes take effect on the next `vn run`. A legacy `~/.config/voicenote/speakers.json` is still read as a compatibility fallback.
+Changes take effect on the next `vn run`. Config values and unquoted/double-quoted `.zshrc` exports support simple `$VAR` / `${VAR}` references to other settings and `$HOME`. Single-quoted shell values stay literal. Shell commands are never executed. Runtime references honor inherited environment values; scheduler comparisons resolve from files alone.
+
+A legacy `~/.config/voicenote/speakers.json` is still read as a compatibility fallback.
 
 ## Workflow
 
@@ -237,7 +240,7 @@ The LaunchAgent invokes `vn run` every 60 seconds. It skips safely when no recor
 
 > Config changes (`config.json` or `~/.zshrc`) are picked up automatically by the background agent on its next run — no reinstall needed. The plist only snapshots real environment variables and pi's absolute path: **after changing `VOICENOTE_PI_BIN`, re-run `vn install-launch-agent` and reload** (`vn upgrade` regenerates the plist automatically). If pi is not signed in or ASR is not configured, the agent skips processing instead of burning ASR spend.
 >
-> Exception: if you `export http_proxy=...` directly in your shell (instead of using `LOCAL_PROXY_HOST`) and then run `vn install-launch-agent`, that real env value is snapshotted into the plist and keeps overriding later `LOCAL_PROXY_HOST` changes; re-run `vn install-launch-agent` to clear it. Prefer `LOCAL_PROXY_HOST`/`LOCAL_PROXY_PORT` for proxy configuration.
+> Proxy values that match the file configuration, including expanded variable references, are not embedded and produce no override warning. Values supplied only by the shell, or differing from the files, are embedded as explicit overrides. To clear an unwanted override, update or unset the shell variable, then run `vn install-launch-agent --load`. Prefer `LOCAL_PROXY_HOST`/`LOCAL_PROXY_PORT` in `config.json` for proxy configuration.
 
 Logs:
 

package/README.zh-CN.md

@@ -138,6 +138,7 @@ vn run --latest                 # 只处理最新有效录音
 vn run --latest --force         # 重跑最新条
 vn run --pdf                    # 生成纪要后额外渲染 PDF
 vn run --dry-run                # 仅列出计划
+vn run /path/to/audio.m4a       # 直接处理单个文件(不扫描目录, 不套用时长/大小/时效过滤)
 vn list                         # 列出本月笔记
 vn list --month 2026-05         # 指定月份
 vn last                         # 打印最新处理摘要

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastagent-sh/voicenote",
-  "version": "0.18.4",
+  "version": "0.18.6",
   "description": "Voice recordings → diarized transcripts → integrated semantic Markdown notes. Currently optimized for the PHILIPS VTR6500 recorder, but the workflow is generic.",
   "type": "module",
   "license": "MIT",

package/src/cli.ts

@@ -8,12 +8,12 @@ import { createHash, createHmac, randomUUID } from 'node:crypto'
 import { appendFile, chmod, mkdir, readFile, writeFile, copyFile, rename, unlink, stat, readdir, rm } from 'node:fs/promises'
 import { existsSync, readFileSync, readdirSync, mkdirSync, writeFileSync, appendFileSync, openSync, closeSync, statSync, readSync, unlinkSync, renameSync } from 'node:fs'
 import { dlopen, FFIType, suffix } from 'bun:ffi'
-import { basename, dirname, extname, join } from 'node:path'
+import { basename, dirname, extname, join, resolve } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { spawn, spawnSync } from 'node:child_process'
 import os from 'node:os'
 
-const VERSION = '0.18.4'
+const VERSION = '0.18.6'
 const LAUNCH_AGENT_LABEL = 'sh.fastagent.voicenote'
 const LAUNCH_AGENT_LABEL_LEGACY = 'com.kid7st.voicenote' // pre-fastagent installs; cleaned up on install
 const TASK_NAME = 'VoiceNote'   // Windows Task Scheduler name (mac uses LAUNCH_AGENT_LABEL)
@@ -209,20 +209,21 @@ function applyDerivedProxy(): void {
   }
 }
 
-// What the config files would provide for each ENV_KEY, independent of this
-// process's environment. Primary source is ~/.config/voicenote/config.json
+// File values for each ENV_KEY. Hydration passes the current environment for
+// variable references; scheduler comparison uses files alone. Primary source is
+// ~/.config/voicenote/config.json
 // (ENV-style runtime keys at the top level; identity under `speakers`); the
 // legacy fallback is `export KEY=...` lines in ~/.zshrc, for CLI installs
 // that predate config.json. Precedence/expansion logic lives in envConfig.ts
 // (pure + tested). Two consumers: loadEnvConfig() hydrates these into
 // process.env for keys the real environment doesn't set, and launchAgentEnv()
 // uses them to decide which values are recoverable at run time.
-function fileProvidedEnv(): Record<string, string> {
+function fileProvidedEnv(environment: Record<string, string | undefined> = {}): Record<string, string> {
   const data = loadJsonSync<Record<string, unknown>>(CONFIG_ENV_PATH, {})
   let zshrc: string | null = null
   const zshrcPath = join(os.homedir(), '.zshrc')
   if (existsSync(zshrcPath)) { try { zshrc = readFileSync(zshrcPath, 'utf8') } catch { zshrc = null } }
-  return parseFileEnv(ENV_KEYS, data, zshrc, os.homedir())
+  return parseFileEnv(ENV_KEYS, data, zshrc, os.homedir(), environment)
 }
 
 let envConfigLoaded = false
@@ -231,7 +232,7 @@ function loadEnvConfig(): void {
   envConfigLoaded = true
   // Precedence: process.env > config.json (GUI) > ~/.zshrc (legacy); an
   // explicit empty string in the environment is never overridden.
-  const toApply = hydrateFromFileEnv(ENV_KEYS, process.env, fileProvidedEnv())
+  const toApply = hydrateFromFileEnv(ENV_KEYS, process.env, fileProvidedEnv(process.env))
   for (const [key, v] of Object.entries(toApply)) { process.env[key] = v; hydratedEnvKeys.add(key) }
   // Derive http_proxy etc. from LOCAL_PROXY_HOST/PORT regardless of source, and
   // always keep Volcano hosts on NO_PROXY. (Runs even with no config files.)
@@ -799,6 +800,18 @@ function isCandidateFile(path: string): boolean {
  * treating a half-read device as authoritative would delete live queue entries
  * along with their retry counters.
  */
+async function toRecording(file: string): Promise<Recording> {
+  const st = await stat(file)
+  return {
+    sourcePath: file,
+    sizeBytes: st.size,
+    modifiedAt: st.mtime.toISOString(),
+    durationSeconds: await ffprobeDuration(file),
+    sourceId: await sourceIdFor(file),
+    recordedAt: parseRecordedAt(file),
+  }
+}
+
 async function scanRecordings(config: Config): Promise<{ recordings: Recording[]; complete: boolean }> {
   if (!existsSync(config.recordDir)) return { recordings: [], complete: false }
   const recordings: Recording[] = []
@@ -812,14 +825,7 @@ async function scanRecordings(config: Config): Promise<{ recordings: Recording[]
       if (!st) { complete = false; continue }
       if (!st.isFile()) continue
       try {
-        recordings.push({
-          sourcePath: file,
-          sizeBytes: st.size,
-          modifiedAt: st.mtime.toISOString(),
-          durationSeconds: await ffprobeDuration(file),
-          sourceId: await sourceIdFor(file),
-          recordedAt: parseRecordedAt(file),
-        })
+        recordings.push(await toRecording(file))
       } catch (e) { complete = false; warnSideEffect(`read ${basename(file)} during scan`, e) }
     }
   } catch (e) {
@@ -2060,9 +2066,10 @@ function pidAlive(pid: number): boolean {
   try { process.kill(pid, 0); return true } catch (e: any) { return e?.code === 'EPERM' }
 }
 
-async function runPipeline(opts: any): Promise<void> {
+async function runPipeline(file: string | undefined, opts: any): Promise<void> {
   wireDailyLog()
   const config = getConfig()
+  opts = { ...opts, file }
   const lock = await acquireRunLock()
   if (!lock) {
     console.log('voicenote pipeline already running; skip')
@@ -2088,21 +2095,30 @@ async function runPipelineLocked(config: Config, opts: any): Promise<void> {
   const interrupted = reconcileInterrupted(store.jobs, nowIso())
   if (interrupted.length) console.log(`Reclaimed ${interrupted.length} job(s) left running by an interrupted run: ${interrupted.slice(0, 3).map(j => j.name).join(', ')}`)
 
-  if (!existsSync(config.recordDir)) {
+  // Explicit file: process exactly that path, wherever it lives. Nothing is
+  // scanned, so the listing is never "complete" (no pruning), and the recorder
+  // filters (age/size/duration) don't apply — the user named the file.
+  const single = opts.file ? resolve(String(opts.file)) : null
+  if (single && !statSync(single, { throwIfNoEntry: false })?.isFile()) throw new Error(`Not a file: ${single}`)
+  if (!single && !existsSync(config.recordDir)) {
     if (shouldLogIdleStatus(`missing:${config.recordDir}`)) {
       console.log(`Idle: recorder not mounted or record dir missing: ${config.recordDir} (repeated idle logs suppressed for 30m)`)
     }
     return
   }
-  const { recordings, complete: scanComplete } = await scanRecordings(config)
+  const { recordings, complete: scanComplete } = single
+    ? { recordings: [await toRecording(single)], complete: false }
+    : await scanRecordings(config)
   const mode = normalizeRunMode(opts)
   const force = Boolean(opts.force)
   const eligible: Recording[] = []
   const skipCounts: Record<string, number> = {}
   const skipSamples: Record<string, string[]> = {}
-  const verboseSkips = Boolean(opts.verbose || opts.dryRun)
+  // An explicitly named file that gets skipped must say why, not fall into the
+  // idle-suppressed silence meant for the 60s scheduler tick.
+  const verboseSkips = Boolean(opts.verbose || opts.dryRun || single)
   const seen = new Set<string>()
-  const limits = limitsOf(config)
+  const limits = single ? { maxAgeHours: 0, minBytes: 0, minDurationSeconds: 0 } : limitsOf(config)
   for (const rec of recordings) {
     seen.add(rec.sourceId)
     const entry = recordFor(store, rec)
@@ -2116,7 +2132,7 @@ async function runPipelineLocked(config: Config, opts: any): Promise<void> {
   // Only prune against a listing we believe to be complete: if the recorder went
   // away mid-glob the scan is partial, and pruning would wipe live queue entries
   // (they'd return on the next scan, but their retry counters would not).
-  const dropped = pruneUnseen(store.jobs, seen, scanComplete && existsSync(config.recordDir))
+  const dropped = pruneUnseen(store.jobs, seen, !single && scanComplete && existsSync(config.recordDir))
   // The only routine path that deletes state — never do it silently.
   if (dropped.length) console.log(`Forgot ${dropped.length} record(s) whose source is no longer on the recorder: ${dropped.slice(0, 3).map(j => j.name).join(', ')}${dropped.length > 3 ? `…(+${dropped.length - 3})` : ''}`)
   const skipSummary = Object.entries(skipCounts).map(([reason, count]) => `${reason}=${count}`).join(', ') || 'none'
@@ -2201,7 +2217,7 @@ async function runPipelineLocked(config: Config, opts: any): Promise<void> {
     }
     // Whole recorder went away — every remaining target would fail the same way
     // and churn ASR-free but noisy retries. Stop and let the next run rescan.
-    if (!existsSync(config.recordDir)) {
+    if (!single && !existsSync(config.recordDir)) {
       console.error(`Recorder disappeared mid-run (${config.recordDir}); stopping. Remaining recordings stay queued.`)
       break
     }
@@ -2250,12 +2266,6 @@ async function launchAgentEnv(): Promise<Record<string, string>> {
   // about: it may equally be a stale shell session, and it will keep
   // overriding config edits until the scheduler is reinstalled.
   //
-  // Known blind spot: the matrix compares each key against its OWN file value,
-  // so it can't see cross-key derivations. A real-env http_proxy is embedded
-  // as-is and will shadow a GUI edit to LOCAL_PROXY_HOST (different key name)
-  // until reinstall. Only no_proxy is special-cased (originals below) because
-  // WE synthesize it; http_proxy from a user's shell is left as a real value.
-  //
   // no_proxy/NO_PROXY carry a volcano-hosts merge we added; substitute the
   // pre-merge real-env original (or drop it entirely if we synthesized the
   // whole value) so the scheduler never freezes our merge over config edits.
@@ -2265,7 +2275,7 @@ async function launchAgentEnv(): Promise<Record<string, string>> {
   const { embed, frozenOverrides } = envKeysToEmbed(ENV_KEYS, embedEnv, hydratedEnvKeys, fileEnv)
   Object.assign(env, embed)
   for (const k of frozenOverrides) {
-    console.error(`Warning: environment ${k} differs from the config file value; the environment value is snapshotted into the scheduler and will override config edits until you re-run \`vn install-launch-agent\`.`)
+    console.error(`Warning: environment ${k} overrides the config file. Update or unset it, then re-run \`vn install-launch-agent --load\` to apply the intended value.`)
   }
   // Embed pi's ABSOLUTE path so launchd resolves it regardless of the fixed plist
   // PATH (npm global bin can live outside it under nvm / custom prefixes). Resolve
@@ -2907,7 +2917,7 @@ async function dispatchServe(req: any, send: (o: unknown) => void): Promise<void
         // request timeout can't misread it as a wedged engine. Progress shows
         // via the jobs poll; acquireRunLock inside runPipeline dedupes against
         // the scheduler tick and a double-click.
-        void runPipeline({}).catch(e => console.error('manual run failed:', e?.message || e))
+        void runPipeline(undefined, {}).catch(e => console.error('manual run failed:', e?.message || e))
         result = { started: true }
         break
       }
@@ -2991,7 +3001,7 @@ async function serve(): Promise<void> {
 
 const cli = cac('vn')
 
-cli.command('run', 'Scan recorder and process recordings (Volcano ASR + pi notes)')
+cli.command('run [file]', 'Scan recorder and process recordings, or process one audio file by path (Volcano ASR + pi notes)')
   .option('--mode <mode>', 'Output mode: notes (default) | transcript', { default: 'notes' })
   .option('--latest', 'Only process newest eligible recording')
   .option('--force', 'Reprocess already processed recordings')

package/src/envConfig.ts

@@ -1,8 +1,9 @@
 // Pure logic behind cli.ts's env-config provenance. Extracted (no fs, no
 // process.env) so its invariants are testable — see envConfig.test.ts:
 //
-// 1. File precedence: config.json (GUI) wins over ~/.zshrc (legacy CLI);
-//    $HOME tokens are expanded in both.
+// 1. File precedence: config.json (GUI) wins over ~/.zshrc (legacy CLI).
+//    Simple $VAR/${VAR} references resolve from these values without running
+//    shell code; runtime hydration may also use inherited environment values.
 // 2. Hydration: only keys the real environment does NOT set are filled from
 //    files — an explicit empty string in the environment (e.g.
 //    VOICENOTE_PI_SUMMARY_TOOLS="") counts as set and is never overridden.
@@ -17,28 +18,46 @@
 //    warn: it may equally be a stale shell session shadowing a fresh config
 //    edit, and it will keep overriding until the scheduler is reinstalled.
 
-/** File-provided values for `keys`: config.json over zshrc, $HOME expanded. */
+/** Omit `environment` when checking which values files can reproduce on their own. */
 export function parseFileEnv(
   keys: readonly string[],
   configData: Record<string, unknown>,
   zshrcContent: string | null,
   home: string,
+  environment: Record<string, string | undefined> = {},
 ): Record<string, string> {
-  const out: Record<string, string> = {}
-  const expand = (v: string) => v.replace(/\$\{?HOME\}?/g, home)
+  const raw = new Map<string, string>()
+  const literal = new Set<string>()
   for (const key of keys) {
     const v = configData[key]
-    if (typeof v === 'string') out[key] = expand(v)
+    if (typeof v === 'string') { raw.set(key, v); continue }
+    const pattern = new RegExp(`(?:^|\\n)\\s*export\\s+${key}=(?:"([^"]*)"|'([^']*)'|([^\\s"'#]+))`)
+    const match = zshrcContent?.match(pattern)
+    const value = match?.slice(1).find(v => v !== undefined)
+    if (value !== undefined) raw.set(key, value)
+    if (match?.[2] !== undefined) literal.add(key)
   }
-  if (zshrcContent !== null) {
-    for (const key of keys) {
-      if (out[key] !== undefined) continue // config.json wins
-      const pattern = new RegExp(`(?:^|\\n)\\s*export\\s+${key}=(?:"([^"]*)"|'([^']*)'|([^\\s"'#]+))`)
-      const value = zshrcContent.match(pattern)?.slice(1).find(v => v !== undefined)
-      if (value !== undefined) out[key] = expand(value)
-    }
+  const resolved = new Map<string, string>()
+  const visiting = new Set<string>()
+  const resolve = (key: string): string => {
+    const cached = resolved.get(key)
+    if (cached !== undefined) return cached
+    if (visiting.has(key)) throw new Error(`Circular config variable reference: ${key}`)
+    visiting.add(key)
+    const value = raw.get(key)!
+    const expanded = literal.has(key) ? value : value.replace(/\\(\$)|\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))/g, (token, escaped, braced, bare) => {
+      if (escaped) return escaped
+      const ref = braced || bare
+      if (ref === 'HOME') return home
+      // Unknown references stay literal, so they cannot look recoverable from files.
+      if (Object.hasOwn(environment, ref) && environment[ref] !== undefined) return environment[ref]!
+      return raw.has(ref) ? resolve(ref) : token
+    })
+    visiting.delete(key)
+    resolved.set(key, expanded)
+    return expanded
   }
-  return out
+  return Object.fromEntries(Array.from(raw.keys(), key => [key, resolve(key)]))
 }
 
 /** Which keys to copy from fileEnv into an environment (invariant 2). */