@cliperhq/cliper 1.0.0

package/src/commands/sync.ts

@@ -0,0 +1,51 @@
+import * as fs from "fs";
+import * as path from "path";
+import chalk from "chalk";
+import ora from "ora";
+import { getCliperDir } from "../scope/config";
+import { initCommand } from "./init";
+
+interface SyncOptions {
+  watch?: boolean;
+}
+
+export async function syncCommand(options: SyncOptions): Promise<void> {
+  const projectRoot = process.cwd();
+  const contextPath = path.join(getCliperDir(projectRoot), "context.md");
+
+  if (!fs.existsSync(contextPath)) {
+    console.log(chalk.yellow("\n  No context doc found. Run cliper init first.\n"));
+    process.exit(1);
+  }
+
+  if (options.watch) {
+    console.log(chalk.cyan("\n  Watching for git changes... (Ctrl+C to stop)\n"));
+    let lastHash = "";
+
+    const check = async () => {
+      try {
+        const { default: simpleGit } = await import("simple-git");
+        const git = simpleGit(projectRoot);
+        const log = await git.log({ maxCount: 1 });
+        const currentHash = log.latest?.hash ?? "";
+
+        if (currentHash && currentHash !== lastHash) {
+          if (lastHash !== "") {
+            console.log(chalk.yellow(`\n  New commit detected: ${currentHash.slice(0, 7)} — refreshing context...\n`));
+            await initCommand({ path: projectRoot });
+          }
+          lastHash = currentHash;
+        }
+      } catch {
+        // silently skip
+      }
+    };
+
+    await check();
+    setInterval(check, 10000); // Check every 10 seconds
+  } else {
+    const spinner = ora("Syncing context document...").start();
+    spinner.stop();
+    await initCommand({ path: projectRoot });
+  }
+}

package/src/context/builder.ts

