@navai/voice-frontend 0.1.0 → 0.1.1

package/README.md

@@ -6,6 +6,7 @@ Frontend helpers to integrate OpenAI Realtime voice without creating custom base
 
 - Route resolution helpers.
 - Optional dynamic frontend function loader.
+- `useWebVoiceAgent(...)` to bootstrap voice session from React with backend + frontend tools.
 - `buildNavaiAgent(...)` with built-in tools:
   - `navigate_to`
   - `execute_app_function`
@@ -23,6 +24,21 @@ Frontend helpers to integrate OpenAI Realtime voice without creating custom base
 npm install @navai/voice-frontend @openai/agents zod
 ```
 
+Peer dependency for hooks:
+
+```bash
+npm install react
+```
+
+When installed from npm, this package auto-configures missing scripts in the consumer `package.json`:
+
+- `generate:module-loaders` -> `navai-generate-web-loaders`
+- `predev`, `prebuild`, `pretypecheck`, `prelint` -> `npm run generate:module-loaders`
+
+It only adds missing entries and never overwrites existing scripts.
+To disable auto-setup, set `NAVAI_SKIP_AUTO_SETUP=1` (or `NAVAI_SKIP_FRONTEND_AUTO_SETUP=1`) during install.
+To run setup manually later, use `npx navai-setup-voice-frontend`.
+
 ## Expected app inputs
 
 1. Route data in `src/ai/routes.ts` (or any array compatible with `NavaiRoute[]`).
@@ -49,6 +65,21 @@ const { agent } = await buildNavaiAgent({
 
 Then use `agent` with `RealtimeSession` from `@openai/agents/realtime`.
 
+## React hook usage
+
+```ts
+import { useWebVoiceAgent } from "@navai/voice-frontend";
+import { NAVAI_WEB_MODULE_LOADERS } from "./ai/generated-module-loaders";
+import { NAVAI_ROUTE_ITEMS } from "./ai/routes";
+
+const agent = useWebVoiceAgent({
+  navigate: (path) => routerNavigate(path),
+  moduleLoaders: NAVAI_WEB_MODULE_LOADERS,
+  defaultRoutes: NAVAI_ROUTE_ITEMS,
+  env: import.meta.env as Record<string, string | undefined>
+});
+```
+
 ## Optional dynamic frontend functions (bundler adapter)
 
 If your bundler can provide module loaders, you can add local frontend functions too.
@@ -56,9 +87,9 @@ If your bundler can provide module loaders, you can add local frontend functions
 ```ts
 import { resolveNavaiFrontendRuntimeConfig } from "@navai/voice-frontend";
 
