@nathapp/nax 0.50.3 → 0.51.0

package/src/cli/init-context.ts

@@ -1,405 +0,0 @@
-/**
- * Context.md Generation (INIT-002)
- *
- * Generates context.md from filesystem scan with optional LLM enhancement.
- * Default mode: template from scan (zero LLM cost)
- * AI mode (--ai flag): LLM-powered narrative context
- */
-
-import { existsSync } from "node:fs";
-import { mkdir } from "node:fs/promises";
-import { basename, join } from "node:path";
-import { getLogger } from "../logger";
-
-/** Project scan results */
-export interface ProjectScan {
-  projectName: string;
-  fileTree: string[];
-  packageManifest: {
-    name?: string;
-    description?: string;
-    scripts?: Record<string, string>;
-    dependencies?: Record<string, string>;
-  } | null;
-  readmeSnippet: string | null;
-  entryPoints: string[];
-  configFiles: string[];
-}
-
-/** Package manifest structure */
-interface PackageManifest {
-  name?: string;
-  description?: string;
-  scripts?: Record<string, string>;
-  dependencies?: Record<string, string>;
-}
-
-/** initContext options */
-export interface InitContextOptions {
-  ai?: boolean;
-  force?: boolean;
-}
-
-/** Dependency injection for testing */
-export const _deps = {
-  callLLM: async (_prompt: string): Promise<string> => {
-    // Placeholder implementation
-    // In production, this would call the nax LLM infrastructure
-    throw new Error("callLLM not implemented");
-  },
-};
-
-/**
- * Recursively find all files in a directory, excluding certain paths.
- * Returns relative paths, limited to maxFiles entries.
- */
-async function findFiles(dir: string, maxFiles = 200): Promise<string[]> {
-  // Use find command to locate files, excluding common directories
-  try {
-    const proc = Bun.spawnSync(
-      [
-        "find",
-        dir,
-        "-type",
-        "f",
-        "-not",
-        "-path",
-        "*/node_modules/*",
-        "-not",
-        "-path",
-        "*/.git/*",
-        "-not",
-        "-path",
-        "*/dist/*",
-      ],
-      { stdio: ["pipe", "pipe", "pipe"] },
-    );
-
-    if (proc.success) {
-      const output = new TextDecoder().decode(proc.stdout);
-      const files = output
-        .trim()
-        .split("\n")
-        .filter((f) => f.length > 0)
-        .map((f) => f.replace(`${dir}/`, ""))
-        .slice(0, maxFiles);
-      return files;
-    }
-  } catch {
-    // find command failed, use fallback
-  }
-
-  return [];
-}
-
-/**
- * Read and parse package.json if it exists
- */
-async function readPackageManifest(projectRoot: string): Promise<PackageManifest | null> {
-  const packageJsonPath = join(projectRoot, "package.json");
-
-  if (!existsSync(packageJsonPath)) {
-    return null;
-  }
-
-  try {
-    const content = await Bun.file(packageJsonPath).text();
-    const manifest = JSON.parse(content) as PackageManifest;
-    return {
-      name: manifest.name,
-      description: manifest.description,
-      scripts: manifest.scripts,
-      dependencies: manifest.dependencies,
-    };
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Read first 100 lines of README.md if it exists
- */
-async function readReadmeSnippet(projectRoot: string): Promise<string | null> {
-  const readmePath = join(projectRoot, "README.md");
-
-  if (!existsSync(readmePath)) {
-    return null;
-  }
-
-  try {
-    const content = await Bun.file(readmePath).text();
-    const lines = content.split("\n");
-    return lines.slice(0, 100).join("\n");
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Detect entry points in the project
- */
-async function detectEntryPoints(projectRoot: string): Promise<string[]> {
-  const candidates = ["src/index.ts", "src/main.ts", "main.go", "src/lib.rs"];
-  const found: string[] = [];
-
-  for (const candidate of candidates) {
-    const path = join(projectRoot, candidate);
-    if (existsSync(path)) {
-      found.push(candidate);
-    }
-  }
-
-  return found;
-}
-
-/**
- * Detect config files in the project
- */
-async function detectConfigFiles(projectRoot: string): Promise<string[]> {
-  const candidates = ["tsconfig.json", "biome.json", "turbo.json", ".env.example"];
-  const found: string[] = [];
-
-  for (const candidate of candidates) {
-    const path = join(projectRoot, candidate);
-    if (existsSync(path)) {
-      found.push(candidate);
-    }
-  }
-
-  return found;
-}
-
-/**
- * Scan a project for context information
- */
-export async function scanProject(projectRoot: string): Promise<ProjectScan> {
-  const fileTree = await findFiles(projectRoot, 200);
-  const packageManifest = await readPackageManifest(projectRoot);
-  const readmeSnippet = await readReadmeSnippet(projectRoot);
-  const entryPoints = await detectEntryPoints(projectRoot);
-  const configFiles = await detectConfigFiles(projectRoot);
-
-  // Determine project name from package.json or directory basename
-  const projectName = packageManifest?.name || basename(projectRoot);
-
-  return {
-    projectName,
-    fileTree,
-    packageManifest,
-    readmeSnippet,
-    entryPoints,
-    configFiles,
-  };
-}
-
-/**
- * Generate a markdown template for context.md from scan results
- */
-export function generateContextTemplate(scan: ProjectScan): string {
-  const lines: string[] = [];
-
-  lines.push(`# ${scan.projectName}\n`);
-
-  if (scan.packageManifest?.description) {
-    lines.push(`${scan.packageManifest.description}\n`);
-  } else {
-    lines.push("<!-- TODO: Add project description -->\n");
-  }
-
-  if (scan.entryPoints.length > 0) {
-    lines.push("## Entry Points\n");
-    for (const ep of scan.entryPoints) {
-      lines.push(`- ${ep}`);
-    }
-    lines.push("");
-  } else {
-    lines.push("## Entry Points\n");
-    lines.push("<!-- TODO: Document entry points -->\n");
-  }
-
-  if (scan.fileTree.length > 0) {
-    lines.push("## Project Structure\n");
-    lines.push("```");
-    for (const file of scan.fileTree.slice(0, 20)) {
-      lines.push(file);
-    }
-    if (scan.fileTree.length > 20) {
-      lines.push(`... and ${scan.fileTree.length - 20} more files`);
-    }
-    lines.push("```\n");
-  } else {
-    lines.push("## Project Structure\n");
-    lines.push("<!-- TODO: Document project structure -->\n");
-  }
-
-  if (scan.configFiles.length > 0) {
-    lines.push("## Configuration Files\n");
-    for (const cf of scan.configFiles) {
-      lines.push(`- ${cf}`);
-    }
-    lines.push("");
-  } else {
-    lines.push("## Configuration Files\n");
-    lines.push("<!-- TODO: Document configuration files -->\n");
-  }
-
-  if (scan.packageManifest?.scripts) {
-    const hasScripts = Object.keys(scan.packageManifest.scripts).length > 0;
-    if (hasScripts) {
-      lines.push("## Scripts\n");
-      for (const [name, command] of Object.entries(scan.packageManifest.scripts)) {
-        lines.push(`- **${name}**: \`${command}\``);
-      }
-      lines.push("");
-    }
-  }
-
-  if (scan.packageManifest?.dependencies) {
-    const deps = Object.keys(scan.packageManifest.dependencies);
-    if (deps.length > 0) {
-      lines.push("## Dependencies\n");
-      lines.push("<!-- TODO: Document key dependencies and their purpose -->\n");
-    }
-  }
-
-  lines.push("## Development Guidelines\n");
-  lines.push("<!-- TODO: Document development guidelines and conventions -->\n");
-
-  return `${lines.join("\n").trim()}\n`;
-}
-
-/**
- * Generate context.md with LLM enhancement
- */
-async function generateContextWithLLM(scan: ProjectScan): Promise<string> {
-  const logger = getLogger();
-
-  // Build LLM prompt from scan results
-  const scanSummary = `
-Project: ${scan.projectName}
-Entry Points: ${scan.entryPoints.join(", ") || "None detected"}
-Config Files: ${scan.configFiles.join(", ") || "None detected"}
-Total Files: ${scan.fileTree.length}
-Description: ${scan.packageManifest?.description || "Not provided"}
-`;
-
-  const prompt = `
-You are a technical documentation expert. Generate a concise, well-structured context.md file for a software project based on this scan:
-
-${scanSummary}
-
-The context.md should include:
-1. Project overview (name, purpose, key technologies)
-2. Entry points and main modules
-3. Key dependencies and why they're used
-4. Development setup and common commands
-5. Architecture overview (brief)
-6. Development guidelines
-
-Keep it under 2000 tokens. Use markdown formatting. Be specific to the detected stack and structure.
-`;
-
-  try {
-    const result = await _deps.callLLM(prompt);
-    logger.info("init", "Generated context.md with LLM");
-    return result;
-  } catch (err) {
-    logger.warn(
-      "init",
-      `LLM context generation failed, falling back to template: ${err instanceof Error ? err.message : String(err)}`,
-    );
-    return generateContextTemplate(scan);
-  }
-}
-
-/**
- * Generate a minimal package context.md template.
- *
- * @param packagePath - Relative path of the package (e.g. "packages/api")
- */
-export function generatePackageContextTemplate(packagePath: string): string {
-  const packageName = packagePath.split("/").pop() ?? packagePath;
-  return `# ${packageName} — Context
-
-<!-- Package-specific conventions. Root context.md provides shared rules. -->
-
-## Tech Stack
-
-<!-- TODO: Document this package's tech stack -->
-
-## Commands
-
-| Command | Purpose |
-|:--------|:--------|
-| \`bun test\` | Unit tests |
-
-## Development Guidelines
-
-<!-- TODO: Document package-specific guidelines -->
-`;
-}
-
-/**
- * Initialize per-package nax/context.md scaffold.
- *
- * Creates \`<packageDir>/nax/context.md\` with a minimal template.
- * Does not overwrite an existing file unless force is set.
- *
- * @param repoRoot - Absolute path to repo root
- * @param packagePath - Relative path of the package (e.g. "packages/api")
- * @param force - Overwrite existing file
- */
-export async function initPackage(repoRoot: string, packagePath: string, force = false): Promise<void> {
-  const logger = getLogger();
-  const packageDir = join(repoRoot, packagePath);
-  const naxDir = join(packageDir, "nax");
-  const contextPath = join(naxDir, "context.md");
-
-  if (existsSync(contextPath) && !force) {
-    logger.info("init", "Package context.md already exists (use --force to overwrite)", { path: contextPath });
-    return;
-  }
-
-  if (!existsSync(naxDir)) {
-    await mkdir(naxDir, { recursive: true });
-  }
-
-  const content = generatePackageContextTemplate(packagePath);
-  await Bun.write(contextPath, content);
-  logger.info("init", "Created package context.md", { path: contextPath });
-}
-
-/**
- * Initialize context.md for a project
- */
-export async function initContext(projectRoot: string, options: InitContextOptions = {}): Promise<void> {
-  const logger = getLogger();
-  const naxDir = join(projectRoot, "nax");
-  const contextPath = join(naxDir, "context.md");
-
-  // Check if context.md already exists
-  if (existsSync(contextPath) && !options.force) {
-    logger.info("init", "context.md already exists, skipping (use --force to overwrite)", { path: contextPath });
-    return;
-  }
-
-  // Create nax directory if needed
-  if (!existsSync(naxDir)) {
-    await mkdir(naxDir, { recursive: true });
-  }
-
-  // Scan the project
-  const scan = await scanProject(projectRoot);
-
-  // Generate content (template or LLM-enhanced)
-  let content: string;
-  if (options.ai) {
-    content = await generateContextWithLLM(scan);
-  } else {
-    content = generateContextTemplate(scan);
-  }
-
-  // Write context.md
-  await Bun.write(contextPath, content);
-  logger.info("init", "Generated nax/context.md template from project scan", { path: contextPath });
-}

package/src/cli/init-detect.ts

@@ -1,303 +0,0 @@
-/**
- * Project Stack Detection for nax init
- *
- * Scans the project root for stack indicators and builds quality.commands
- * for nax/config.json.
- */
-
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-
-/** Detected project runtime */
-export type Runtime = "bun" | "node" | "unknown";
-
-/** Detected UI framework */
-export type UIFramework = "ink" | "react" | "vue" | "svelte";
-
-/** Full stack info including UI framework and bin detection */
-export interface StackInfo extends ProjectStack {
-  uiFramework?: UIFramework;
-  hasBin?: boolean;
-}
-
-/** Shape of a parsed package.json for detection purposes */
-interface PackageJson {
-  dependencies?: Record<string, string>;
-  devDependencies?: Record<string, string>;
-  peerDependencies?: Record<string, string>;
-  bin?: Record<string, string> | string;
-  workspaces?: string[] | { packages: string[] };
-}
-
-function readPackageJson(projectRoot: string): PackageJson | undefined {
-  const pkgPath = join(projectRoot, "package.json");
-  if (!existsSync(pkgPath)) return undefined;
-  try {
-    return JSON.parse(readFileSync(pkgPath, "utf-8")) as PackageJson;
-  } catch {
-    return undefined;
-  }
-}
-
-function allDeps(pkg: PackageJson): Record<string, string> {
-  return {
-    ...pkg.dependencies,
-    ...pkg.devDependencies,
-    ...pkg.peerDependencies,
-  };
-}
-
-function detectUIFramework(pkg: PackageJson): UIFramework | undefined {
-  const deps = allDeps(pkg);
-  if ("ink" in deps) return "ink";
-  if ("react" in deps || "next" in deps) return "react";
-  if ("vue" in deps || "nuxt" in deps) return "vue";
-  if ("svelte" in deps || "@sveltejs/kit" in deps) return "svelte";
-  return undefined;
-}
-
-function detectHasBin(pkg: PackageJson): boolean {
-  return pkg.bin !== undefined;
-}
-
-/**
- * Detect the project stack including UI framework from package.json.
- */
-export function detectStack(projectRoot: string): StackInfo {
-  const base = detectProjectStack(projectRoot);
-  const pkg = readPackageJson(projectRoot);
-  if (!pkg) return base;
-  return {
-    ...base,
-    uiFramework: detectUIFramework(pkg),
-    hasBin: detectHasBin(pkg) || undefined,
-  };
-}
-
-/** Detected project language */
-export type Language = "typescript" | "python" | "rust" | "go" | "unknown";
-
-/** Detected linter */
-export type Linter = "biome" | "eslint" | "ruff" | "clippy" | "golangci-lint" | "unknown";
-
-/** Detected monorepo tooling */
-export type Monorepo = "turborepo" | "nx" | "pnpm-workspaces" | "bun-workspaces" | "none";
-
-/** Full detected project stack */
-export interface ProjectStack {
-  runtime: Runtime;
-  language: Language;
-  linter: Linter;
-  monorepo: Monorepo;
-}
-
-/** Quality commands derived from stack detection */
-export interface QualityCommands {
-  typecheck?: string;
-  lint?: string;
-  test?: string;
-}
-
-function detectRuntime(projectRoot: string): Runtime {
-  if (existsSync(join(projectRoot, "bun.lockb")) || existsSync(join(projectRoot, "bunfig.toml"))) {
-    return "bun";
-  }
-  if (
-    existsSync(join(projectRoot, "package-lock.json")) ||
-    existsSync(join(projectRoot, "yarn.lock")) ||
-    existsSync(join(projectRoot, "pnpm-lock.yaml"))
-  ) {
-    return "node";
-  }
-  return "unknown";
-}
-
-function detectLanguage(projectRoot: string): Language {
-  if (existsSync(join(projectRoot, "tsconfig.json"))) return "typescript";
-  if (existsSync(join(projectRoot, "pyproject.toml")) || existsSync(join(projectRoot, "setup.py"))) {
-    return "python";
-  }
-  if (existsSync(join(projectRoot, "Cargo.toml"))) return "rust";
-  if (existsSync(join(projectRoot, "go.mod"))) return "go";
-  return "unknown";
-}
-
-function detectLinter(projectRoot: string): Linter {
-  if (existsSync(join(projectRoot, "biome.json")) || existsSync(join(projectRoot, "biome.jsonc"))) {
-    return "biome";
-  }
-  if (
-    existsSync(join(projectRoot, ".eslintrc.json")) ||
-    existsSync(join(projectRoot, ".eslintrc.js")) ||
-    existsSync(join(projectRoot, "eslint.config.js"))
-  ) {
-    return "eslint";
-  }
-  return "unknown";
-}
-
-function detectMonorepo(projectRoot: string): Monorepo {
-  if (existsSync(join(projectRoot, "turbo.json"))) return "turborepo";
-  if (existsSync(join(projectRoot, "nx.json"))) return "nx";
-  if (existsSync(join(projectRoot, "pnpm-workspace.yaml"))) return "pnpm-workspaces";
-  // Bun/npm/yarn workspaces: package.json with "workspaces" field
-  const pkg = readPackageJson(projectRoot);
-  if (pkg?.workspaces) return "bun-workspaces";
-  return "none";
-}
-
-/**
- * Detect the project stack by scanning for indicator files.
- */
-export function detectProjectStack(projectRoot: string): ProjectStack {
-  return {
-    runtime: detectRuntime(projectRoot),
-    language: detectLanguage(projectRoot),
-    linter: detectLinter(projectRoot),
-    monorepo: detectMonorepo(projectRoot),
-  };
-}
-
-function resolveLintCommand(stack: ProjectStack, fallback: string): string {
-  if (stack.linter === "biome") return "biome check .";
-  if (stack.linter === "eslint") return "eslint .";
-  return fallback;
-}
-
-/**
- * Build quality.commands for monorepo orchestrators.
- *
- * Turborepo and Nx support change-aware filtering natively — delegate
- * scoping to the tool rather than nax's smart test runner.
- * pnpm/bun workspaces have no built-in affected detection, so nax's
- * smart runner still applies; commands run across all packages.
- */
-function buildMonorepoQualityCommands(stack: ProjectStack): QualityCommands | null {
-  if (stack.monorepo === "turborepo") {
-    return {
-      typecheck: "turbo run typecheck --filter=...[HEAD~1]",
-      lint: "turbo run lint --filter=...[HEAD~1]",
-      test: "turbo run test --filter=...[HEAD~1]",
-    };
-  }
-  if (stack.monorepo === "nx") {
-    return {
-      typecheck: "nx affected --target=typecheck",
-      lint: "nx affected --target=lint",
-      test: "nx affected --target=test",
-    };
-  }
-  if (stack.monorepo === "pnpm-workspaces") {
-    return {
-      lint: resolveLintCommand(stack, "pnpm run --recursive lint"),
-      test: "pnpm run --recursive test",
-    };
-  }
-  if (stack.monorepo === "bun-workspaces") {
-    return {
-      lint: resolveLintCommand(stack, "bun run lint"),
-      test: "bun run --filter '*' test",
-    };
-  }
-  return null;
-}
-
-/**
- * Build quality.commands from a detected project stack.
- */
-export function buildQualityCommands(stack: ProjectStack): QualityCommands {
-  // Monorepo orchestrators: delegate to the tool's own scoping
-  const monorepoCommands = buildMonorepoQualityCommands(stack);
-  if (monorepoCommands) return monorepoCommands;
-
-  if (stack.runtime === "bun" && stack.language === "typescript") {
-    return {
-      typecheck: "bun run tsc --noEmit",
-      lint: resolveLintCommand(stack, "bun run lint"),
-      test: "bun test",
-    };
-  }
-
-  if (stack.runtime === "node" && stack.language === "typescript") {
-    return {
-      typecheck: "npx tsc --noEmit",
-      lint: resolveLintCommand(stack, "npm run lint"),
-      test: "npm test",
-    };
-  }
-
-  if (stack.language === "python") {
-    return {
-      lint: "ruff check .",
-      test: "pytest",
-    };
-  }
-
-  if (stack.language === "rust") {
-    return {
-      typecheck: "cargo check",
-      lint: "cargo clippy",
-      test: "cargo test",
-    };
-  }
-
-  if (stack.language === "go") {
-    return {
-      typecheck: "go vet ./...",
-      lint: "golangci-lint run",
-      test: "go test ./...",
-    };
-  }
-
-  return {};
-}
-
-function isStackDetected(stack: ProjectStack): boolean {
-  return stack.runtime !== "unknown" || stack.language !== "unknown";
-}
-
-/** Build the acceptance config section from StackInfo, or undefined if not applicable. */
-function buildAcceptanceConfig(stack: StackInfo): { testStrategy: string; testFramework?: string } | undefined {
-  if (stack.uiFramework === "ink") {
-    return { testStrategy: "component", testFramework: "ink-testing-library" };
-  }
-  if (stack.uiFramework === "react") {
-    return { testStrategy: "component", testFramework: "@testing-library/react" };
-  }
-  if (stack.uiFramework === "vue") {
-    return { testStrategy: "component", testFramework: "@testing-library/vue" };
-  }
-  if (stack.uiFramework === "svelte") {
-    return { testStrategy: "component", testFramework: "@testing-library/svelte" };
-  }
-  if (stack.hasBin) {
-    const testFramework = stack.runtime === "bun" ? "bun:test" : "jest";
-    return { testStrategy: "cli", testFramework };
-  }
-  return undefined;
-}
-
-/**
- * Build the full init config object from a detected project stack.
- * Falls back to minimal config when stack is undetected.
- */
-export function buildInitConfig(stack: ProjectStack | StackInfo): object {
-  const stackInfo = stack as StackInfo;
-  const acceptance = buildAcceptanceConfig(stackInfo);
-
-  if (!isStackDetected(stack)) {
-    return acceptance ? { version: 1, acceptance } : { version: 1 };
-  }
-
-  const commands = buildQualityCommands(stack);
-  const hasCommands = Object.keys(commands).length > 0;
-
-  if (!hasCommands && !acceptance) {
-    return { version: 1 };
-  }
-
-  const config: Record<string, unknown> = { version: 1 };
-  if (hasCommands) config.quality = { commands };
-  if (acceptance) config.acceptance = acceptance;
-  return config;
-}