@@ -0,0 +1,178 @@
+import { FileContent } from "../scanner/fileContent";
+import { GitContext } from "../scanner/gitContext";
+import { ResolvedReference } from "../resolver/urlFetcher";
+import { Gap } from "../gaps/detector";
+
+export interface ContextDocOptions {
+  projectRoot: string;
+  projectName: string;
+  activeScope: string[];
+  watchedScope: string[];
+  fileTree: string;
+  files: FileContent[];
+  gitContext: GitContext;
+  references: ResolvedReference[];
+  gaps: Gap[];
+  generatedAt: string;
+  dependencyMap: string;
+}
+
+const DIVIDER = "━".repeat(50);
+
+function formatGitContext(git: GitContext): string {
+  if (!git.isGitRepo) return "Not a git repository.";
+
+  const lines: string[] = [];
+  lines.push(`Branch:        ${git.branch}`);
+
+  if (git.lastCommit) {
+    lines.push(`Last commit:   ${git.lastCommit.hash} — ${git.lastCommit.message} (${git.lastCommit.timeAgo})`);
+    lines.push(`Author:        ${git.lastCommit.author}`);
+  }
+
+  if (git.uncommittedChanges.length > 0) {
+    lines.push(`\nUncommitted changes (${git.uncommittedChanges.length} files):`);
+    for (const f of git.uncommittedChanges.slice(0, 10)) {
+      lines.push(`  - ${f}`);
+    }
+  }
+
+  if (git.recentCommits.length > 0) {
+    lines.push("\nRecent commits:");
+    for (const c of git.recentCommits) {
+      lines.push(`  ${c.hash} — ${c.message}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function formatFileContents(files: FileContent[]): string {
+  if (files.length === 0) return "No files in scope.";
+
+  return files
+    .map((f) => {
+      const ext = f.relativePath.split(".").pop() ?? "";
+      const truncatedNote = f.truncated ? "\n[... truncated ...]" : "";
+      return `### ${f.relativePath}\n\`\`\`${ext}\n${f.content}${truncatedNote}\n\`\`\``;
+    })
+    .join("\n\n");
+}
+
+function formatReferences(refs: ResolvedReference[]): string {
+  const fetched = refs.filter((r) => r.status === "fetched");
+  const failed = refs.filter((r) => r.status === "failed");
+
+  const lines: string[] = [];
+
+  if (fetched.length === 0 && failed.length === 0) {
+    return "No external references found in markdown files.";
+  }
+
+  for (const ref of fetched) {
+    lines.push(`#### ${ref.url}`);
+    lines.push(`Source: ${ref.source}`);
+    lines.push(`\n${ref.content}\n`);
+  }
+
+  if (failed.length > 0) {
+    lines.push("\n**Could not fetch:**");
+    for (const ref of failed) {
+      lines.push(`  - ${ref.url} (${ref.reason})`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function formatGaps(gaps: Gap[]): string {
+  if (gaps.length === 0) return "No significant gaps detected.";
+
+  const bySeverity = {
+    high: gaps.filter((g) => g.severity === "high"),
+    medium: gaps.filter((g) => g.severity === "medium"),
+    low: gaps.filter((g) => g.severity === "low"),
+  };
+
+  const lines: string[] = [];
+
+  if (bySeverity.high.length > 0) {
+    lines.push("**HIGH PRIORITY**");
+    for (const g of bySeverity.high) {
+      lines.push(`  ⚠️  [${g.file}${g.line ? `:${g.line}` : ""}] ${g.description}`);
+    }
+  }
+
+  if (bySeverity.medium.length > 0) {
+    lines.push("\n**MEDIUM PRIORITY**");
+    for (const g of bySeverity.medium) {
+      lines.push(`  ⚡ [${g.file}${g.line ? `:${g.line}` : ""}] ${g.description}`);
+    }
+  }
+
+  if (bySeverity.low.length > 0) {
+    lines.push("\n**LOW PRIORITY**");
+    for (const g of bySeverity.low.slice(0, 10)) {
+      lines.push(`  ℹ️  [${g.file}${g.line ? `:${g.line}` : ""}] ${g.description}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+export function buildContextDoc(opts: ContextDocOptions): string {
+  const scopeSummary = [
+    ...opts.activeScope.map((s) => `${s} (active)`),
+    ...opts.watchedScope.map((s) => `${s} (watched)`),
+  ].join(", ") || "auto-detected";
+
+  return `${DIVIDER}
+CLIPER CONTEXT DOCUMENT
+${DIVIDER}
+PROJECT:      ${opts.projectName}
+GENERATED:    ${opts.generatedAt}
+BRANCH:       ${opts.gitContext.branch || "unknown"}
+SCOPED TO:    ${scopeSummary}
+${DIVIDER}
+
+## FOLDER STRUCTURE
+
+\`\`\`
+${opts.fileTree}
+\`\`\`
+
+${DIVIDER}
+
+## GIT CONTEXT
+
+${formatGitContext(opts.gitContext)}
+
+${DIVIDER}
+
+## DEPENDENCY MAP
+
+${opts.dependencyMap}
+
+${DIVIDER}
+
+## KEY FILES
+
+${formatFileContents(opts.files)}
+
+${DIVIDER}
+
+## BLOCKED REFERENCES (fetched locally)
+
+${formatReferences(opts.references)}
+
+${DIVIDER}
+
+## DETECTED GAPS
+
+${formatGaps(opts.gaps)}
+
+${DIVIDER}
+END OF CLIPER CONTEXT DOCUMENT
+${DIVIDER}
+`;
+}

package/src/gaps/detector.ts

@@ -0,0 +1,131 @@
+import * as fs from "fs";
+import * as path from "path";
+import { FileContent } from "../scanner/fileContent";
+
+export interface Gap {
+  type: "undocumented_function" | "missing_env_var" | "todo_fixme" | "implicit_dependency" | "stale_reference";
+  file: string;
+  line?: number;
+  description: string;
+  severity: "high" | "medium" | "low";
+}
+
+// Detect functions/classes with no JSDoc or comments above them
+function detectUndocumentedCode(file: FileContent): Gap[] {
+  const gaps: Gap[] = [];
+  const lines = file.content.split("\n");
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    const prevLine = i > 0 ? lines[i - 1].trim() : "";
+
+    const isFunctionOrClass =
+      /^(export\s+)?(async\s+)?function\s+\w+/.test(line) ||
+      /^(export\s+)?(default\s+)?class\s+\w+/.test(line) ||
+      /^(export\s+)?const\s+\w+\s*=\s*(async\s+)?\(/.test(line);
+
+    if (isFunctionOrClass) {
+      const hasComment =
+        prevLine.startsWith("//") ||
+        prevLine.startsWith("*") ||
+        prevLine.startsWith("/*") ||
+        prevLine.startsWith("/**") ||
+        prevLine === "*/";
+
+      if (!hasComment) {
+        gaps.push({
+          type: "undocumented_function",
+          file: file.relativePath,
+          line: i + 1,
+          description: `Undocumented: "${line.slice(0, 60)}..."`,
+          severity: "low",
+        });
+      }
+    }
+  }
+
+  return gaps.slice(0, 5); // Cap at 5 per file to avoid noise
+}
+
+// Detect TODO/FIXME/HACK comments
+function detectTodos(file: FileContent): Gap[] {
+  const gaps: Gap[] = [];
+  const lines = file.content.split("\n");
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (/TODO|FIXME|HACK|XXX|TEMP/i.test(line)) {
+      gaps.push({
+        type: "todo_fixme",
+        file: file.relativePath,
+        line: i + 1,
+        description: line.trim().slice(0, 100),
+        severity: /FIXME|HACK/i.test(line) ? "high" : "medium",
+      });
+    }
+  }
+
+  return gaps;
+}
+
+// Detect env vars referenced in code but not in .env.example
+function detectMissingEnvVars(
+  files: FileContent[],
+  projectRoot: string
+): Gap[] {
+  const gaps: Gap[] = [];
+  const envExamplePath = path.join(projectRoot, ".env.example");
+
+  let knownEnvVars: Set<string> = new Set();
+  if (fs.existsSync(envExamplePath)) {
+    const content = fs.readFileSync(envExamplePath, "utf-8");
+    for (const line of content.split("\n")) {
+      const match = line.match(/^([A-Z_][A-Z0-9_]*)\s*=/);
+      if (match) knownEnvVars.add(match[1]);
+    }
+  }
+
+  const ENV_REGEX = /process\.env\.([A-Z_][A-Z0-9_]*)/g;
+
+  for (const file of files) {
+    let match;
+    while ((match = ENV_REGEX.exec(file.content)) !== null) {
+      const varName = match[1];
+      if (!knownEnvVars.has(varName)) {
+        gaps.push({
+          type: "missing_env_var",
+          file: file.relativePath,
+          description: `process.env.${varName} used but not in .env.example`,
+          severity: "high",
+        });
+      }
+    }
+  }
+
+  // Deduplicate by description
+  const seen = new Set<string>();
+  return gaps.filter((g) => {
+    if (seen.has(g.description)) return false;
+    seen.add(g.description);
+    return true;
+  });
+}
+
+export function detectGaps(files: FileContent[], projectRoot: string): Gap[] {
+  const gaps: Gap[] = [];
+
+  for (const file of files) {
+    if (file.truncated) continue;
+    const ext = path.extname(file.relativePath);
+    if ([".ts", ".tsx", ".js", ".jsx"].includes(ext)) {
+      gaps.push(...detectUndocumentedCode(file));
+      gaps.push(...detectTodos(file));
+    }
+  }
+
+  gaps.push(...detectMissingEnvVars(files, projectRoot));
+
+  // Sort by severity
+  const order: Record<string, number> = { high: 0, medium: 1, low: 2 };
+  return gaps.sort((a, b) => order[a.severity] - order[b.severity]);
+}

package/src/index.ts

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+
+import { program } from "commander";
+import { initCommand } from "./commands/init";
+import { syncCommand } from "./commands/sync";
+import { scopeCommand } from "./commands/scope";
+import { statusCommand } from "./commands/status";
+import { exportCommand } from "./commands/export";
+import { analyzeCommand } from "./commands/analyze";
+const { version } = require("../package.json");
+
+program
+  .name("cliper")
+  .description("AI context doc generator for developers")
+  .version(version);
+
+program
+  .command("init")
+  .description("Scan project and generate context document")
+  .option("-p, --path <path>", "Project root path", process.cwd())
+  .option("--max-file-size <kb>", "Max file size to include in KB", (v) => parseInt(v), 50)
+  .action(initCommand);
+
+program
+  .command("sync")
+  .description("Refresh stale sections of the context document")
+  .option("--watch", "Auto-refresh on git events")
+  .action(syncCommand);
+
+program
+  .command("scope")
+  .description("Manage active scope")
+  .argument("<action>", "add | remove | watch | list")
+  .argument("[path]", "File or directory path")
+  .action(scopeCommand);
+
+program
+  .command("status")
+  .description("Show what is fresh, stale, and in scope")
+  .action(statusCommand);
+
+program
+  .command("export")
+  .description("Print context doc to stdout")
+  .option("--format <format>", "Output format: md or txt", "md")
+  .action(exportCommand);
+
+program
+  .command("analyze")
+  .description("Analyze context doc and generate optimized AI prompt")
+  .requiredOption("--model <model>", "Target model: claude or chatgpt")
+  .action(analyzeCommand);
+
+program.parse(process.argv);

package/src/resolver/urlFetcher.ts

@@ -0,0 +1,119 @@
+import * as fs from "fs";
+import * as path from "path";
+import { glob } from "glob";
+
+export interface ResolvedReference {
+  url: string;
+  source: string; // which file it was found in
+  status: "fetched" | "blocked" | "failed" | "skipped";
+  content?: string;
+  reason?: string;
+}
+
+const URL_REGEX = /https?:\/\/[^\s\)\]\>"']+/g;
+
+const ALWAYS_BLOCKED_PATTERNS = [
+  /robots\.txt/i,
+  /localhost/i,
+  /127\.0\.0\.1/,
+  /internal\./,
+  /\.local\//,
+];
+
+const SKIP_EXTENSIONS = [".png", ".jpg", ".jpeg", ".gif", ".pdf", ".zip"];
+
+function shouldSkip(url: string): boolean {
+  if (SKIP_EXTENSIONS.some((ext) => url.toLowerCase().includes(ext))) return true;
+  if (url.includes("shields.io")) return true;
+  if (url.includes("badge")) return true;
+  if (url.includes("github.com/") && url.includes("/actions/")) return true;
+  return false;
+}
+
+async function fetchUrl(url: string): Promise<{ ok: boolean; content?: string; reason?: string }> {
+  try {
+    const { default: fetch } = await import("node-fetch");
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 8000);
+
+    const res = await fetch(url, {
+      signal: controller.signal as any,
+      headers: {
+        "User-Agent": "Cliper/1.0 context-doc-generator",
+      },
+    });
+
+    clearTimeout(timeout);
+
+    if (!res.ok) {
+      return { ok: false, reason: `HTTP ${res.status}` };
+    }
+
+    const contentType = res.headers.get("content-type") ?? "";
+    if (!contentType.includes("text") && !contentType.includes("json")) {
+      return { ok: false, reason: "Non-text content" };
+    }
+
+    const text = await res.text();
+
+    // Strip HTML tags for cleaner context
+    const cleaned = text
+      .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, "")
+      .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "")
+      .replace(/<[^>]+>/g, " ")
+      .replace(/\s+/g, " ")
+      .trim()
+      .slice(0, 3000); // Cap at 3000 chars per URL
+
+    return { ok: true, content: cleaned };
+  } catch (err: any) {
+    return { ok: false, reason: err.message ?? "Network error" };
+  }
+}
+
+export async function resolveBlockedReferences(
+  projectRoot: string
+): Promise<ResolvedReference[]> {
+  const markdownFiles = await glob("**/*.md", {
+    cwd: projectRoot,
+    ignore: ["node_modules/**", ".git/**", "dist/**"],
+  });
+
+  const urlMap = new Map<string, string>(); // url -> source file
+
+  for (const mdFile of markdownFiles) {
+    const fullPath = path.join(projectRoot, mdFile);
+    try {
+      const content = fs.readFileSync(fullPath, "utf-8");
+      const matches = content.match(URL_REGEX) ?? [];
+      for (const url of matches) {
+        if (!urlMap.has(url)) urlMap.set(url, mdFile);
+      }
+    } catch {
+      // Skip unreadable files
+    }
+  }
+
+  const results: ResolvedReference[] = [];
+
+  for (const [url, source] of urlMap) {
+    if (shouldSkip(url)) {
+      results.push({ url, source, status: "skipped", reason: "Badge/asset URL" });
+      continue;
+    }
+
+    if (ALWAYS_BLOCKED_PATTERNS.some((p) => p.test(url))) {
+      results.push({ url, source, status: "blocked", reason: "Internal/local URL" });
+      continue;
+    }
+
+    const result = await fetchUrl(url);
+    if (result.ok && result.content) {
+      results.push({ url, source, status: "fetched", content: result.content });
+    } else {
+      results.push({ url, source, status: "failed", reason: result.reason });
+    }
+  }
+
+  return results;
+}