-// Vite adapter example:
+// Vite adapter example (folder-scoped):
 const runtime = await resolveNavaiFrontendRuntimeConfig({
-  moduleLoaders: import.meta.glob(["/src/**/*.{ts,js}", "!/src/ai/routes.ts"]),
+  moduleLoaders: import.meta.glob(["/src/ai/functions-modules/**/*.{ts,js}"]),
   defaultRoutes: NAVAI_ROUTE_ITEMS
 });
 ```

package/bin/auto-configure-consumer.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+
+const PACKAGE_NAME = "@navai/voice-frontend";
+const SKIP_ENV_KEYS = ["NAVAI_SKIP_AUTO_SETUP", "NAVAI_SKIP_FRONTEND_AUTO_SETUP"];
+const SCRIPT_ENTRIES = [
+  ["generate:module-loaders", "navai-generate-web-loaders"],
+  ["predev", "npm run generate:module-loaders"],
+  ["prebuild", "npm run generate:module-loaders"],
+  ["pretypecheck", "npm run generate:module-loaders"],
+  ["prelint", "npm run generate:module-loaders"]
+];
+
+function shouldSkipSetup() {
+  for (const envKey of SKIP_ENV_KEYS) {
+    const value = process.env[envKey];
+    if (!value) {
+      continue;
+    }
+
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "1" || normalized === "true" || normalized === "yes") {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function getConsumerRoot() {
+  const initCwd = process.env.INIT_CWD;
+  if (typeof initCwd === "string" && initCwd.trim().length > 0) {
+    return path.resolve(initCwd);
+  }
+
+  return process.cwd();
+}
+
+function hasPackageDependency(packageJson, packageName) {
+  const dependencyKeys = ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"];
+
+  for (const key of dependencyKeys) {
+    const block = packageJson[key];
+    if (!block || typeof block !== "object") {
+      continue;
+    }
+
+    if (typeof block[packageName] === "string") {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+async function readJson(filePath) {
+  try {
+    const raw = await readFile(filePath, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+async function main() {
+  if (shouldSkipSetup()) {
+    return;
+  }
+
+  const consumerRoot = getConsumerRoot();
+  const packageJsonPath = path.resolve(consumerRoot, "package.json");
+  const packageJson = await readJson(packageJsonPath);
+  if (!packageJson || typeof packageJson !== "object") {
+    return;
+  }
+
+  if (!hasPackageDependency(packageJson, PACKAGE_NAME)) {
+    return;
+  }
+
+  const scripts = packageJson.scripts && typeof packageJson.scripts === "object" ? packageJson.scripts : {};
+  const nextScripts = { ...scripts };
+  const added = [];
+  const kept = [];
+
+  for (const [scriptName, scriptValue] of SCRIPT_ENTRIES) {
+    if (typeof nextScripts[scriptName] === "string") {
+      if (nextScripts[scriptName] !== scriptValue) {
+        kept.push(scriptName);
+      }
+      continue;
+    }
+
+    nextScripts[scriptName] = scriptValue;
+    added.push(scriptName);
+  }
+
+  if (added.length === 0) {
+    return;
+  }
+
+  const nextPackageJson = {
+    ...packageJson,
+    scripts: nextScripts
+  };
+  await writeFile(packageJsonPath, `${JSON.stringify(nextPackageJson, null, 2)}\n`, "utf8");
+
+  console.log(`[navai] ${PACKAGE_NAME} configured scripts in ${packageJsonPath}: ${added.join(", ")}.`);
+  if (kept.length > 0) {
+    console.log(`[navai] ${PACKAGE_NAME} kept existing scripts: ${kept.join(", ")}.`);
+  }
+}
+
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.warn(`[navai] ${PACKAGE_NAME} auto-setup skipped: ${message}`);
+});

package/bin/generate-web-module-loaders.mjs

@@ -0,0 +1,483 @@
+#!/usr/bin/env node
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+
+const DEFAULT_EXTENSIONS = [
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mts",
+  ".mtsx",
+  ".cts",
+  ".ctsx",
+  ".mjs",
+  ".mjsx",
+  ".cjs",
+  ".cjsx"
+];
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    printHelp();
+    return;
+  }
+
+  const projectRoot = path.resolve(process.cwd(), args.projectRoot ?? ".");
+  const srcRoot = path.resolve(projectRoot, args.srcRoot ?? "src");
+  const outputFile = path.resolve(projectRoot, args.outputFile ?? "src/ai/generated-module-loaders.ts");
+  const outputDir = path.dirname(outputFile);
+  const envFile = path.resolve(projectRoot, args.envFile ?? ".env");
+  const defaultFunctionsFolder = args.defaultFunctionsFolder ?? "src/ai/functions-modules";
+  const defaultRoutesFile = args.defaultRoutesFile ?? "src/ai/routes.ts";
+  const typeImport = args.typeImport ?? "@navai/voice-frontend";
+  const exportName = args.exportName ?? "NAVAI_WEB_MODULE_LOADERS";
+
+  const envFileValues = await readEnvFile(envFile);
+  const configuredFunctionsFolders =
+    readOptional(process.env.NAVAI_FUNCTIONS_FOLDERS) ??
+    readOptional(envFileValues.NAVAI_FUNCTIONS_FOLDERS);
+  const configuredRoutesFile =
+    readOptional(process.env.NAVAI_ROUTES_FILE) ?? readOptional(envFileValues.NAVAI_ROUTES_FILE);
+  const functionsFolders = configuredFunctionsFolders ?? defaultFunctionsFolder;
+  const routesFile = configuredRoutesFile ?? defaultRoutesFile;
+
+  const defaultRoutesModuleFile = await resolveModulePathFromFs(defaultRoutesFile, projectRoot);
+
+  const configuredFunctionTokens = functionsFolders
+    .split(",")
+    .map((token) => token.trim())
+    .filter(Boolean);
+  const functionTokens =
+    configuredFunctionTokens.length > 0 ? configuredFunctionTokens : [defaultFunctionsFolder];
+  const functionMatchers = functionTokens.map((token) => createPathMatcher(token));
+
+  let selectedFunctionFiles = await collectFilesForTokens({
+    tokens: functionTokens,
+    projectRoot,
+    srcRoot,
+    outputFile
+  });
+  selectedFunctionFiles = dedupeAbsolutePaths(selectedFunctionFiles).filter((absolutePath) => {
+    const sourcePath = sourcePathFromAbsolute(srcRoot, absolutePath);
+    return functionMatchers.some((matcher) => matcher(sourcePath));
+  });
+
+  if (selectedFunctionFiles.length === 0 && configuredFunctionTokens.length > 0) {
+    const fallbackMatcher = createPathMatcher(defaultFunctionsFolder);
+    selectedFunctionFiles = await collectFilesForTokens({
+      tokens: [defaultFunctionsFolder],
+      projectRoot,
+      srcRoot,
+      outputFile
+    });
+    selectedFunctionFiles = dedupeAbsolutePaths(selectedFunctionFiles).filter((absolutePath) =>
+      fallbackMatcher(sourcePathFromAbsolute(srcRoot, absolutePath))
+    );
+    console.warn(
+      `[navai] NAVAI_FUNCTIONS_FOLDERS did not match any module: "${functionsFolders}". Falling back to "${defaultFunctionsFolder}".`
+    );
+  }
+
+  const selectedFiles = new Set(selectedFunctionFiles);
+  const routesModuleFile = await resolveModulePathFromFs(routesFile, projectRoot);
+  if (routesModuleFile) {
+    const shouldIncludeConfiguredRoutes =
+      !defaultRoutesModuleFile ||
+      path.resolve(routesModuleFile) !== path.resolve(defaultRoutesModuleFile);
+    if (shouldIncludeConfiguredRoutes) {
+      selectedFiles.add(routesModuleFile);
+    }
+  } else {
+    console.warn(`[navai] Route module "${routesFile}" was not found in src.`);
+  }
+
+  const orderedFiles = [...selectedFiles].sort((left, right) => left.localeCompare(right));
+  const entries = orderedFiles.map((absolutePath) => {
+    const sourcePath = normalizePath(path.relative(projectRoot, absolutePath));
+    const importPath = toRelativeModulePath(outputDir, absolutePath);
+    return `  "${sourcePath}": async () => await import("${importPath}")`;
+  });
+
+  const output = [
+    "// Auto-generated by @navai/voice-frontend (navai-generate-web-loaders)",
+    `import type { NavaiFunctionModuleLoaders } from "${typeImport}";`,
+    "",
+    `export const ${exportName}: NavaiFunctionModuleLoaders = {`,
+    entries.join(",\n"),
+    "};",
+    ""
+  ].join("\n");
+
+  await mkdir(outputDir, { recursive: true });
+  await writeFile(outputFile, output, "utf8");
+
+  console.log(
+    `[navai] Generated ${entries.length} web module loader(s) at ${normalizePath(
+      path.relative(projectRoot, outputFile)
+    )}.`
+  );
+}
+
+function parseArgs(argv) {
+  const args = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === "--help" || token === "-h") {
+      args.help = true;
+      continue;
+    }
+
+    if (!token.startsWith("--")) {
+      throw new Error(`Unknown argument: "${token}"`);
+    }
+
+    const equalsIndex = token.indexOf("=");
+    if (equalsIndex >= 0) {
+      const key = token.slice(2, equalsIndex);
+      const value = token.slice(equalsIndex + 1);
+      setArgValue(args, key, value);
+      continue;
+    }
+
+    const key = token.slice(2);
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--")) {
+      throw new Error(`Missing value for argument "--${key}"`);
+    }
+
+    setArgValue(args, key, next);
+    index += 1;
+  }
+
+  return args;
+}
+
+function setArgValue(args, key, value) {
+  const map = {
+    "project-root": "projectRoot",
+    "src-root": "srcRoot",
+    "output-file": "outputFile",
+    "env-file": "envFile",
+    "default-functions-folder": "defaultFunctionsFolder",
+    "default-routes-file": "defaultRoutesFile",
+    "type-import": "typeImport",
+    "export-name": "exportName"
+  };
+
+  const mapped = map[key];
+  if (!mapped) {
+    throw new Error(`Unknown argument: "--${key}"`);
+  }
+
+  args[mapped] = value;
+}
+
+function printHelp() {
+  const help = [
+    "navai-generate-web-loaders",
+    "",
+    "Generates src/ai/generated-module-loaders.ts using NAVAI_FUNCTIONS_FOLDERS and NAVAI_ROUTES_FILE.",
+    "",
+    "Usage:",
+    "  navai-generate-web-loaders [--project-root <path>] [--env-file <path>]",
+    "",
+    "Options:",
+    "  --project-root <path>               Project root (default: current directory)",
+    "  --src-root <path>                   Source root (default: src)",
+    "  --output-file <path>                Output file (default: src/ai/generated-module-loaders.ts)",
+    "  --env-file <path>                   Env file relative to project root (default: .env)",
+    "  --default-functions-folder <path>   Fallback functions folder (default: src/ai/functions-modules)",
+    "  --default-routes-file <path>        Fallback routes file (default: src/ai/routes.ts)",
+    "  --type-import <module>              Type import path (default: @navai/voice-frontend)",
+    "  --export-name <identifier>          Export constant name (default: NAVAI_WEB_MODULE_LOADERS)",
+    "  --help                              Show this help"
+  ].join("\n");
+
+  console.log(help);
+}
+
+async function readEnvFile(envPath) {
+  try {
+    const contents = await readFile(envPath, "utf8");
+    return parseEnv(contents);
+  } catch {
+    return {};
+  }
+}
+
+function parseEnv(contents) {
+  const result = {};
+  const lines = contents.split(/\r?\n/);
+  for (const rawLine of lines) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) {
+      continue;
+    }
+
+    const eqIndex = line.indexOf("=");
+    if (eqIndex <= 0) {
+      continue;
+    }
+
+    const key = line.slice(0, eqIndex).trim();
+    let value = line.slice(eqIndex + 1).trim();
+    if (
+      (value.startsWith("\"") && value.endsWith("\"")) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+
+    result[key] = value;
+  }
+
+  return result;
+}
+
+function readOptional(input) {
+  if (typeof input !== "string") {
+    return undefined;
+  }
+
+  const trimmed = input.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function normalizePath(filePath) {
+  return filePath.replace(/\\/g, "/");
+}
+
+function normalizeSourcePath(input) {
+  return normalizePath(input)
+    .trim()
+    .replace(/^\/+/, "")
+    .replace(/^(\.\/)+/, "")
+    .replace(/^(\.\.\/)+/, "");
+}
+
+function ensureSrcPrefix(input) {
+  const normalized = normalizeSourcePath(input);
+  if (!normalized) {
+    return "";
+  }
+
+  return normalized.startsWith("src/") ? normalized : `src/${normalized}`;
+}
+
+function toRelativeModulePath(outputDir, absoluteFilePath) {
+  const relative = normalizePath(path.relative(outputDir, absoluteFilePath));
+  const withPrefix = relative.startsWith(".") ? relative : `./${relative}`;
+  return withPrefix.replace(/\.[cm]?[jt]sx?$/i, "");
+}
+
+function shouldIncludeFile(filename) {
+  if (!/\.[cm]?[jt]sx?$/i.test(filename)) {
+    return false;
+  }
+
+  return !/\.d\.ts$/i.test(filename);
+}
+
+function dedupeAbsolutePaths(absolutePaths) {
+  const deduped = new Map();
+  for (const absolutePath of absolutePaths) {
+    const resolved = path.resolve(absolutePath);
+    if (!deduped.has(resolved)) {
+      deduped.set(resolved, resolved);
+    }
+  }
+
+  return [...deduped.values()].sort((left, right) => left.localeCompare(right));
+}
+
+async function collectFilesForTokens(input) {
+  const files = [];
+  for (const token of input.tokens) {
+    files.push(...(await collectFilesForToken({ ...input, token })));
+  }
+
+  return files;
+}
+
+async function collectFilesForToken(input) {
+  const normalizedToken = ensureSrcPrefix(input.token);
+  if (!normalizedToken) {
+    return [];
+  }
+
+  const matcher = createPathMatcher(normalizedToken);
+
+  if (normalizedToken.endsWith("/...")) {
+    const base = normalizedToken.slice(0, -4).replace(/\/+$/, "");
+    const baseDirectory = path.resolve(input.projectRoot, base);
+    return await collectFilesFromDirectoryWithMatcher(baseDirectory, input, matcher);
+  }
+
+  if (normalizedToken.includes("*")) {
+    const wildcardBase = getWildcardSearchBase(normalizedToken);
+    const baseDirectory = path.resolve(input.projectRoot, wildcardBase);
+    return await collectFilesFromDirectoryWithMatcher(baseDirectory, input, matcher);
+  }
+
+  if (/\.[cm]?[jt]sx?$/i.test(normalizedToken)) {
+    const resolved = await resolveModulePathFromFs(normalizedToken, input.projectRoot);
+    if (!resolved || path.resolve(resolved) === path.resolve(input.outputFile)) {
+      return [];
+    }
+
+    return [resolved];
+  }
+
+  const possibleDirectory = path.resolve(input.projectRoot, normalizedToken);
+  const directoryStats = await safeStat(possibleDirectory);
+  if (directoryStats?.isDirectory()) {
+    return await walkDirectory(possibleDirectory, input.outputFile);
+  }
+
+  const resolved = await resolveModulePathFromFs(normalizedToken, input.projectRoot);
+  if (!resolved || path.resolve(resolved) === path.resolve(input.outputFile)) {
+    return [];
+  }
+
+  return [resolved];
+}
+
+async function collectFilesFromDirectoryWithMatcher(directoryPath, input, matcher) {
+  const files = await walkDirectoryIfExists(directoryPath, input.outputFile);
+  return files.filter((absolutePath) => matcher(sourcePathFromAbsolute(input.srcRoot, absolutePath)));
+}
+
+function getWildcardSearchBase(pattern) {
+  const wildcardIndex = pattern.indexOf("*");
+  if (wildcardIndex < 0) {
+    return pattern;
+  }
+
+  const prefix = pattern.slice(0, wildcardIndex);
+  if (!prefix) {
+    return "src";
+  }
+
+  const directoryPrefix = prefix.endsWith("/")
+    ? prefix
+    : prefix.slice(0, prefix.lastIndexOf("/") + 1);
+  const trimmed = directoryPrefix.replace(/\/+$/, "");
+  return trimmed || "src";
+}
+
+async function walkDirectoryIfExists(directoryPath, outputFile) {
+  const directoryStats = await safeStat(directoryPath);
+  if (!directoryStats?.isDirectory()) {
+    return [];
+  }
+
+  return await walkDirectory(directoryPath, outputFile);
+}
+
+async function safeStat(filePath) {
+  try {
+    return await stat(filePath);
+  } catch {
+    return null;
+  }
+}
+
+async function walkDirectory(directoryPath, outputFile) {
+  const entries = await readdir(directoryPath, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const absoluteEntryPath = path.join(directoryPath, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...(await walkDirectory(absoluteEntryPath, outputFile)));
+      continue;
+    }
+
+    if (!entry.isFile() || !shouldIncludeFile(entry.name)) {
+      continue;
+    }
+
+    if (path.resolve(absoluteEntryPath) === path.resolve(outputFile)) {
+      continue;
+    }
+
+    files.push(path.resolve(absoluteEntryPath));
+  }
+
+  return files;
+}
+
+function sourcePathFromAbsolute(srcRoot, absoluteFilePath) {
+  return ensureSrcPrefix(path.relative(srcRoot, absoluteFilePath));
+}
+
+function globToRegExp(pattern) {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  const wildcardSafe = escaped.replace(/\*\*/g, "___DOUBLE_STAR___");
+  const single = wildcardSafe.replace(/\*/g, "[^/]*");
+  const output = single.replace(/___DOUBLE_STAR___/g, ".*");
+  return new RegExp(`^${output}$`);
+}
+
+function createPathMatcher(input) {
+  const normalized = ensureSrcPrefix(input);
+  if (!normalized) {
+    return () => false;
+  }
+
+  if (normalized.endsWith("/...")) {
+    const base = normalized.slice(0, -4).replace(/\/+$/, "");
+    return (candidatePath) => candidatePath.startsWith(`${base}/`);
+  }
+
+  if (normalized.includes("*")) {
+    const regexp = globToRegExp(normalized);
+    return (candidatePath) => regexp.test(candidatePath);
+  }
+
+  if (/\.[cm]?[jt]sx?$/i.test(normalized)) {
+    return (candidatePath) => candidatePath === normalized;
+  }
+
+  const base = normalized.replace(/\/+$/, "");
+  return (candidatePath) => candidatePath === base || candidatePath.startsWith(`${base}/`);
+}
+
+function buildModuleCandidates(inputPath) {
+  const normalized = ensureSrcPrefix(inputPath);
+  if (!normalized) {
+    return [];
+  }
+
+  if (/\.[cm]?[jt]sx?$/.test(normalized)) {
+    return [normalized];
+  }
+
+  return [
+    ...DEFAULT_EXTENSIONS.map((extension) => `${normalized}${extension}`),
+    ...DEFAULT_EXTENSIONS.map((extension) => `${normalized}/index${extension}`)
+  ];
+}
+
+async function resolveModulePathFromFs(inputPath, projectRoot) {
+  const candidates = buildModuleCandidates(inputPath);
+  for (const candidate of candidates) {
+    const absoluteCandidate = path.resolve(projectRoot, candidate);
+    const candidateStats = await safeStat(absoluteCandidate);
+    if (candidateStats?.isFile() && shouldIncludeFile(path.basename(absoluteCandidate))) {
+      return absoluteCandidate;
+    }
+  }
+
+  return null;
+}
+
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`[navai] Failed to generate web module loaders: ${message}`);
+  process.exitCode = 1;
+});