tidewave 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -1,55 +1,9 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
+## [0.5.1] - 2025-11-11
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+* Add `npx tidewave install` and trim down dependency list.
 
-## [0.1.0] - 2024-08-29
+## [0.5.0] - 2025-11-10
 
-### Added
-
-#### Core Features
-- **MCP Server Support**: STDIO-based Model Context Protocol server for integration with AI coding assistants
-- **Documentation Extraction**: Extract TypeScript/JavaScript documentation and type information for symbols, classes, functions, and methods
-- **Source Location Resolution**: Get source file paths for modules, symbols, and members
-- **Multi-format Support**: Support for local files, npm dependencies, and Node.js builtin modules
-
-#### Module Reference Formats
-- `module:symbol` - Extract documentation for top-level symbols
-- `module:Class#method` - Extract documentation for instance methods
-- `module:Class.method` - Extract documentation for static methods
-- `node:Class#method` - Extract documentation for Node.js builtin instance methods
-- `node:Class.method` - Extract documentation for Node.js builtin static methods
-
-#### CLI Commands
-- `tidewave mcp` - Start the MCP server via STDIO
-- `tidewave docs <module-path>` - Extract documentation for a symbol
-- `tidewave source <module>` - Get the source file path for a module
-
-#### Runtime Support
-- Full support for Node.js with npm/npx
-- Native support for Bun with bunx
-- Support for Deno via npm: protocol
-
-### Fixed
-- Handle source location of symbols and members correctly (#7)
-- Handle prefix option only on CLI layer, not in core extraction (#6)
-- Correctly extract JavaScript/TypeScript symbols, instances, and methods
-- Show interface types correctly
-- Handle falsy values and improve error handling (#1)
-
-### Changed
-- Refactored codebase into modular structure for better maintainability
-- Simplified module resolution and extraction logic
-- Improved TypeScript and Node.js module resolution
-- Changed config flag for project path handling (#3)
-
-### Technical Details
-- Built with TypeScript for type safety
-- Uses TypeScript Compiler API for accurate code analysis
-- Supports ESM modules
-- Includes comprehensive error handling and user-friendly error messages
-- Optimized for use with AI coding assistants through MCP protocol
-
-[0.1.0]: https://github.com/dashbit/tidewave_javascript/releases/tag/v0.1.0
+* Initial release.

package/README.md

@@ -1,13 +1,16 @@
 # Tidewave
 
-> Tidewave Web for Next.js and React+Vite is currently in alpha testing!
+Tidewave is the coding agent for full-stack web app development. Integrate
+Claude Code, OpenAI Codex, and other agents with your web app and web framework
+at every layer, from UI to database. [See our website](https://tidewave.ai) for
+more information.
 
-Tidewave is the coding agent for full-stack web app development.
-[See our website](https://tidewave.ai) for more information.
+This project supports:
 
-If you are using Next.js or you have a React + Vite frontend, talking either to
-a backend as a service (such as Supabase) or a third-party framework, you are in
-the right place!
+- Next.js 15/16
+
+- React + Vite frontends, with either a backend as a service (such as Supabase)
+  or a third-party framework
 
 If you are using React with Django, FastAPI, Flask, Phoenix, or Rails,
 [follow the steps here instead](http://hexdocs.pm/tidewave/react.html).
@@ -187,8 +190,9 @@ database calls, etc) won't be available.
 Next.js' `tidewaveHandler` and Vite's `tidewave` accept the configuration
 options below:
 
-- `allow_remote_access:` allow remote connections when true (default false)
-- `allowed_origins:` defaults to the current host/port
+- `allow_remote_access:` allow remote connections when true (default false).
+  Enable this only if you trust your network and you want Tidewave MCP to be
+  accessed from another trusted machine
 - `team`: enable Tidewave Web for teams
 
 ## CLI

package/dist/cli/index.js

@@ -4924,7 +4924,7 @@ var init_src = __esm(() => {
 });
 
 // package.json
-var name = "tidewave", version = "0.5.0", package_default;
+var name = "tidewave", version = "0.5.1", package_default;
 var init_package = __esm(() => {
   package_default = {
     name,
@@ -4995,23 +4995,14 @@ var init_package = __esm(() => {
     },
     dependencies: {
       "@modelcontextprotocol/sdk": "^1.17.4",
-      "@opentelemetry/api": "^1.9.0",
-      "@opentelemetry/api-logs": "^0.206.0",
-      "@opentelemetry/core": "^2.1.0",
-      "@opentelemetry/resources": "^2.1.0",
-      "@opentelemetry/sdk-logs": "^0.206.0",
-      "@opentelemetry/sdk-trace-base": "^2.1.0",
-      "@opentelemetry/sdk-trace-node": "^2.1.0",
-      "@opentelemetry/semantic-conventions": "^1.37.0",
       "body-parser": "^2.2.0",
-      chalk: "^5.3.0",
-      commander: "^12.1.0",
       connect: "^3.7.0",
       typescript: "^5",
       zod: "3.25.76"
     },
     devDependencies: {
       "@eslint/js": "^9.16.0",
+      "@opentelemetry/sdk-trace-node": "^2.1.0",
       "@types/body-parser": "^1.19.6",
       "@types/bun": "latest",
       "@types/connect": "^3.4.38",
@@ -5021,6 +5012,8 @@ var init_package = __esm(() => {
       "@vercel/otel": "^2.0.1",
       "@vitest/ui": "^3.2.4",
       "bun-types": "latest",
+      commander: "^12.1.0",
+      chalk: "^5.3.0",
       eslint: "^9.16.0",
       globals: "^15.14.0",
       next: "^15.5.3",
@@ -14525,7 +14518,7 @@ init_tools();
 init_src();
 init_package();
 import { program } from "commander";
-import chalk from "chalk";
+import chalk2 from "chalk";
 
 // node_modules/@modelcontextprotocol/sdk/dist/esm/server/stdio.js
 import process2 from "node:process";
@@ -14625,11 +14618,345 @@ class StdioServerTransport {
 
 // src/cli/index.ts
 init_mcp2();
-function chdir(path4) {
+
+// src/cli/install.ts
+import * as fs from "fs";
+import * as path4 from "path";
+import * as child_process from "child_process";
+import * as readline from "readline";
+import chalk from "chalk";
+async function handleInstall(options) {
+  const targetDir = options.prefix || process.cwd();
+  const dryRun = options.dryRun || false;
+  const skipDeps = options.skipDeps || false;
+  console.log(chalk.blue(`
+\uD83C\uDF0A Tidewave Installer
+`));
+  console.log(chalk.gray(`Target directory: ${targetDir}`));
+  if (dryRun) {
+    console.log(chalk.yellow(`
+⚠️  DRY RUN MODE - No files will be created
+`));
+  }
+  const nextVersion = await detectNextJsVersion(targetDir);
+  if (!nextVersion) {
+    console.error(chalk.red(`
+❌ Could not find Next.js in node_modules.`));
+    console.log(chalk.gray(`
+The installer only works for Next.js projects
+`));
+    process.exit(1);
+  }
+  console.log(chalk.green(`✅ Detected Next.js ${nextVersion.raw} (v${nextVersion.major})`));
+  if (!skipDeps) {
+    await installDependencies(targetDir, dryRun);
+  } else {
+    console.log(chalk.gray("⏭️  Skipping dependency installation"));
+  }
+  const steps = [
+    () => createApiHandler(targetDir, dryRun),
+    () => createMiddleware(targetDir, nextVersion, dryRun),
+    () => createInstrumentation(targetDir, dryRun)
+  ];
+  for (const step of steps) {
+    await step();
+  }
+  console.log(chalk.green(`
+✅ Tidewave setup complete!
+`));
+  console.log(chalk.blue("Next steps:"));
+  console.log("  1. Start your Next.js dev server: npm run dev");
+  console.log("  2. Install the Tidewave app: https://hexdocs.pm/tidewave/");
+  console.log(`  3. Connect to your app through Tidewave
+`);
+}
+async function detectNextJsVersion(dir) {
+  try {
+    const nextPackageJsonPath = path4.join(dir, "node_modules", "next", "package.json");
+    if (!fs.existsSync(nextPackageJsonPath)) {
+      return null;
+    }
+    const nextPackageJson = JSON.parse(fs.readFileSync(nextPackageJsonPath, "utf-8"));
+    const { version: version2 } = nextPackageJson;
+    const match = version2.match(/^(\d+)\.(\d+)\.(\d+)/);
+    if (match) {
+      return {
+        major: parseInt(match[1]),
+        minor: parseInt(match[2]),
+        raw: version2
+      };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function detectPackageManager(dir) {
+  if (fs.existsSync(path4.join(dir, "bun.lockb")))
+    return "bun";
+  if (fs.existsSync(path4.join(dir, "pnpm-lock.yaml")))
+    return "pnpm";
+  if (fs.existsSync(path4.join(dir, "yarn.lock")))
+    return "yarn";
+  if (fs.existsSync(path4.join(dir, "package-lock.json")))
+    return "npm";
+  return "npm";
+}
+async function promptUser(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      const normalized = answer.trim().toLowerCase();
+      resolve(normalized === "" || normalized === "y" || normalized === "yes");
+    });
+  });
+}
+async function installDependencies(dir, dryRun) {
+  console.log(chalk.yellow("\uD83D\uDCE6 Installing dependencies..."));
+  if (dryRun) {
+    console.log(chalk.gray("[DRY RUN] Would install: tidewave, @opentelemetry/sdk-node"));
+    return;
+  }
+  const pm = detectPackageManager(dir);
+  const devDepCommands = {
+    npm: ["install", "-D", "tidewave"],
+    yarn: ["add", "-D", "tidewave"],
+    pnpm: ["add", "--save-dev", "tidewave"],
+    bun: ["add", "--dev", "tidewave"]
+  };
+  const depCommands = {
+    npm: ["install", "@opentelemetry/sdk-node"],
+    yarn: ["add", "@opentelemetry/sdk-node"],
+    pnpm: ["add", "@opentelemetry/sdk-node"],
+    bun: ["add", "@opentelemetry/sdk-node"]
+  };
+  const devCmds = devDepCommands[pm];
+  const depCmds = depCommands[pm];
+  if (!devCmds || !depCmds) {
+    console.error(chalk.red(`
+❌ Unknown package manager: ${pm}`));
+    process.exit(1);
+  }
+  try {
+    child_process.execSync(`${pm} ${devCmds.join(" ")}`, {
+      cwd: dir,
+      stdio: "inherit"
+    });
+    child_process.execSync(`${pm} ${depCmds.join(" ")}`, {
+      cwd: dir,
+      stdio: "inherit"
+    });
+    console.log(chalk.green("✅ Dependencies installed"));
+  } catch (_error) {
+    console.error(chalk.red(`
+❌ Failed to install dependencies`));
+    console.log(chalk.gray(`
+Please install manually:
+  ${pm} ${devCmds.join(" ")}
+  ${pm} ${depCmds.join(" ")}
+`));
+    process.exit(1);
+  }
+}
+async function createApiHandler(dir, dryRun) {
+  const apiDir = path4.join(dir, "pages", "api");
+  const handlerPath = path4.join(apiDir, "tidewave.ts");
+  const handlerContent = `import type { NextApiRequest, NextApiResponse } from 'next';
+
+export default async function handler(
+  req: NextApiRequest,
+  res: NextApiResponse,
+) {
+  if (process.env.NODE_ENV === 'development') {
+    const { tidewaveHandler } = await import('tidewave/next-js/handler');
+    const handler = await tidewaveHandler();
+    return handler(req, res);
+  } else {
+    res.status(404).end();
+  }
+}
+
+export const config = {
+  runtime: 'nodejs',
+  api: {
+    bodyParser: false, // Tidewave already parses the body internally
+  },
+};
+`;
+  if (fs.existsSync(handlerPath)) {
+    if (dryRun) {
+      console.log(chalk.gray(`[DRY RUN] Would ask to overwrite: ${path4.relative(dir, handlerPath)}`));
+      return;
+    }
+    const shouldOverwrite = await promptUser(chalk.yellow(`
+⚠️  ${path4.relative(dir, handlerPath)} already exists. Overwrite? (Y/n): `));
+    if (!shouldOverwrite) {
+      console.log(chalk.gray(`⏭️  Skipping: ${path4.relative(dir, handlerPath)}`));
+      return;
+    }
+  }
+  if (dryRun) {
+    console.log(chalk.gray(`[DRY RUN] Would create: ${path4.relative(dir, handlerPath)}`));
+    return;
+  }
+  fs.mkdirSync(apiDir, { recursive: true });
+  fs.writeFileSync(handlerPath, handlerContent, "utf-8");
+  console.log(chalk.green(`✅ Created: ${path4.relative(dir, handlerPath)}`));
+}
+async function createMiddleware(dir, nextVersion, dryRun) {
+  const isNext16Plus = nextVersion.major >= 16;
+  const fileName = isNext16Plus ? "proxy.ts" : "middleware.ts";
+  const filePath = path4.join(dir, fileName);
+  if (fs.existsSync(filePath)) {
+    console.log(chalk.yellow(`⏭️  ${fileName} already exists`));
+    const content = fs.readFileSync(filePath, "utf-8");
+    if (content.includes("/tidewave") && content.includes("/api/tidewave")) {
+      console.log(chalk.green(`✅ ${fileName} already configured for Tidewave`));
+      return;
+    }
+    console.log(chalk.gray(`
+  Please manually add the following to your ${fileName}:
+`));
+    printMiddlewareInstructions(isNext16Plus);
+    return;
+  }
+  const middlewareContent = isNext16Plus ? `import { NextRequest, NextResponse } from 'next/server';
+
+export function proxy(req: NextRequest): NextResponse {
+  if (req.nextUrl.pathname.startsWith('/tidewave')) {
+    return NextResponse.rewrite(new URL('/api/tidewave', req.url));
+  }
+
+  // Here you could add your own logic or different middlewares.
+  return NextResponse.next();
+}
+` : `import { NextRequest, NextResponse } from 'next/server';
+
+export function middleware(req: NextRequest): NextResponse {
+  if (req.nextUrl.pathname.startsWith('/tidewave')) {
+    return NextResponse.rewrite(new URL('/api/tidewave', req.url));
+  }
+
+  // Here you could add your own logic or different middlewares.
+  return NextResponse.next();
+}
+
+export const config = {
+  matcher: ['/tidewave/:path*'],
+};
+`;
+  if (dryRun) {
+    console.log(chalk.gray(`[DRY RUN] Would create: ${fileName}`));
+    return;
+  }
+  fs.writeFileSync(filePath, middlewareContent, "utf-8");
+  console.log(chalk.green(`✅ Created: ${fileName}`));
+}
+function printMiddlewareInstructions(isNext16Plus) {
+  if (isNext16Plus) {
+    console.log(chalk.cyan(`  if (req.nextUrl.pathname.startsWith('/tidewave')) {
+    return NextResponse.rewrite(new URL('/api/tidewave', req.url));
+  }`));
+  } else {
+    console.log(chalk.cyan(`  if (req.nextUrl.pathname.startsWith('/tidewave')) {
+    return NextResponse.rewrite(new URL('/api/tidewave', req.url));
+  }
+
+  // Also add to config.matcher:
+  export const config = {
+    matcher: ['/tidewave/:path*'],
+  };`));
+  }
+  console.log();
+}
+async function createInstrumentation(dir, dryRun) {
+  const rootPath = path4.join(dir, "instrumentation.ts");
+  const srcPath = path4.join(dir, "src", "instrumentation.ts");
+  const hasSrcDir = fs.existsSync(path4.join(dir, "src"));
+  const instrumentationPath = hasSrcDir ? srcPath : rootPath;
+  if (fs.existsSync(rootPath) || fs.existsSync(srcPath)) {
+    const existingPath = fs.existsSync(rootPath) ? rootPath : srcPath;
+    const existingFile = fs.existsSync(rootPath) ? "instrumentation.ts" : "src/instrumentation.ts";
+    console.log(chalk.yellow(`⏭️  ${existingFile} already exists`));
+    const content = fs.readFileSync(existingPath, "utf-8");
+    if (content.includes("TidewaveSpanProcessor") && content.includes("TidewaveLogRecordProcessor")) {
+      console.log(chalk.green(`✅ ${existingFile} already configured for Tidewave`));
+      return;
+    }
+    console.log(chalk.gray(`
+  Please manually add the following to your instrumentation.ts:
+`));
+    printInstrumentationInstructions();
+    return;
+  }
+  const instrumentationContent = `// instrumentation.ts
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import type { SpanProcessor } from '@opentelemetry/sdk-trace-base';
+import type { LogRecordProcessor } from '@opentelemetry/sdk-logs';
+
+export async function register() {
+  const runtime = process.env.NEXT_RUNTIME;
+  const env = process.env.NODE_ENV;
+
+  // Add your app own processes here existing configuration
+  const sdkConfig: {
+    spanProcessors: SpanProcessor[];
+    logRecordProcessors: LogRecordProcessor[];
+  } = {
+    spanProcessors: [],
+    logRecordProcessors: [],
+  };
+
+  // Conditionally add Tidewave processors in development
+  if (runtime === 'nodejs' && env === 'development') {
+    const { TidewaveSpanProcessor, TidewaveLogRecordProcessor } = await import(
+      'tidewave/next-js/instrumentation'
+    );
+
+    sdkConfig.spanProcessors.push(new TidewaveSpanProcessor());
+    sdkConfig.logRecordProcessors.push(new TidewaveLogRecordProcessor());
+  }
+
+  const sdk = new NodeSDK(sdkConfig);
+  sdk.start();
+}
+`;
+  if (dryRun) {
+    console.log(chalk.gray(`[DRY RUN] Would create: ${path4.relative(dir, instrumentationPath)}`));
+    return;
+  }
+  if (hasSrcDir) {
+    fs.mkdirSync(path4.dirname(instrumentationPath), { recursive: true });
+  }
+  fs.writeFileSync(instrumentationPath, instrumentationContent, "utf-8");
+  console.log(chalk.green(`✅ Created: ${path4.relative(dir, instrumentationPath)}`));
+}
+function printInstrumentationInstructions() {
+  console.log(chalk.cyan(`  // Inside your register() function:
+  const runtime = process.env.NEXT_RUNTIME;
+  const env = process.env.NODE_ENV;
+
+  if (runtime === 'nodejs' && env === 'development') {
+    const { TidewaveSpanProcessor, TidewaveLogRecordProcessor } = await import(
+      'tidewave/next-js/instrumentation'
+    );
+
+    sdkConfig.spanProcessors.push(new TidewaveSpanProcessor());
+    sdkConfig.logRecordProcessors.push(new TidewaveLogRecordProcessor());
+  }`));
+  console.log();
+}
+
+// src/cli/index.ts
+function chdir(path5) {
   try {
-    process.chdir(path4);
+    process.chdir(path5);
   } catch (e) {
-    console.error(chalk.red(`Failed to apply given prefix: ${e}`));
+    console.error(chalk2.red(`Failed to apply given prefix: ${e}`));
   }
 }
 program.name(name).description("Universal documentation and source extraction tool for TypeScript and JavaScript").version(version);
@@ -14638,7 +14965,7 @@ async function handleGetDocs2(modulePath, options) {
     chdir(options.prefix);
   const docsResult = await Tidewave.extractDocs(modulePath);
   if (isExtractError(docsResult)) {
-    console.error(chalk.red(`Error: ${docsResult.error.message}`));
+    console.error(chalk2.red(`Error: ${docsResult.error.message}`));
     process.exit(1);
   }
   if (options.json) {
@@ -14652,7 +14979,7 @@ async function handleGetSourcePath2(moduleName, options) {
     chdir(options.prefix);
   const sourceResult = await Tidewave.getSourceLocation(moduleName);
   if (isResolveError(sourceResult)) {
-    console.error(chalk.red(`Error: ${sourceResult.error.message}`));
+    console.error(chalk2.red(`Error: ${sourceResult.error.message}`));
     process.exit(1);
   }
   console.log(sourceResult.path);
@@ -14668,6 +14995,7 @@ var {
   docs: { cli: docsCli },
   source: { cli: sourceCli }
 } = tools;
+program.command("install").description("Install Tidewave in a Next.js project").option("--prefix <path>", "Specify the directory containing package.json").option("--dry-run", "Preview changes without creating files").action(handleInstall);
 program.command("mcp").description("Starts a MCP server for tidewave (stdio)").option(docsCli.options.prefix.flag, docsCli.options.prefix.desc).action(handleMcp);
 program.command(docsCli.command).description(docsCli.description).argument(docsCli.argument, docsCli.argumentDescription).option(docsCli.options.prefix.flag, docsCli.options.prefix.desc).option(docsCli.options.json.flag, docsCli.options.json.desc).action(handleGetDocs2);
 program.command(sourceCli.command).description(sourceCli.description).argument(sourceCli.argument, sourceCli.argumentDescription).option(sourceCli.options.prefix.flag, sourceCli.options.prefix.desc).action(handleGetSourcePath2);

package/dist/cli/install.d.ts

@@ -0,0 +1,7 @@
+interface InstallOptions {
+    prefix?: string;
+    dryRun?: boolean;
+    skipDeps?: boolean;
+}
+export declare function handleInstall(options: InstallOptions): Promise<void>;
+export {};