refactor: migrate prompt modules from server to CLI (native analysis foundation) by melagiri · Pull Request #245 · melagiri/code-insights

melagiri · 2026-03-28T11:41:34Z

Summary

Moved 9 pure-function prompt/parser/normalizer modules from server/src/llm/ to cli/src/analysis/
Added 9 ./analysis/* exports to cli/package.json
Converted server files to re-exports from @code-insights/cli/analysis/*
Moved associated test files to cli/src/analysis/__tests__/ (131 tests)
Zero functional changes — pure refactor

Closes #238

What

Creates cli/src/analysis/ with 9 modules:

prompt-types.ts — types (AnalysisResponse, PromptQualityResponse, SQLiteMessageRow, ContentBlock)
prompt-constants.ts — canonical categories + classification guidance strings
prompts.ts — prompt builder functions (buildSessionAnalysisInstructions, buildPromptQualityInstructions, buildFacetOnlyInstructions, buildCacheableConversationBlock)
message-format.ts — formatMessagesForAnalysis, classifyStoredUserMessage, formatSessionMetaLine
response-parsers.ts — parseAnalysisResponse, parsePromptQualityResponse, extractJsonPayload
normalize-utils.ts — levenshtein, normalizeCategory, kebabToTitleCase
friction-normalize.ts — normalizeFrictionCategory
pattern-normalize.ts — normalizePatternCategory, getPatternCategoryLabel
prompt-quality-normalize.ts — normalizePromptQualityCategory, getPQCategoryLabel, getPQCategoryType

Why

Foundation for Phase 12 native analysis (v4.8.0). The CLI needs to build analysis prompts for --native mode (claude -p), but prompt builders lived in server/src/llm/. The CLI cannot import from the server package (circular: server already imports from CLI for DB access). Moving the pure-function modules to CLI breaks the circular dependency.

How

Created cli/src/analysis/ with all 9 modules, adjusting imports between them to stay relative within analysis/
message-format.ts inlined safeParseJson (5-line pure helper) rather than importing across the package boundary — mirrors the existing pattern in server/src/utils.ts and dashboard/src/lib/types.ts
prompt-types.ts gained ContentBlock (was in server/src/llm/types.ts) since prompts.ts needs it — both definitions are structurally identical and TypeScript structural typing ensures compatibility
Server files replaced their full implementations with re-exports — all existing server consumers (analysis.ts, facet-extraction.ts, analysis-db.ts, shared-aggregation.ts, etc.) import unchanged via the re-export chain

Schema Impact

SQLite schema changed: no
Types changed: no (same types, new location)
Server API changed: no
Backward compatible: yes — server re-exports preserve exact same API surface

Verification

Build: PASS (pnpm build — CLI + server + dashboard all clean)
Tests: PASS (939 tests across 43 test files — 0 failures)

The 5 migrated test files run in both CLI (cli/src/analysis/__tests__/) and server (server/src/llm/*.test.ts) locations, giving double coverage confirming the re-export chain works.

Test plan

pnpm build passes from repo root (zero errors)
pnpm test passes (939 tests, 43 files)
Server re-exports preserve exact same API surface
No circular dependency warnings in build output
New CLI tests in cli/src/analysis/__tests__/ all pass (131 tests)
Existing server tests still pass unchanged via re-exports

🤖 Generated with Claude Code

…rmalizers Move 9 pure-function modules from server/src/llm/ to cli/src/analysis/ as the foundation for native analysis (--native mode, Issue #238, Phase 12 v4.8.0). New modules in cli/src/analysis/: - prompt-types.ts: AnalysisResponse, PromptQualityResponse, SQLiteMessageRow, ContentBlock - prompt-constants.ts: Canonical categories and classification guidance strings - prompts.ts: buildSessionAnalysisInstructions, buildPromptQualityInstructions, buildFacetOnlyInstructions - message-format.ts: formatMessagesForAnalysis, classifyStoredUserMessage, formatSessionMetaLine - response-parsers.ts: parseAnalysisResponse, parsePromptQualityResponse, extractJsonPayload - normalize-utils.ts: levenshtein, normalizeCategory, kebabToTitleCase - friction-normalize.ts: normalizeFrictionCategory - pattern-normalize.ts: normalizePatternCategory, getPatternCategoryLabel - prompt-quality-normalize.ts: normalizePromptQualityCategory, getPQCategoryLabel, getPQCategoryType Added 9 ./analysis/* exports to cli/package.json. Moved test files to cli/src/analysis/__tests__/ (5 test files, 131 tests). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…ights/cli/analysis/* Server files now re-export from the CLI analysis/ package, preserving the exact same public API surface with zero breaking changes. Converted to re-exports: - server/src/llm/prompt-types.ts - server/src/llm/prompt-constants.ts - server/src/llm/prompts.ts - server/src/llm/message-format.ts - server/src/llm/response-parsers.ts - server/src/llm/normalize-utils.ts - server/src/llm/friction-normalize.ts - server/src/llm/pattern-normalize.ts - server/src/llm/prompt-quality-normalize.ts All existing server imports (analysis.ts, facet-extraction.ts, prompt-quality-analysis.ts, analysis-db.ts, shared-aggregation.ts) continue to work unchanged via re-exports. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

vado290 · 2026-03-28T13:24:53Z

please keep building,it is a great work,very helpful and useful tool

…

melagiri · 2026-03-29T03:55:53Z

Thank you :) Please share your valuable feedback to improve this tool

melagiri · 2026-03-29T04:00:57Z

TA Synthesis (Phase 2): Prompt Module Migration — Round 1

Review of Domain Specialist Comments

#	Finding	Source	Verdict	Rationale
1	🟠 Server `prompts.ts` re-export confirmation	Node/CLI Specialist	✅ RESOLVED	Orchestrator verified on PR branch: `server/src/llm/prompts.ts` is a 9-line re-export (down from 425 lines). Confirmed via diff.
2	🟡 Duplicate `ContentBlock` definition	Both reviewers	AGREE — non-blocking	`ContentBlock` now exists in both `cli/src/analysis/prompt-types.ts` and `server/src/llm/types.ts`. TypeScript structural typing ensures compatibility. The CLI cannot import from server (that's the whole point of this refactor). Acceptable duplication.
3	🔵 `safeParseJson` inlined in `message-format.ts`	Both reviewers	AGREE — acceptable	5-line pure helper inlined to avoid cross-package import. Matches existing pattern (dashboard has its own copy too). Not worth a shared utility package for this.
4	🔵 Dormant monitoring code in `response-parsers.ts`	TA Insider	AGREE — not introduced by this PR	Empty monitoring blocks existed in the server version. Pure move, no new debt.
5	🔵 Server files retain old implementations on master	Node/CLI Specialist	AGREE — expected	Server files on master still have full implementations. The PR branch replaces them with re-exports. This is correct git behavior, not a bug.

Second Pass Findings

After reviewing both independent reviews and re-checking the diff:

No schema changes: All 13 "schema" matches in the diff are inside prompt template strings and test assertions — zero SQLite DDL changes.
Data contract intact: No changes to cli/src/types.ts, no migration files touched, no API route changes.
24 files changed, +2761/-1452: Numbers are consistent with moving ~1400 lines of implementation from server to CLI, plus adding the new CLI copies and converting server files to re-exports.
Test coverage: 131 tests moved to cli/src/analysis/__tests__/, existing server tests still pass via re-export chain. Double coverage confirms the contract.
Package exports: PR description lists 9 ./analysis/* exports added to cli/package.json — specialist verified all 9.

No new issues found in second pass.

Consolidated Review (For Dev Agent)

🔴 FIX NOW: None.

❌ NOT APPLICABLE: None — all findings were valid observations.

⚠️ ESCALATE TO FOUNDER: None.

🟡 SUGGESTIONS (non-blocking, dev's discretion):

ContentBlock duplication — Both reviewers noted this. If a future PR introduces a shared types package, both definitions should collapse into it. No action needed now — the duplication is a consequence of the architectural constraint (CLI cannot import from server). Worth a brief comment in prompt-types.ts noting the sibling definition exists in server/src/llm/types.ts.

Final Verdict

PASS — ready for merge. Zero blocking issues from either reviewer. Pure refactor confirmed: no schema changes, no API changes, no functional changes. Build and 939 tests pass. Server re-export chain verified on PR branch.

melagiri and others added 2 commits March 28, 2026 17:10

melagiri merged commit 659f393 into master Mar 29, 2026
2 checks passed

melagiri deleted the feature/prompt-module-migration branch March 29, 2026 04:22

melagiri mentioned this pull request Mar 29, 2026

feat: AnalysisRunner interface + ClaudeNativeRunner + ProviderRunner #239

Closed

7 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor: migrate prompt modules from server to CLI (native analysis foundation)#245

refactor: migrate prompt modules from server to CLI (native analysis foundation)#245
melagiri merged 2 commits intomasterfrom
feature/prompt-module-migration

melagiri commented Mar 28, 2026

Uh oh!

vado290 commented Mar 28, 2026 via email

Uh oh!

melagiri commented Mar 29, 2026 •

edited

Loading

Uh oh!

melagiri commented Mar 29, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

melagiri commented Mar 28, 2026

Summary

What

Why

How

Schema Impact

Verification

Test plan

Uh oh!

vado290 commented Mar 28, 2026 via email

Uh oh!

melagiri commented Mar 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

melagiri commented Mar 29, 2026

TA Synthesis (Phase 2): Prompt Module Migration — Round 1

Review of Domain Specialist Comments

Second Pass Findings

Consolidated Review (For Dev Agent)

Final Verdict

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

melagiri commented Mar 29, 2026 •

edited

Loading