@repolensai/cli 0.1.1

package/lib/protocol-handler.mjs

@@ -0,0 +1,158 @@
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", `'\"'\"'`)}'`;
+}
+
+function cmdQuote(value) {
+  return `"${String(value).replaceAll('"', '""')}"`;
+}
+
+/**
+ * @param {string} rawUrl
+ */
+export function parseRepoLensProtocolUrl(rawUrl) {
+  let parsed;
+  try {
+    parsed = new URL(rawUrl);
+  } catch {
+    throw new Error("Invalid RepoLens launch URL.");
+  }
+
+  if (!["repolens-cli:", "repolens:"].includes(parsed.protocol) || parsed.hostname !== "run") {
+    throw new Error("Unsupported RepoLens launch URL.");
+  }
+
+  const command = parsed.searchParams.get("command")?.trim() ?? "";
+  if (!command) {
+    throw new Error("RepoLens launch URL is missing a command.");
+  }
+
+  return {
+    command,
+    boardId: parsed.searchParams.get("boardId")?.trim() || null,
+    source: parsed.searchParams.get("source")?.trim() || null,
+  };
+}
+
+/**
+ * @param {string} command
+ */
+export function isSafeRepoLensCommand(command) {
+  return typeof command === "string"
+    && command.startsWith("repolens ")
+    && !/[\u0000\r\n;&|<>`$]/.test(command);
+}
+
+/**
+ * @param {{
+ *   command: string;
+ *   cliEntrypoint: string;
+ *   nodePath: string;
+ *   repoRoot?: string | null;
+ *   source?: string | null;
+ * }} input
+ */
+export function buildTerminalLaunchScript({ command, cliEntrypoint, nodePath, repoRoot = null, source = null }) {
+  if (!isSafeRepoLensCommand(command)) {
+    throw new Error("Refusing to launch an unsafe RepoLens command.");
+  }
+
+  const commandArgs = command.slice("repolens ".length).trim();
+  const lines = [
+    `REPOLENS_CMD=${shellQuote(command)}`,
+    `REPOLENS_NODE=${shellQuote(nodePath)}`,
+    `REPOLENS_ENTRY=${shellQuote(cliEntrypoint)}`,
+    `REPOLENS_ARGS=${shellQuote(commandArgs)}`,
+    `REPOLENS_REPO_ROOT=${shellQuote(repoRoot ?? "")}`,
+    `REPOLENS_SOURCE=${shellQuote(source ?? "")}`,
+    "",
+    "printf 'RepoLens CLI handoff\\n\\n'",
+    'if [[ -n "$REPOLENS_SOURCE" ]]; then',
+    '  printf "Source: %s\\n" "$REPOLENS_SOURCE"',
+    "fi",
+    'printf "Command:\\n%s\\n\\n" "$REPOLENS_CMD"',
+    'if [[ -n "$REPOLENS_REPO_ROOT" ]]; then',
+    '  printf "Working directory:\\n%s\\n\\n" "$REPOLENS_REPO_ROOT"',
+    "else",
+    "  printf 'Working directory:\\nChoose it in Terminal before confirming.\\n\\n'",
+    "fi",
+    'printf "Run this command? [y/N] "',
+    "read -r REPOLENS_CONFIRM",
+    'case "$REPOLENS_CONFIRM" in',
+    "  [Yy]|[Yy][Ee][Ss]) ;;",
+    "  *) echo 'Cancelled.'; exit 0 ;;",
+    "esac",
+    'if [[ -n "$REPOLENS_REPO_ROOT" ]]; then',
+    '  cd "$REPOLENS_REPO_ROOT" || exit 1',
+    "fi",
+    'eval "set -- $REPOLENS_ARGS"',
+    '"$REPOLENS_NODE" "$REPOLENS_ENTRY" "$@"',
+  ];
+
+  return lines.join("\n");
+}
+
+/**
+ * @param {{
+ *   command: string;
+ *   cliEntrypoint: string;
+ *   nodePath: string;
+ *   repoRoot?: string | null;
+ *   source?: string | null;
+ * }} input
+ */
+export function buildWindowsTerminalLaunchScript({ command, cliEntrypoint, nodePath, repoRoot = null, source = null }) {
+  if (!isSafeRepoLensCommand(command)) {
+    throw new Error("Refusing to launch an unsafe RepoLens command.");
+  }
+
+  const commandArgs = command.slice("repolens ".length).trim();
+  const lines = [
+    "@echo off",
+    `set "REPOLENS_CMD=${command}"`,
+    `set "REPOLENS_NODE=${nodePath}"`,
+    `set "REPOLENS_ENTRY=${cliEntrypoint}"`,
+    `set "REPOLENS_ARGS=${commandArgs}"`,
+    `set "REPOLENS_REPO_ROOT=${repoRoot ?? ""}"`,
+    `set "REPOLENS_SOURCE=${source ?? ""}"`,
+    "echo RepoLens CLI handoff",
+    "echo.",
+    'if not "%REPOLENS_SOURCE%"=="" echo Source: %REPOLENS_SOURCE%',
+    "echo Command:",
+    "echo %REPOLENS_CMD%",
+    "echo.",
+    'if not "%REPOLENS_REPO_ROOT%"=="" (',
+    "  echo Working directory:",
+    "  echo %REPOLENS_REPO_ROOT%",
+    ") else (",
+    "  echo Working directory:",
+    "  echo Choose it in Terminal before confirming.",
+    ")",
+    "echo.",
+    'choice /C YN /N /M "Run this command? [Y/N] "',
+    "if errorlevel 2 goto :eof",
+    'if not "%REPOLENS_REPO_ROOT%"=="" cd /d "%REPOLENS_REPO_ROOT%"',
+    `call ${cmdQuote(nodePath)} ${cmdQuote(cliEntrypoint)} ${commandArgs}`,
+    "",
+  ];
+
+  return lines.join("\r\n");
+}
+
+/**
+ * @param {{
+ *   scriptPath: string;
+ * }} input
+ */
+export function buildLinuxDesktopEntry({ scriptPath }) {
+  return `[Desktop Entry]
+Type=Application
+Name=RepoLens Launcher
+Comment=Handle RepoLens browser-to-terminal handoff
+Exec=${scriptPath} %u
+Terminal=false
+NoDisplay=true
+MimeType=x-scheme-handler/repolens-cli;
+StartupNotify=false
+X-Desktop-File-Install-Version=0.27
+`;
+}

package/lib/publish-shared.d.ts

@@ -0,0 +1,14 @@
+export function buildEvidenceRows(boardId: string, evidenceValue: unknown, commitSha: string | null): Array<Record<string, unknown>>;
+export function buildDiagramRows(params: {
+  analysisId: string;
+  boardId: string;
+  publishKind: string;
+  audience: string;
+  diagrams: unknown;
+}): Array<Record<string, unknown>>;
+export function collectExplainerRelatedFiles(result: Record<string, unknown>): string[];
+export function collectChangeBriefRelatedFiles(result: Record<string, unknown>): string[];
+export function exportExplainerToMarkdown(result: Record<string, unknown>): string;
+export function exportChangeBriefToMarkdown(result: Record<string, unknown>): string;
+export function normalizeChangeBriefAudience(value: string): string;
+export function normalizeExplainerAudience(value: string): string;

package/lib/publish-shared.mjs

@@ -0,0 +1,299 @@
+export function buildEvidenceRows(boardId, evidenceValue, commitSha) {
+  return readArray(evidenceValue).map((item) => {
+    const record = asRecord(item);
+
+    return {
+      board_id: boardId,
+      evidence_type: stringOrFallback(record.type, "file"),
+      reference: stringOrFallback(record.reference, "unknown"),
+      description: stringOrFallback(record.description, ""),
+      commit_sha: typeof commitSha === "string" ? commitSha : null,
+      line_start: readLinePart(record.lineRange, 0),
+      line_end: readLinePart(record.lineRange, 1),
+      // Persist only references and metadata, not raw source snippets.
+      code_snippet: null,
+      confidence: normalizeEvidenceConfidence(record.confidence),
+    };
+  });
+}
+
+export function buildDiagramRows(params) {
+  return readArray(params.diagrams)
+    .map(asRecord)
+    .filter((diagram) => nullableString(diagram.mermaidSource))
+    .map((diagram) => ({
+      analysis_id: params.analysisId,
+      board_id: params.boardId,
+      type: "diagram",
+      perspective: stringOrFallback(diagram.type, params.publishKind),
+      audience: params.audience,
+      title: stringOrFallback(diagram.title, "Diagram"),
+      content: stringOrFallback(diagram.mermaidSource, ""),
+      content_format: "mermaid",
+      confidence_score: 0.72,
+      confidence_reason: "local_agent_structured_output",
+      is_inferred: true,
+      related_files: readStringArray(diagram.relatedFiles),
+    }));
+}
+
+export function collectExplainerRelatedFiles(result) {
+  const files = new Set();
+
+  for (const component of readArray(result.keyComponents).map(asRecord)) {
+    for (const file of readStringArray(component.files)) {
+      files.add(file);
+    }
+  }
+
+  for (const diagram of readArray(result.diagrams).map(asRecord)) {
+    for (const file of readStringArray(diagram.relatedFiles)) {
+      files.add(file);
+    }
+  }
+
+  for (const evidence of readArray(result.evidence).map(asRecord)) {
+    const reference = nullableString(evidence.reference);
+    if (reference) {
+      files.add(reference);
+    }
+  }
+
+  return Array.from(files);
+}
+
+export function collectChangeBriefRelatedFiles(result) {
+  const files = new Set();
+
+  for (const item of readArray(result.impactedFiles).map(asRecord)) {
+    const filePath = nullableString(item.path);
+    if (filePath) {
+      files.add(filePath);
+    }
+  }
+
+  for (const diagram of readArray(result.diagrams).map(asRecord)) {
+    for (const file of readStringArray(diagram.relatedFiles)) {
+      files.add(file);
+    }
+  }
+
+  for (const evidence of readArray(result.evidence).map(asRecord)) {
+    const reference = nullableString(evidence.reference);
+    if (reference) {
+      files.add(reference);
+    }
+  }
+
+  return Array.from(files);
+}
+
+export function exportExplainerToMarkdown(result) {
+  const lines = [];
+
+  lines.push(`# ${stringOrFallback(result.title, "Explainer")}`);
+  lines.push("");
+  lines.push(`> ${stringOrFallback(result.summary, "")}`);
+  lines.push("");
+
+  if (nullableString(result.valueProposition)) {
+    lines.push("## Value Proposition");
+    lines.push(String(result.valueProposition));
+    lines.push("");
+  }
+
+  if (nullableString(result.userJourney)) {
+    lines.push("## User Journey");
+    lines.push(String(result.userJourney));
+    lines.push("");
+  }
+
+  const keyComponents = readArray(result.keyComponents).map(asRecord);
+  if (keyComponents.length > 0) {
+    lines.push("## Key Components");
+    for (const component of keyComponents) {
+      lines.push(`- **${stringOrFallback(component.name, "Untitled Component")}** — ${stringOrFallback(component.role, "")}`);
+      const files = readStringArray(component.files);
+      if (files.length > 0) {
+        lines.push(`  - Files: ${files.map((file) => `\`${file}\``).join(", ")}`);
+      }
+    }
+    lines.push("");
+  }
+
+  if (nullableString(result.businessLogic)) {
+    lines.push("## Business Logic");
+    lines.push(String(result.businessLogic));
+    lines.push("");
+  }
+
+  for (const diagram of readArray(result.diagrams).map(asRecord)) {
+    lines.push(`## ${stringOrFallback(diagram.title, "Diagram")}`);
+    lines.push("");
+    lines.push("```mermaid");
+    lines.push(stringOrFallback(diagram.mermaidSource, ""));
+    lines.push("```");
+    lines.push("");
+  }
+
+  if (nullableString(result.risksAndQuestions)) {
+    lines.push("## Risks & Questions");
+    lines.push(String(result.risksAndQuestions));
+    lines.push("");
+  }
+
+  const openQuestions = readStringArray(result.openQuestions);
+  if (openQuestions.length > 0) {
+    lines.push("## Open Questions");
+    for (const question of openQuestions) {
+      lines.push(`- ${question}`);
+    }
+    lines.push("");
+  }
+
+  appendEvidence(lines, result.evidence);
+
+  lines.push("---");
+  lines.push("*Generated by RepoLens CLI*");
+
+  return lines.join("\n");
+}
+
+export function exportChangeBriefToMarkdown(result) {
+  const lines = [];
+
+  lines.push("# Change Brief");
+  lines.push("");
+  lines.push(`> ${stringOrFallback(result.summary, "")}`);
+  lines.push("");
+
+  for (const feature of readArray(result.impactedFeatures).map(asRecord)) {
+    if (lines[lines.length - 1] !== "## Impacted Features" && !lines.includes("## Impacted Features")) {
+      lines.push("## Impacted Features");
+    }
+    lines.push(`- **${stringOrFallback(feature.feature, "Feature")}** (${stringOrFallback(feature.impactType, "changed")}) — ${stringOrFallback(feature.description, "")}`);
+  }
+  if (lines[lines.length - 1] === "## Impacted Features") {
+    lines.pop();
+  } else if (lines.includes("## Impacted Features")) {
+    lines.push("");
+  }
+
+  const impactedFiles = readArray(result.impactedFiles).map(asRecord);
+  if (impactedFiles.length > 0) {
+    lines.push("## Changed Files");
+    for (const item of impactedFiles) {
+      lines.push(`- \`${stringOrFallback(item.path, "unknown")}\` (${stringOrFallback(item.changeType, "modified")}) — ${stringOrFallback(item.role, "")}`);
+    }
+    lines.push("");
+  }
+
+  const impactedScreens = readStringArray(result.impactedScreens);
+  if (impactedScreens.length > 0) {
+    lines.push("## Impacted Screens");
+    for (const screen of impactedScreens) {
+      lines.push(`- ${screen}`);
+    }
+    lines.push("");
+  }
+
+  if (nullableString(result.rolloutRisks)) {
+    lines.push("## Rollout Risks");
+    lines.push(String(result.rolloutRisks));
+    lines.push("");
+  }
+
+  const qaChecklist = readStringArray(result.qaChecklist);
+  if (qaChecklist.length > 0) {
+    lines.push("## QA Checklist");
+    for (const item of qaChecklist) {
+      lines.push(`- [ ] ${item}`);
+    }
+    lines.push("");
+  }
+
+  if (nullableString(result.communicationBrief)) {
+    lines.push("## Communication Brief");
+    lines.push(String(result.communicationBrief));
+    lines.push("");
+  }
+
+  for (const diagram of readArray(result.diagrams).map(asRecord)) {
+    lines.push(`## ${stringOrFallback(diagram.title, "Diagram")}`);
+    lines.push("");
+    lines.push("```mermaid");
+    lines.push(stringOrFallback(diagram.mermaidSource, ""));
+    lines.push("```");
+    lines.push("");
+  }
+
+  appendEvidence(lines, result.evidence);
+
+  lines.push("---");
+  lines.push("*Generated by RepoLens CLI*");
+
+  return lines.join("\n");
+}
+
+export function normalizeChangeBriefAudience(value) {
+  return value === "engineer" || value === "qa" ? value : "pm";
+}
+
+export function normalizeExplainerAudience(value) {
+  return value === "engineer" || value === "technical_deep_dive" ? value : "pm";
+}
+
+function appendEvidence(lines, evidenceValue) {
+  const evidence = readArray(evidenceValue).map(asRecord);
+  if (evidence.length === 0) {
+    return;
+  }
+
+  lines.push("## Evidence");
+  for (const item of evidence) {
+    const confidence = normalizeEvidenceConfidence(item.confidence);
+    const badge = confidence === "explicit" ? "✓" : confidence === "strongly_inferred" ? "~" : "?";
+    lines.push(`- [${badge}] **${stringOrFallback(item.reference, "unknown")}** — ${stringOrFallback(item.description, "")}`);
+  }
+  lines.push("");
+}
+
+function readLinePart(value, index) {
+  if (!Array.isArray(value)) {
+    return null;
+  }
+
+  const candidate = value[index];
+  return typeof candidate === "number" && !Number.isNaN(candidate) ? candidate : null;
+}
+
+function normalizeEvidenceConfidence(value) {
+  if (value === "explicit" || value === "strongly_inferred" || value === "hypothesis") {
+    return value;
+  }
+  return "hypothesis";
+}
+
+function readArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function readStringArray(value) {
+  return readArray(value).map(String).filter(Boolean);
+}
+
+function stringOrFallback(value, fallback) {
+  return typeof value === "string" && value.length > 0 ? value : fallback;
+}
+
+function nullableString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value : null;
+}
+
+function asRecord(value) {
+  return isPlainObject(value) ? value : {};
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/lib/runtime-events.d.ts

@@ -0,0 +1,31 @@
+export interface CliRuntimeAuthConfig {
+  appUrl?: string | null;
+  token?: string | null;
+}
+
+export interface CliRuntimeEvent {
+  action:
+    | "cli_login.browser_open_failed"
+    | "cli_protocol.install_failed"
+    | "cli_protocol.install_succeeded"
+    | "cli_protocol.launch_invalid_url"
+    | "cli_protocol.launch_missing_repo_link"
+    | "cli_protocol.launch_opened"
+    | "cli_protocol.launch_received"
+    | "cli_protocol.launch_terminal_failed"
+    | "cli_protocol.launch_unsafe_command"
+    | "cli_protocol.launch_unsupported_platform";
+  boardId?: string | null;
+  targetId?: string | null;
+  metadata?: Record<string, unknown> | null;
+}
+
+export function normalizeCliRuntimeEvent(value: unknown): CliRuntimeEvent | null;
+
+export function reportCliRuntimeEvent(
+  authConfig: CliRuntimeAuthConfig,
+  event: unknown,
+  options?: {
+    fetchImpl?: typeof fetch;
+  }
+): Promise<boolean>;

package/lib/runtime-events.mjs

@@ -0,0 +1,80 @@
+const CLI_RUNTIME_ACTIONS = new Set([
+  "cli_login.browser_open_failed",
+  "cli_protocol.install_failed",
+  "cli_protocol.install_succeeded",
+  "cli_protocol.launch_invalid_url",
+  "cli_protocol.launch_missing_repo_link",
+  "cli_protocol.launch_opened",
+  "cli_protocol.launch_received",
+  "cli_protocol.launch_terminal_failed",
+  "cli_protocol.launch_unsafe_command",
+  "cli_protocol.launch_unsupported_platform",
+]);
+
+/**
+ * @param {unknown} value
+ */
+function normalizeMetadata(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+
+  return /** @type {Record<string, unknown>} */ (value);
+}
+
+/**
+ * @param {unknown} value
+ */
+export function normalizeCliRuntimeEvent(value) {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+
+  const candidate = /** @type {Record<string, unknown>} */ (value);
+  const action = typeof candidate.action === "string" ? candidate.action : null;
+  if (!action || !CLI_RUNTIME_ACTIONS.has(action)) {
+    return null;
+  }
+
+  return {
+    action,
+    boardId: typeof candidate.boardId === "string" && candidate.boardId.trim() ? candidate.boardId.trim() : null,
+    targetId: typeof candidate.targetId === "string" && candidate.targetId.trim() ? candidate.targetId.trim() : null,
+    metadata: normalizeMetadata(candidate.metadata),
+  };
+}
+
+/**
+ * @param {{
+ *   appUrl?: string | null;
+ *   token?: string | null;
+ * }} authConfig
+ * @param {unknown} event
+ * @param {{
+ *   fetchImpl?: typeof fetch;
+ * }} [options]
+ */
+export async function reportCliRuntimeEvent(authConfig, event, options = {}) {
+  const normalized = normalizeCliRuntimeEvent(event);
+  if (!normalized || !authConfig?.appUrl || !authConfig?.token) {
+    return false;
+  }
+
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const url = new URL("/api/cli/events", `${authConfig.appUrl}/`);
+
+  try {
+    const response = await fetchImpl(url, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${authConfig.token}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify(normalized),
+    });
+
+    return response.ok;
+  } catch {
+    return false;
+  }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@repolensai/cli",
+  "version": "0.1.1",
+  "description": "RepoLens terminal client for local agent orchestration and board publishing",
+  "type": "module",
+  "preferGlobal": true,
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "repolens": "bin/repolens.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "keywords": [
+    "repolens",
+    "cli",
+    "codex",
+    "claude",
+    "git"
+  ],
+  "homepage": "https://github.com/Michal-Pi/repolense/tree/main/packages/cli",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Michal-Pi/repolense.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/Michal-Pi/repolense/issues"
+  },
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=20"
+  }
+}