@repolensai/cli 0.1.1

package/lib/history-metadata-shared.d.ts

@@ -0,0 +1,18 @@
+export interface HistoryReportMetadata {
+  kind: string;
+  generatedAt: string | null;
+  sinceRef: string | null;
+  scopePath: string | null;
+  pathKind: string | null;
+  summary: string | null;
+  whyChanged: string | null;
+  relatedFiles: string[];
+  commitThemes: string[];
+  topOwners: string[];
+  readingOrder: string[];
+  query?: string | null;
+  traceMatches?: string[];
+}
+
+export function buildHistoryReportMetadata(kind: string, payload: Record<string, unknown>): HistoryReportMetadata;
+export function buildHistoryMetadataText(metadata: HistoryReportMetadata): string;

package/lib/history-metadata-shared.mjs

@@ -0,0 +1,87 @@
+export function buildHistoryReportMetadata(kind, payload) {
+  const base = {
+    kind,
+    generatedAt: readString(payload?.generatedAt),
+    sinceRef: readString(payload?.sinceRef),
+    scopePath: readString(payload?.targetPath),
+    pathKind: readString(payload?.pathKind),
+    summary: readString(payload?.summary) ?? buildDefaultSummary(kind, payload),
+    whyChanged: readString(payload?.whyChanged),
+    relatedFiles: readStringArray(payload?.relatedFiles),
+    commitThemes: readCommitThemes(payload?.commitThemes).map((theme) => theme.label),
+    topOwners: readOwners(payload?.owners).slice(0, 3).map((owner) => owner.author),
+    readingOrder: readReadingOrder(payload?.readingOrder).slice(0, 5).map((entry) => entry.path),
+  };
+
+  if (kind === "trace") {
+    return {
+      ...base,
+      query: readString(payload?.query),
+      traceMatches: readTraceMatches(payload?.matches).slice(0, 5).map((match) => match.filePath),
+    };
+  }
+
+  return base;
+}
+
+export function buildHistoryMetadataText(metadata) {
+  const sections = [
+    metadata.kind ? `Kind: ${metadata.kind}` : null,
+    metadata.query ? `Query: ${metadata.query}` : null,
+    metadata.scopePath ? `Scope: ${metadata.scopePath}${metadata.pathKind ? ` (${metadata.pathKind})` : ""}` : null,
+    metadata.summary ? `Summary: ${metadata.summary}` : null,
+    metadata.whyChanged ? `Why changed: ${metadata.whyChanged}` : null,
+    metadata.commitThemes?.length ? `Themes: ${metadata.commitThemes.join(", ")}` : null,
+    metadata.topOwners?.length ? `Owners: ${metadata.topOwners.join(", ")}` : null,
+    metadata.readingOrder?.length ? `Reading order: ${metadata.readingOrder.join(" -> ")}` : null,
+    metadata.traceMatches?.length ? `Matches: ${metadata.traceMatches.join(", ")}` : null,
+  ].filter(Boolean);
+
+  return sections.join("\n");
+}
+
+function buildDefaultSummary(kind, payload) {
+  switch (kind) {
+    case "trace":
+      return readString(payload?.query) ? `Likely matches for ${payload.query}.` : "Likely file matches.";
+    case "hotspots":
+      return readHotspotFiles(payload?.files).length > 0
+        ? `${readHotspotFiles(payload.files).length} hotspot files were ranked.`
+        : "Hotspot file ranking.";
+    case "ownership":
+      return readString(payload?.targetPath) ? `Ownership summary for ${payload.targetPath}.` : "Ownership summary.";
+    case "start-here":
+      return readString(payload?.targetPath) ? `Start-here summary for ${payload.targetPath}.` : "Start-here summary.";
+    case "evolution":
+    default:
+      return readString(payload?.targetPath) ? `Evolution summary for ${payload.targetPath}.` : "Evolution summary.";
+  }
+}
+
+function readString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : null;
+}
+
+function readStringArray(value) {
+  return Array.isArray(value) ? value.map((entry) => (typeof entry === "string" ? entry : "")).filter(Boolean) : [];
+}
+
+function readOwners(value) {
+  return Array.isArray(value) ? value.filter((entry) => entry && typeof entry.author === "string") : [];
+}
+
+function readReadingOrder(value) {
+  return Array.isArray(value) ? value.filter((entry) => entry && typeof entry.path === "string") : [];
+}
+
+function readCommitThemes(value) {
+  return Array.isArray(value) ? value.filter((entry) => entry && typeof entry.label === "string") : [];
+}
+
+function readTraceMatches(value) {
+  return Array.isArray(value) ? value.filter((entry) => entry && typeof entry.filePath === "string") : [];
+}
+
+function readHotspotFiles(value) {
+  return Array.isArray(value) ? value.filter((entry) => entry && typeof entry.filePath === "string") : [];
+}

