@aprimediet/codewalker 1.0.0 → 1.1.0

package/compat.ts

@@ -1,217 +0,0 @@
-/**
- * Compatibility probe: detect if @aprimediet/minion and @aprimediet/memory are active
- * for this project by reading the shared .pi/<project-id>.md marker and probing
- * global directories.
- */
-
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { CONFIG_DIR_NAME, getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
-
-export interface CompatResult {
-	projectId: string | null;
-	minionActive: boolean;
-	memoryActive: boolean;
-	memoryEntries: number;
-	openTaskCount: number;
-	openTaskSummary: string;
-	memorySummary: string;
-}
-
-/**
- * Walk upward from cwd until we find a dir containing .pi/ or .git/.
- * Return cwd if root is reached without finding either.
- */
-function findProjectRoot(cwd: string): string {
-	let dir = cwd;
-	for (;;) {
-		const piPath = path.join(dir, CONFIG_DIR_NAME);
-		const gitPath = path.join(dir, ".git");
-		if (fs.existsSync(piPath) || fs.existsSync(gitPath)) {
-			return dir;
-		}
-		const parent = path.dirname(dir);
-		if (parent === dir) {
-			// reached filesystem root
-			return cwd;
-		}
-		dir = parent;
-	}
-}
-
-/**
- * Scan <configDir>/*.md files for one with frontmatter containing pi-project: true.
- * Return that file's id: value, or null if none found.
- */
-function readMarkerId(configDir: string): string | null {
-	if (!fs.existsSync(configDir)) {
-		return null;
-	}
-
-	let names: string[];
-	try {
-		names = fs.readdirSync(configDir).filter((n) => n.endsWith(".md"));
-	} catch {
-		return null;
-	}
-
-	for (const name of names) {
-		const file = path.join(configDir, name);
-		try {
-			const content = fs.readFileSync(file, "utf-8");
-			const { frontmatter } = parseFrontmatter<Record<string, string>>(content);
-			if (frontmatter && String(frontmatter["pi-project"]) === "true" && frontmatter.id) {
-				return frontmatter.id;
-			}
-		} catch {
-			// not a valid marker, skip
-		}
-	}
-
-	return null;
-}
-
-/**
- * Extract status and title from task frontmatter.
- * Return { status, title } or null if cannot parse.
- * title may be undefined if missing from frontmatter; callers should supply a fallback.
- */
-function parseTaskMetadata(content: string): { status: string; title: string | undefined } | null {
-	try {
-		const { frontmatter } = parseFrontmatter<Record<string, string>>(content);
-		if (!frontmatter) return null;
-		const status = frontmatter.status || "";
-		const title = frontmatter.title || undefined;
-		if (!status) return null;
-		return { status, title };
-	} catch {
-		return null;
-	}
-}
-
-/**
- * Probe minion integration: check if <globalDir>/tasks/ exists and has open tasks.
- * Return { openTasks, openTaskSummary } or null if minion is not active.
- */
-function probeMinionTasks(globalDir: string): { openTasks: number; openTaskSummary: string } | null {
-	const tasksDir = path.join(globalDir, "tasks");
-
-	// If tasks dir doesn't exist, minion is not active for this project
-	if (!fs.existsSync(tasksDir)) {
-		return null;
-	}
-
-	const OPEN_STATUSES = new Set(["backlog", "todo", "in_progress", "blocked", "review"]);
-	const openTasks: string[] = [];
-
-	try {
-		const names = fs.readdirSync(tasksDir);
-		for (const name of names) {
-			if (!name.endsWith(".md")) continue;
-			const file = path.join(tasksDir, name);
-			try {
-				const content = fs.readFileSync(file, "utf-8");
-				const meta = parseTaskMetadata(content);
-				if (meta && OPEN_STATUSES.has(meta.status)) {
-					const taskTitle = meta.title ?? name.replace(/\.md$/, "");
-					openTasks.push(`${meta.status}: ${taskTitle}`);
-					if (openTasks.length >= 10) break;
-				}
-			} catch {
-				// skip unparseable files
-			}
-		}
-	} catch {
-		// tasks dir exists but is unreadable — still report as active
-	}
-
-	const summary = openTasks.length > 0 ? openTasks.join("\n") : "(no open tasks)";
-	return { openTasks: openTasks.length, openTaskSummary: summary };
-}
-
-/**
- * Probe memory integration: check if <globalDir>/memory/ exists and count entries.
- * Also read MEMORY.md (up to 3000 chars).
- * Return { entries, memorySummary } or null if memory is not active.
- */
-function probeMemoryIntegration(globalDir: string): { entries: number; memorySummary: string } | null {
-	const memoryDir = path.join(globalDir, "memory");
-
-	// If memory dir doesn't exist, memory is not active for this project
-	if (!fs.existsSync(memoryDir)) {
-		return null;
-	}
-
-	// Count entries in memory/entries/
-	let entriesCount = 0;
-	const entriesDir = path.join(memoryDir, "entries");
-	try {
-		if (fs.existsSync(entriesDir)) {
-			const files = fs.readdirSync(entriesDir);
-			entriesCount = files.filter((f) => f.endsWith(".md")).length;
-		}
-	} catch {
-		// entries dir unreadable, but memory is still active
-	}
-
-	// Read MEMORY.md (truncated at 3000 chars)
-	let memorySummary = "";
-	const memoryFile = path.join(memoryDir, "MEMORY.md");
-	try {
-		if (fs.existsSync(memoryFile)) {
-			const content = fs.readFileSync(memoryFile, "utf-8");
-			memorySummary = content.length > 3000 ? content.slice(0, 3000) : content;
-		}
-	} catch {
-		// MEMORY.md unreadable
-	}
-
-	return { entries: entriesCount, memorySummary };
-}
-
-/**
- * Probe compatibility: detect minion and memory integration for the project at cwd.
- * Return detailed status for both extensions in a flat structure.
- */
-export function probeCompat(cwd: string): CompatResult {
-	const root = findProjectRoot(cwd);
-	const configDir = path.join(root, CONFIG_DIR_NAME);
-	const projectId = readMarkerId(configDir);
-
-	// Initialize with defaults
-	const base: CompatResult = {
-		projectId,
-		minionActive: false,
-		memoryActive: false,
-		memoryEntries: 0,
-		openTaskCount: 0,
-		openTaskSummary: "",
-		memorySummary: "",
-	};
-
-	// If no project marker, return defaults
-	if (!projectId) {
-		return base;
-	}
-
-	const piHome = path.dirname(getAgentDir());
-	const globalDir = path.join(piHome, "projects", projectId);
-
-	// Probe minion
-	const minionProbe = probeMinionTasks(globalDir);
-	if (minionProbe) {
-		base.minionActive = true;
-		base.openTaskCount = minionProbe.openTasks;
-		base.openTaskSummary = minionProbe.openTaskSummary;
-	}
-
-	// Probe memory
-	const memoryProbe = probeMemoryIntegration(globalDir);
-	if (memoryProbe) {
-		base.memoryActive = true;
-		base.memoryEntries = memoryProbe.entries;
-		base.memorySummary = memoryProbe.memorySummary;
-	}
-
-	return base;
-}

package/detect.ts

@@ -1,188 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { execSync } from "node:child_process";
-
-export interface TechStack {
-  primary: string[];
-  frameworks: string[];
-  infrastructure: string[];
-  packageManagers: string[];
-}
-
-export interface TechIssue {
-  severity: "error" | "warning" | "info";
-  location: string;
-  message: string;
-}
-
-export interface ProjectStatus {
-  recentCommits: string;
-  hasChangelog: boolean;
-  todoCount: number;
-}
-
-const LANG_FILES: Array<{ file: string; lang: string }> = [
-  { file: "package.json", lang: "Node.js" },
-  { file: "tsconfig.json", lang: "TypeScript" },
-  { file: "requirements.txt", lang: "Python" },
-  { file: "pyproject.toml", lang: "Python" },
-  { file: "go.mod", lang: "Go" },
-  { file: "Cargo.toml", lang: "Rust" },
-  { file: "pom.xml", lang: "Java" },
-  { file: "build.gradle", lang: "Java/Kotlin" },
-  { file: "build.gradle.kts", lang: "Kotlin" },
-  { file: "Gemfile", lang: "Ruby" },
-  { file: "composer.json", lang: "PHP" },
-  { file: "mix.exs", lang: "Elixir" },
-];
-
-const FRAMEWORK_FILES: Array<{ file: string; name: string; infra?: boolean }> = [
-  { file: "next.config.js", name: "Next.js" },
-  { file: "next.config.ts", name: "Next.js" },
-  { file: "next.config.mjs", name: "Next.js" },
-  { file: "vite.config.ts", name: "Vite" },
-  { file: "vite.config.js", name: "Vite" },
-  { file: "nuxt.config.ts", name: "Nuxt.js" },
-  { file: "svelte.config.js", name: "SvelteKit" },
-  { file: "astro.config.mjs", name: "Astro" },
-  { file: "remix.config.js", name: "Remix" },
-  { file: "angular.json", name: "Angular" },
-  { file: "tailwind.config.ts", name: "Tailwind CSS" },
-  { file: "tailwind.config.js", name: "Tailwind CSS" },
-  { file: "biome.json", name: "Biome" },
-  { file: "Dockerfile", name: "Docker", infra: true },
-  { file: "docker-compose.yml", name: "Docker Compose", infra: true },
-  { file: ".github/workflows", name: "GitHub Actions", infra: true },
-  { file: ".gitlab-ci.yml", name: "GitLab CI", infra: true },
-];
-
-const NPM_FRAMEWORKS: Record<string, string> = {
-  react: "React",
-  vue: "Vue",
-  express: "Express",
-  fastify: "Fastify",
-  hono: "Hono",
-  "@nestjs/core": "NestJS",
-  prisma: "Prisma",
-  "@prisma/client": "Prisma",
-  "drizzle-orm": "Drizzle ORM",
-  "@trpc/server": "tRPC",
-};
-
-export function detectTechStack(root: string): TechStack {
-  const primary = new Set<string>();
-  const frameworks = new Set<string>();
-  const infrastructure = new Set<string>();
-  const packageManagers = new Set<string>();
-
-  for (const d of LANG_FILES) {
-    if (fs.existsSync(path.join(root, d.file))) primary.add(d.lang);
-  }
-
-  for (const d of FRAMEWORK_FILES) {
-    if (fs.existsSync(path.join(root, d.file))) {
-      if (d.infra) infrastructure.add(d.name);
-      else frameworks.add(d.name);
-    }
-  }
-
-  if (fs.existsSync(path.join(root, "package-lock.json"))) packageManagers.add("npm");
-  if (fs.existsSync(path.join(root, "yarn.lock"))) packageManagers.add("yarn");
-  if (fs.existsSync(path.join(root, "pnpm-lock.yaml"))) packageManagers.add("pnpm");
-  if (fs.existsSync(path.join(root, "bun.lock"))) packageManagers.add("bun");
-
-  try {
-    const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf-8"));
-    const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
-    for (const [dep, label] of Object.entries(NPM_FRAMEWORKS)) {
-      if (dep in deps) frameworks.add(label);
-    }
-  } catch {
-    /***/
-  }
-
-  return {
-    primary: [...primary],
-    frameworks: [...frameworks],
-    infrastructure: [...infrastructure],
-    packageManagers: [...packageManagers],
-  };
-}
-
-export function detectProjectStatus(root: string): ProjectStatus {
-  let recentCommits = "";
-  try {
-    recentCommits = execSync("git log --oneline -20", {
-      cwd: root,
-      encoding: "utf-8",
-      timeout: 5000,
-    }).trim();
-  } catch {
-    recentCommits = "(git not available or no commits)";
-  }
-
-  const hasChangelog =
-    fs.existsSync(path.join(root, "CHANGELOG.md")) || fs.existsSync(path.join(root, "CHANGELOG"));
-
-  let todoCount = 0;
-  try {
-    const result = execSync(
-      `grep -r --include="*.ts" --include="*.tsx" --include="*.js" --include="*.py" --include="*.go" --include="*.rs" -c "TODO:\\|FIXME:\\|HACK:\\|BUG:" . 2>/dev/null || true`,
-      { cwd: root, encoding: "utf-8", timeout: 10000 }
-    );
-    for (const line of result.split("\n")) {
-      const m = line.match(/:(\d+)$/);
-      if (m) todoCount += parseInt(m[1], 10);
-    }
-  } catch {
-    /***/
-  }
-
-  return { recentCommits, hasChangelog, todoCount };
-}
-
-export function detectTechnicalIssues(root: string): TechIssue[] {
-  const issues: TechIssue[] = [];
-
-  // Invalid tsconfig.json
-  const tsconfigPath = path.join(root, "tsconfig.json");
-  if (fs.existsSync(tsconfigPath)) {
-    try {
-      JSON.parse(fs.readFileSync(tsconfigPath, "utf-8"));
-    } catch (e) {
-      issues.push({
-        severity: "error",
-        location: "tsconfig.json",
-        message: `Invalid JSON: ${e instanceof Error ? e.message : String(e)}`,
-      });
-    }
-  }
-
-  // No test directory or config
-  const testDirs = ["test", "tests", "__tests__", "spec"];
-  const testConfigs = ["vitest.config.ts", "vitest.config.js", "jest.config.ts", "jest.config.js"];
-  const hasTests =
-    testDirs.some((d) => fs.existsSync(path.join(root, d))) ||
-    testConfigs.some((f) => fs.existsSync(path.join(root, f)));
-  if (!hasTests) {
-    issues.push({
-      severity: "warning",
-      location: "root",
-      message: "No test directory or test config detected",
-    });
-  }
-
-  // .env.example without .env
-  if (
-    fs.existsSync(path.join(root, ".env.example")) &&
-    !fs.existsSync(path.join(root, ".env"))
-  ) {
-    issues.push({
-      severity: "info",
-      location: ".env",
-      message: ".env.example exists but .env is missing — check environment setup",
-    });
-  }
-
-  return issues;
-}

package/docs/PRD.md

@@ -1,78 +0,0 @@
-# Product Requirements Document: @aprimediet/codewalker
-
-**Version:** 1.0
-**Date:** 2026-06-25
-**Status:** Draft
-
-## Overview
-Project intelligence extension for the pi coding agent that systematically analyzes any project — tech stack, goals, boundaries, status, technical issues — and produces structured documentation: a **PRD** for humans and **AGENTS.md** / **CLAUDE.md** for coding agents.
-
-## Problem Statement
-Developers using the pi coding agent need a fast, reliable way to understand a project they're working on without manually reading every file. The coding agent also needs structured project instructions to work effectively. Currently there's no automated way to generate this intelligence snapshot and split the content by audience (human vs. agent).
-
-## Goals
-- Identify tech stack (language, frameworks, infrastructure, package manager)
-- Identify project goals and non-goals (interactively when missing)
-- Identify boundaries, scope, and constraints of a project
-- Generate a human-readable PRD.md with product context
-- Generate an engineering-focused AGENTS.md for coding agents
-- Detect companion extensions (minion, memory) and report their state
-- Store the intelligence snapshot to persistent memory for session continuity
-
-## Non-Goals
-- Give suggestions or recommendations on how to improve the project
-- Try to solve or fix technical issues found during analysis
-- Research how to solve technical issues — diagnose only, no solutions
-- Modify project files beyond the documentation it generates
-
-## Target Users
-Developers who use the pi coding agent and need to quickly get up to speed on a project or generate structured documentation for human and agent consumption.
-
-## Key Features
-
-### Tech Stack Detection
-Automatically scan manifest files (package.json, tsconfig.json, requirements.txt, go.mod, Cargo.toml, etc.) and framework configs to identify primary language, frameworks, infrastructure, and package manager.
-
-### Goals & Non-Goals Gathering
-Search README and docs for existing goals. If not found, interactively gather them from the user one question at a time — problem solved, primary users, key features, out-of-scope items, success metrics.
-
-### Boundary Documentation
-Identify key entry points, external services, exposed interfaces (APIs, CLI flags), and technical constraints (runtime version, env vars, OS requirements).
-
-### Project Status Scanning
-Read recent git commits, check for changelogs/roadmaps, scan for TODO/FIXME/HACK/BUG markers in source code.
-
-### Technical Issue Detection
-Detect missing tests, broken env files, invalid configs, and TypeScript strictness issues — report without trying to fix.
-
-### Audience-Split Documentation
-Generate three documents from the same intelligence, each targeted at its audience:
-- **docs/PRD.md** (humans, product) — overview, problem, goals, users, features, success metrics
-- **AGENTS.md** (coding agents, engineering) — tech stack, commands, conventions, technical boundaries, gotchas
-- **CLAUDE.md** (Claude Code) — thin pointer that imports AGENTS.md
-
-### Integration Detection
-Detect active `@aprimediet/minion` and `@aprimediet/memory` extensions via shared `.pi/<id>.md` project marker. Report open tasks and memory entries without modifying any files.
-
-### Memory Storage
-Store the full project intelligence snapshot to `@aprimediet/memory` (scope: project) for persistent recall across sessions.
-
-## Success Metrics
-- User can read a summary of their current project in PRD.md without reading every file manually
-- Coding agent can read specific project instructions in AGENTS.md to work effectively
-- Pi coding agent can learn and store the latest project snapshot in memory for session continuity
-- Documentation is correctly split by audience with no overlap
-
-## Scope & Boundaries
-- **Runtime:** Node.js with ESM modules (`"type": "module"`)
-- **Peer dependency:** `@earendil-works/pi-coding-agent`
-- **No third-party runtime dependencies** — Node built-ins only (`fs`, `path`, `child_process`)
-- **Exposed interface:** single `/learn-this` command registered with the pi extension API
-- **File system operations:** all detection probes are read-only; writes are confined to documentation files (PRD.md, AGENTS.md, CLAUDE.md) and memory storage
-- **Not a CI tool:** runs on-demand via `/learn-this`, not as a background service
-
-## Open Questions
-- Should AGENTS.md be auto-generated or user-edited after generation?
-- How often should memory snapshots be refreshed — on every `/learn-this` run or on demand?
-- Should the extension support non-Node.js projects (Python, Go, Rust) for full PRD/AGENTS.md generation?
-- Should there be a flag to skip interactive questions when running in non-interactive mode?

package/prd.ts

@@ -1,106 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-
-const PRD_CANDIDATES = [
-  "docs/PRD.md",
-  "docs/prd.md",
-  "PRD.md",
-  ".pi/prd.md",
-  "PRODUCT.md",
-  "SPEC.md",
-];
-
-export function findExistingPRD(root: string): string | null {
-  for (const p of PRD_CANDIDATES) {
-    const filePath = path.join(root, p);
-    if (fs.existsSync(filePath)) {
-      return filePath;
-    }
-  }
-
-  // README with a goals/requirements heading
-  const readme = path.join(root, "README.md");
-  if (fs.existsSync(readme)) {
-    try {
-      const text = fs.readFileSync(readme, "utf-8");
-      if (/^##\s+(Goals|Non-Goals|Requirements|Product Requirements)/im.test(text)) {
-        return readme;
-      }
-    } catch {
-      // Ignore read errors
-    }
-  }
-
-  return null;
-}
-
-export function readPRD(filePath: string): string {
-  try {
-    return fs.readFileSync(filePath, "utf-8");
-  } catch {
-    return "";
-  }
-}
-
-export function createPRD(root: string, content: string): string {
-  const outPath = path.join(root, "docs", "PRD.md");
-  fs.mkdirSync(path.dirname(outPath), { recursive: true });
-  fs.writeFileSync(outPath, content, "utf-8");
-  return outPath;
-}
-
-export function prdTemplate(p: {
-  projectName: string;
-  overview: string;
-  problem: string;
-  goals: string[];
-  nonGoals: string[];
-  targetUsers: string;
-  keyFeatures: Array<{ name: string; description: string }>;
-  successMetrics: string[];
-  boundaries: string;
-  openQuestions: string[];
-  date: string;
-}): string {
-  const goalsSection = p.goals.map((g) => `- ${g}`).join("\n");
-  const nonGoalsSection = p.nonGoals.map((g) => `- ${g}`).join("\n");
-  const featuresSection = p.keyFeatures
-    .map((f) => `### ${f.name}\n${f.description}`)
-    .join("\n\n");
-  const metricsSection = p.successMetrics.map((m) => `- ${m}`).join("\n");
-  const questionsSection = p.openQuestions.map((q) => `- ${q}`).join("\n");
-
-  return `# Product Requirements Document: ${p.projectName}
-
-**Version:** 1.0
-**Date:** ${p.date}
-**Status:** Draft
-
-## Overview
-${p.overview}
-
-## Problem Statement
-${p.problem}
-
-## Goals
-${goalsSection}
-
-## Non-Goals
-${nonGoalsSection}
-
-## Target Users
-${p.targetUsers}
-
-## Key Features
-${featuresSection}
-
-## Success Metrics
-${metricsSection}
-
-## Boundaries & Constraints
-${p.boundaries}
-
-## Open Questions
-${questionsSection}
-`;
-}