package/lib/history-report-shared.d.ts

@@ -0,0 +1,6 @@
+export type HistoryReportKind = "evolution" | "hotspots" | "ownership" | "start-here" | "trace";
+
+export function buildHistoryReportMarkdown(kind: HistoryReportKind, payload: Record<string, unknown>): string;
+export function buildHistoryReportTitle(kind: HistoryReportKind, payload: Record<string, unknown>): string;
+export function buildHistoryReportSummary(kind: HistoryReportKind, payload: Record<string, unknown>): string;
+export function collectHistoryReportRelatedFiles(kind: HistoryReportKind, payload: Record<string, unknown>): string[];

package/lib/history-report-shared.mjs

@@ -0,0 +1,410 @@
+export function buildHistoryReportMarkdown(kind, payload) {
+  switch (kind) {
+    case "evolution":
+      return buildEvolutionMarkdown(payload);
+    case "hotspots":
+      return buildHotspotsMarkdown(payload);
+    case "ownership":
+      return buildOwnershipMarkdown(payload);
+    case "start-here":
+      return buildStartHereMarkdown(payload);
+    case "trace":
+      return buildTraceMarkdown(payload);
+    default:
+      return "# RepoLens History Report\n";
+  }
+}
+
+export function buildHistoryReportTitle(kind, payload) {
+  switch (kind) {
+    case "evolution":
+      return `Evolution: ${stringOrFallback(payload?.targetPath, "Unknown path")}`;
+    case "hotspots":
+      return `Hotspots since ${stringOrFallback(payload?.sinceRef, "recent history")}`;
+    case "ownership":
+      return `Ownership: ${stringOrFallback(payload?.targetPath, "Unknown path")}`;
+    case "start-here":
+      return `Start Here: ${stringOrFallback(payload?.targetPath, "Unknown path")}`;
+    case "trace":
+      return `Trace: ${stringOrFallback(payload?.query, "Unknown query")}`;
+    default:
+      return "History Report";
+  }
+}
+
+export function buildHistoryReportSummary(kind, payload) {
+  switch (kind) {
+    case "evolution":
+      return `${numberOrZero(payload?.commitCount)} commits across ${arrayLength(payload?.authors)} authors for ${stringOrFallback(payload?.targetPath, "this path")}.`;
+    case "hotspots":
+      return `${arrayLength(payload?.files)} hotspot files ranked from recent churn${payload?.sinceRef ? ` since ${payload.sinceRef}` : ""}.`;
+    case "ownership":
+      return `${arrayLength(payload?.owners)} owners summarized for ${stringOrFallback(payload?.targetPath, "this path")}.`;
+    case "start-here":
+      return `${numberOrZero(payload?.trackedFileCount)} tracked files and ${arrayLength(payload?.owners)} owners summarized for ${stringOrFallback(payload?.targetPath, "this area")}.`;
+    case "trace":
+      return `${arrayLength(payload?.matches)} likely matches for ${stringOrFallback(payload?.query, "this query")}.`;
+    default:
+      return "History-aware repo report.";
+  }
+}
+
+export function collectHistoryReportRelatedFiles(kind, payload) {
+  switch (kind) {
+    case "evolution":
+    case "ownership":
+      return dedupeStrings([
+        readString(payload?.targetPath),
+        ...readRenameHistory(payload?.renameHistory).flatMap((entry) => [entry.fromPath, entry.toPath]),
+        ...readFileStats(payload?.fileStats).map((entry) => entry.filePath),
+      ]);
+    case "start-here":
+      return dedupeStrings([
+        readString(payload?.targetPath),
+        ...readHotspotFiles(payload?.hotspotFiles).map((entry) => entry.filePath),
+        ...readDirectoryStats(payload?.directoryStats).map((entry) => entry.directoryPath),
+        ...readReadingOrder(payload?.readingOrder).map((entry) => entry.path),
+        ...readRenameHistory(payload?.renameHistory).flatMap((entry) => [entry.fromPath, entry.toPath]),
+      ]);
+    case "hotspots":
+      return dedupeStrings(readHotspotFiles(payload?.files).map((entry) => entry.filePath));
+    case "trace":
+      return dedupeStrings(readTraceMatches(payload?.matches).map((entry) => entry.filePath));
+    default:
+      return [];
+  }
+}
+
+function buildEvolutionMarkdown(payload) {
+  const sections = [
+    "# RepoLens Evolution Report",
+    "",
+    `- Repo root: \`${stringOrFallback(payload?.repoRoot, "unknown")}\``,
+    `- Branch: \`${stringOrFallback(payload?.branch, "unknown")}\``,
+    `- Target path: \`${stringOrFallback(payload?.targetPath, "unknown")}\``,
+    `- Scope: ${stringOrFallback(payload?.pathKind, "unknown")}`,
+    `- Since: \`${stringOrFallback(payload?.sinceRef, "full available history")}\``,
+    `- Tracked files in scope: ${numberOrZero(payload?.trackedFileCount)}`,
+    `- Generated at: ${stringOrFallback(payload?.generatedAt, "unknown")}`,
+    "",
+    "## Why This Area Changed",
+    stringOrFallback(payload?.whyChanged, "No why-changed summary was derived."),
+    "",
+    "## Commit Themes",
+    readCommitThemes(payload?.commitThemes).length > 0
+      ? readCommitThemes(payload?.commitThemes)
+          .map((theme) => `- ${theme.label}: ${theme.commits} commits${theme.examples.length > 0 ? ` (${theme.examples.join("; ")})` : ""}`)
+          .join("\n")
+      : "- No recurring commit themes found.",
+    "",
+    "## Recent Commits",
+    readCommits(payload?.commits).length > 0
+      ? readCommits(payload?.commits)
+          .map((commit) => `- ${commit.date} \`${shortSha(commit.sha)}\` ${commit.author} — ${commit.subject}`)
+          .join("\n")
+      : "- No history found for this path.",
+    "",
+    "## Authors",
+    readAuthors(payload?.authors).length > 0
+      ? readAuthors(payload?.authors).map((author) => `- ${author.author}: ${author.commits} commits`).join("\n")
+      : "- No authors found.",
+    "",
+    "## Touched Files",
+    readFileStats(payload?.fileStats).length > 0
+      ? readFileStats(payload?.fileStats)
+          .map((file) => `- \`${file.filePath}\` — ${file.touchedCommits} commits, +${file.additions}/-${file.deletions}`)
+          .join("\n")
+      : "- No file stats found.",
+    "",
+    "## Subdirectories",
+    readDirectoryStats(payload?.directoryStats).length > 0
+      ? readDirectoryStats(payload?.directoryStats)
+          .map((directory) => `- \`${directory.directoryPath}\` — ${directory.fileCount} files, ${directory.touchedCommits} commits, score ${directory.score}`)
+          .join("\n")
+      : "- No subdirectory summaries found.",
+    "",
+    "## Rename / Move History",
+    readRenameHistory(payload?.renameHistory).length > 0
+      ? readRenameHistory(payload?.renameHistory)
+          .map((entry) => `- ${shortSha(entry.commit)}: \`${entry.fromPath}\` -> \`${entry.toPath}\``)
+          .join("\n")
+      : "- No rename or move history found.",
+  ];
+
+  return `${sections.join("\n")}\n`;
+}
+
+function buildHotspotsMarkdown(payload) {
+  const sections = [
+    "# RepoLens Hotspots Report",
+    "",
+    `- Repo root: \`${stringOrFallback(payload?.repoRoot, "unknown")}\``,
+    `- Branch: \`${stringOrFallback(payload?.branch, "unknown")}\``,
+    `- Since: \`${stringOrFallback(payload?.sinceRef, "recent history")}\``,
+    `- Generated at: ${stringOrFallback(payload?.generatedAt, "unknown")}`,
+    "",
+    "## Hotspots",
+    readHotspotFiles(payload?.files).length > 0
+      ? readHotspotFiles(payload?.files)
+          .map((file, index) => `${index + 1}. \`${file.filePath}\` — score ${file.score}, ${file.touchedCommits} commits, +${file.additions}/-${file.deletions}`)
+          .join("\n")
+      : "- No hotspot files found.",
+  ];
+
+  return `${sections.join("\n")}\n`;
+}
+
+function buildOwnershipMarkdown(payload) {
+  const sections = [
+    "# RepoLens Ownership Report",
+    "",
+    `- Repo root: \`${stringOrFallback(payload?.repoRoot, "unknown")}\``,
+    `- Branch: \`${stringOrFallback(payload?.branch, "unknown")}\``,
+    `- Target path: \`${stringOrFallback(payload?.targetPath, "unknown")}\``,
+    `- Scope: ${stringOrFallback(payload?.pathKind, "unknown")}`,
+    `- Since: \`${stringOrFallback(payload?.sinceRef, "full available history")}\``,
+    `- Tracked files in scope: ${numberOrZero(payload?.trackedFileCount)}`,
+    `- Generated at: ${stringOrFallback(payload?.generatedAt, "unknown")}`,
+    "",
+    "## Owners",
+    readOwners(payload?.owners).length > 0
+      ? readOwners(payload?.owners)
+          .map((owner) => `- ${owner.author}: ${owner.commits} commits, last touched ${owner.lastTouchedAt} — ${owner.lastSubject}`)
+          .join("\n")
+      : "- No ownership history found.",
+    "",
+    "## Current Line Ownership",
+    readBlameOwners(payload?.blameOwners).length > 0
+      ? readBlameOwners(payload?.blameOwners)
+          .map((owner) => `- ${owner.author}: ${owner.lines} current lines across ${owner.commits} commits`)
+          .join("\n")
+      : "- No blame-based ownership available for this path.",
+    "",
+    "## File Ownership Map",
+    readFileOwners(payload?.fileOwners).length > 0
+      ? readFileOwners(payload?.fileOwners)
+          .map((owner) => `- \`${owner.filePath}\` — ${owner.primaryOwner} (${owner.ownerCommits} commits, ${owner.touchedCommits} touches)`)
+          .join("\n")
+      : "- No file-level ownership map found.",
+    "",
+    "## Rename / Move History",
+    readRenameHistory(payload?.renameHistory).length > 0
+      ? readRenameHistory(payload?.renameHistory)
+          .map((entry) => `- ${shortSha(entry.commit)}: \`${entry.fromPath}\` -> \`${entry.toPath}\``)
+          .join("\n")
+      : "- No rename or move history found.",
+  ];
+
+  return `${sections.join("\n")}\n`;
+}
+
+function buildStartHereMarkdown(payload) {
+  const sections = [
+    "# RepoLens Start Here Report",
+    "",
+    `- Repo root: \`${stringOrFallback(payload?.repoRoot, "unknown")}\``,
+    `- Branch: \`${stringOrFallback(payload?.branch, "unknown")}\``,
+    `- Target path: \`${stringOrFallback(payload?.targetPath, "unknown")}\``,
+    `- Scope: ${stringOrFallback(payload?.pathKind, "unknown")}`,
+    `- Since: \`${stringOrFallback(payload?.sinceRef, "full available history")}\``,
+    `- Tracked files in scope: ${numberOrZero(payload?.trackedFileCount)}`,
+    `- Generated at: ${stringOrFallback(payload?.generatedAt, "unknown")}`,
+    "",
+    "## Why Start Here",
+    stringOrFallback(payload?.summary, "Start with the highest-signal files and owners in this area."),
+    "",
+    "## Why This Area Changed",
+    stringOrFallback(payload?.whyChanged, "No why-changed summary was derived."),
+    "",
+    "## Commit Themes",
+    readCommitThemes(payload?.commitThemes).length > 0
+      ? readCommitThemes(payload?.commitThemes)
+          .map((theme) => `- ${theme.label}: ${theme.commits} commits${theme.examples.length > 0 ? ` (${theme.examples.join("; ")})` : ""}`)
+          .join("\n")
+      : "- No recurring commit themes found.",
+    "",
+    "## Reading Order",
+    readReadingOrder(payload?.readingOrder).length > 0
+      ? readReadingOrder(payload?.readingOrder)
+          .map((entry, index) => `${index + 1}. \`${entry.path}\` — ${entry.reason}`)
+          .join("\n")
+      : "- No reading order was derived.",
+    "",
+    "## Hot Files",
+    readHotspotFiles(payload?.hotspotFiles).length > 0
+      ? readHotspotFiles(payload?.hotspotFiles)
+          .map((file) => `- \`${file.filePath}\` — score ${file.score}, ${file.touchedCommits} commits, +${file.additions}/-${file.deletions}`)
+          .join("\n")
+      : "- No hotspot files found in this scope.",
+    "",
+    "## Subdirectories",
+    readDirectoryStats(payload?.directoryStats).length > 0
+      ? readDirectoryStats(payload?.directoryStats)
+          .map((directory) => `- \`${directory.directoryPath}\` — ${directory.fileCount} files, ${directory.touchedCommits} commits, score ${directory.score}`)
+          .join("\n")
+      : "- No subdirectory summaries found.",
+    "",
+    "## Key Owners",
+    readOwners(payload?.owners).length > 0
+      ? readOwners(payload?.owners)
+          .map((owner) => `- ${owner.author}: ${owner.commits} commits, last touched ${owner.lastTouchedAt} — ${owner.lastSubject}`)
+          .join("\n")
+      : "- No ownership history found.",
+    "",
+    "## File Ownership Map",
+    readFileOwners(payload?.fileOwners).length > 0
+      ? readFileOwners(payload?.fileOwners)
+          .map((owner) => `- \`${owner.filePath}\` — ${owner.primaryOwner} (${owner.ownerCommits} commits, ${owner.touchedCommits} touches)`)
+          .join("\n")
+      : "- No file-level ownership map found.",
+    "",
+    "## Recent Commits",
+    readCommits(payload?.recentCommits).length > 0
+      ? readCommits(payload?.recentCommits)
+          .map((commit) => `- ${commit.date} \`${shortSha(commit.sha)}\` ${commit.author} — ${commit.subject}`)
+          .join("\n")
+      : "- No recent commits found.",
+    "",
+    "## Rename / Move History",
+    readRenameHistory(payload?.renameHistory).length > 0
+      ? readRenameHistory(payload?.renameHistory)
+          .map((entry) => `- ${shortSha(entry.commit)}: \`${entry.fromPath}\` -> \`${entry.toPath}\``)
+          .join("\n")
+      : "- No rename or move history found.",
+  ];
+
+  return `${sections.join("\n")}\n`;
+}
+
+function buildTraceMarkdown(payload) {
+  const sections = [
+    "# RepoLens Trace Report",
+    "",
+    `- Repo root: \`${stringOrFallback(payload?.repoRoot, "unknown")}\``,
+    `- Branch: \`${stringOrFallback(payload?.branch, "unknown")}\``,
+    `- Query: \`${stringOrFallback(payload?.query, "unknown")}\``,
+    `- Since: \`${stringOrFallback(payload?.sinceRef, "full available history")}\``,
+    `- Generated at: ${stringOrFallback(payload?.generatedAt, "unknown")}`,
+    "",
+    "## Matches",
+  ];
+
+  const matches = readTraceMatches(payload?.matches);
+  if (matches.length === 0) {
+    sections.push("- No matching files found.");
+    return `${sections.join("\n")}\n`;
+  }
+
+  for (const match of matches) {
+    sections.push(`- \`${match.filePath}\` (score ${numberOrZero(match.score)}, primary ${stringOrFallback(match.matchType, "path")} match)`);
+    const scoreParts = [
+      numberOrZero(match.scoreBreakdown?.definition) > 0 ? `definition +${match.scoreBreakdown.definition}` : null,
+      numberOrZero(match.scoreBreakdown?.symbol) > 0 ? `symbol +${match.scoreBreakdown.symbol}` : null,
+      numberOrZero(match.scoreBreakdown?.content) > 0 ? `content +${match.scoreBreakdown.content}` : null,
+      numberOrZero(match.scoreBreakdown?.path) > 0 ? `path +${match.scoreBreakdown.path}` : null,
+      numberOrZero(match.scoreBreakdown?.hotspot) > 0 ? `hotspot +${match.scoreBreakdown.hotspot}` : null,
+      numberOrZero(match.scoreBreakdown?.history) > 0 ? `history +${match.scoreBreakdown.history}` : null,
+      numberOrZero(match.scoreBreakdown?.ownership) > 0 ? `ownership +${match.scoreBreakdown.ownership}` : null,
+      numberOrZero(match.scoreBreakdown?.blame) > 0 ? `blame +${match.scoreBreakdown.blame}` : null,
+      numberOrZero(match.scoreBreakdown?.rename) > 0 ? `rename +${match.scoreBreakdown.rename}` : null,
+    ].filter(Boolean);
+
+    sections.push(`  Match signals: ${readStringArray(match.matchSignals).join(", ") || stringOrFallback(match.matchType, "path")}`);
+    sections.push(`  Score: ${scoreParts.join(", ") || "base match"}`);
+    if (readMatchedLines(match.matchedLines).length > 0) {
+      sections.push(`  Matches: ${readMatchedLines(match.matchedLines).slice(0, 2).map((entry) => `${entry.lineNumber}: ${entry.preview}`).join("; ")}`);
+    }
+    if (readOwners(match.ownership?.owners).length > 0) {
+      sections.push(`  Owners: ${readOwners(match.ownership.owners).slice(0, 2).map((owner) => `${owner.author} (${owner.commits})`).join(", ")}`);
+    }
+    if (readCommits(match.evolution?.commits).length > 0) {
+      sections.push(`  Recent: ${readCommits(match.evolution.commits).slice(0, 3).map((commit) => `${commit.date} ${shortSha(commit.sha)} ${commit.subject}`).join("; ")}`);
+    }
+    if (readRenameHistory(match.evolution?.renameHistory).length > 0) {
+      const latestRename = readRenameHistory(match.evolution.renameHistory)[0];
+      sections.push(`  Rename: ${latestRename.fromPath} -> ${latestRename.toPath}`);
+    }
+  }
+
+  return `${sections.join("\n")}\n`;
+}
+
+function readCommits(value) {
+  return Array.isArray(value) ? value.filter((entry) => entry && typeof entry.sha === "string") : [];
+}
+
+function readAuthors(value) {
+  return Array.isArray(value) ? value.filter((entry) => entry && typeof entry.author === "string") : [];
+}
+
+function readFileStats(value) {
+  return Array.isArray(value) ? value.filter((entry) => entry && typeof entry.filePath === "string") : [];
+}
+
+function readOwners(value) {
+  return Array.isArray(value) ? value.filter((entry) => entry && typeof entry.author === "string") : [];
+}
+
+function readBlameOwners(value) {
+  return Array.isArray(value) ? value.filter((entry) => entry && typeof entry.author === "string") : [];
+}
+
+function readCommitThemes(value) {
+  return Array.isArray(value) ? value.filter((entry) => entry && typeof entry.label === "string") : [];
+}
+
+function readFileOwners(value) {
+  return Array.isArray(value) ? value.filter((entry) => entry && typeof entry.filePath === "string" && typeof entry.primaryOwner === "string") : [];
+}
+
+function readRenameHistory(value) {
+  return Array.isArray(value) ? value.filter((entry) => entry && typeof entry.fromPath === "string" && typeof entry.toPath === "string") : [];
+}
+
+function readDirectoryStats(value) {
+  return Array.isArray(value) ? value.filter((entry) => entry && typeof entry.directoryPath === "string") : [];
+}
+
+function readHotspotFiles(value) {
+  return Array.isArray(value) ? value.filter((entry) => entry && typeof entry.filePath === "string") : [];
+}
+
+function readTraceMatches(value) {
+  return Array.isArray(value) ? value.filter((entry) => entry && typeof entry.filePath === "string") : [];
+}
+
+function readMatchedLines(value) {
+  return Array.isArray(value) ? value.filter((entry) => entry && typeof entry.filePath === "string" && Number.isFinite(entry.lineNumber)) : [];
+}
+
+function readReadingOrder(value) {
+  return Array.isArray(value) ? value.filter((entry) => entry && typeof entry.path === "string" && typeof entry.reason === "string") : [];
+}
+
+function readStringArray(value) {
+  return Array.isArray(value) ? value.map((entry) => (typeof entry === "string" ? entry : "")).filter(Boolean) : [];
+}
+
+function readString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : null;
+}
+
+function dedupeStrings(values) {
+  return Array.from(new Set(values.filter(Boolean)));
+}
+
+function arrayLength(value) {
+  return Array.isArray(value) ? value.length : 0;
+}
+
+function numberOrZero(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+function stringOrFallback(value, fallback) {
+  return typeof value === "string" && value.length > 0 ? value : fallback;
+}
+
+function shortSha(value) {
+  return typeof value === "string" ? value.slice(0, 7) : "unknown";
+}

package/lib/protocol-handler.d.ts

@@ -0,0 +1,15 @@
+export function parseRepoLensProtocolUrl(rawUrl: string): {
+  command: string;
+  boardId: string | null;
+  source: string | null;
+};
+
+export function isSafeRepoLensCommand(command: string): boolean;
+
+export function buildTerminalLaunchScript(input: {
+  command: string;
+  cliEntrypoint: string;
+  nodePath: string;
+  repoRoot?: string | null;
+  source?: string | null;
+}): string;