TaskList.md

OpenSIPS Documentation Collector - Master Task List

This document serves as the master execution plan for verifying and finalizing the project.

Phase 1: Project Setup & Environment Audit

• Step 1: Environment Verification

  • Verify package.json dependencies match requirements (MASTRA, AI SDK, Zod, etc.).
  • Check tsconfig.json for strict mode settings.
  • Verify .env file exists and contains necessary keys (or use .env.example).
  • Ensure data/state and data/processed directories exist (or are created by code).
  • Verification: Run npm install and ensure no peer dependency warnings. Run npm run build (if script exists, else tsc) to check for compilation errors.

• Step 2: Documentation Integrity Check

  • Verify docs/schemas matches src/schemas implementations 1:1.
  • Confirm AGENTS.md accurately reflects the current architecture.
  • Check docs/opensips-llm-extraction-prompts.md contains prompts for all document types.
  • Verification: Manual cross-check of one schema (e.g., modules.schema.ts) against its markdown doc.

Phase 2: Schema Implementation Verification

• Step 3: Base & Shared Schemas

  • Verify src/schemas/base.schema.ts exports BaseDocumentSchema.
  • Verify src/schemas/collection-state.schema.ts matches state management design.
  • Verify src/schemas/consolidated.schema.ts structure.
  • Verification: Run existing unit test tests/unit/schemas/module.schema.test.ts.

• Step 4: Core Documentation Schemas

  • Audit src/schemas/core/*.ts files (12 types).
  • Ensure all 12 types (variables, functions, parameters, etc.) are exported in src/schemas/index.ts.
  • Verification: Create a temporary test script that imports all core schemas and successfully parses a dummy object for each.

• Step 5: Module & Guide Schemas

  • Verify src/schemas/modules.schema.ts handles nested objects (params, functions).
  • Verify src/schemas/guides.schema.ts covers all 3 guide types.
  • Verification: Run npx ts-node -e "import { ModuleDocumentSchema } from './src/schemas/modules.schema'; console.log('Module Schema Valid');"

Phase 3: Service Layer Verification (Unit Testing)

• Step 6: State Service

  • Verify src/services/state.service.ts implements init, save, markCompleted, logError.
  • Check file locking/atomicity logic (if any) or simple write safety.
  • Verification: Run tests/unit/services/state.service.test.ts.

• Step 7: File Service

  • Verify src/services/file.service.ts path resolution logic.
  • Ensure writeDocumentJson validates data before writing.
  • Verification: Create a unit test checking that writeDocumentJson writes to the correct path data/processed/{version}/{category}/{name}.json.

• Step 8: Fetcher & Converter Services

  • Verify src/services/fetcher.service.ts has rate limiting logic.
  • Verify src/services/converter.service.ts uses Turndown correctly.
  • Verification: Create a test that mocks fetch and asserts rate limiting delay, then checks HTML->MD conversion output.

• Step 9: LLM Provider Service

  • Verify src/services/llm.service.ts supports Google, OpenAI, Anthropic switching.
  • Check error handling and retry logic in generate.
  • Verification: Create a test with a mocked provider response to ensure generate returns parsed JSON.

Phase 4: MASTRA Tools Verification

• Step 10: Fetch & Parse Tools

  • Verify src/tools/fetch-html.tool.ts uses FetcherService.
  • Verify src/tools/parse-module-list.tool.ts uses Cheerio correctly.
  • Verification: Run a script executing parseModuleListTool with a sample HTML snippet containing module links.

• Step 11: Extraction Tools

  • Verify src/tools/extract-with-llm.tool.ts integration with doc-extractor.agent.ts.
  • Check prompt injection mechanism from docs/opensips-llm-extraction-prompts.md.
  • Verification: Mock the LLM service and run extractWithLlmTool to see if it calls the service with the correct prompt structure.

• Step 12: Output Tools

  • Verify src/tools/write-json.tool.ts and validate-schema.tool.ts.
  • Verify src/tools/update-state.tool.ts.
  • Verification: Execute writeJsonTool in a test script and confirm file creation.

Phase 5: Workflow Implementation & Testing

• Step 13: Discovery Workflow

  • Audit src/workflows/discovery/discover-urls.workflow.ts.
  • Ensure it passes data correctly between steps (Fetch -> Parse -> Update State).
  • Verification: Run the workflow with a mocked fetcher that returns a static module list page.

• Step 14: Module Extraction Workflow

  • Audit src/workflows/modules/extract-module.workflow.ts.
  • Check extractWithLlmTool usage with ModuleDocumentSchema.
  • Verification: Run the workflow with mocked inputs (single module) and verify state update to "completed".

• Step 15: Core Workflows (12 Types)

  • Audit src/workflows/core/core-workflows.ts (factory pattern usage).
  • Ensure all 12 workflows are correctly instantiated.
  • Verification: Pick one core workflow (e.g., extractCoreVariablesWorkflow) and dry-run it with mocks.

• Step 16: Guide Workflows

  • Audit src/workflows/guides/guide-workflows.ts.
  • Verification: Dry-run extractInstallGuideWorkflow with mocks.

• Step 17: Output Workflows

  • Audit enhance-relationships.workflow.ts and consolidate-mcp.workflow.ts.
  • Check that consolidate reads from the correct paths.
  • Verification: Populate dummy data in data/processed and run consolidateMcpWorkflow to see if it generates a valid aggregated file.

Phase 6: CLI & Orchestration Verification

• Step 18: CLI Entry Point

  • Audit src/index.ts.
  • Verify command parsing: collect, status, retry, list.
  • Verification: Run node dist/index.js --help and check output.

• Step 19: Main Orchestrator Logic

  • Check the collect command logic in src/index.ts.
  • Verify it initializes state -> runs discovery -> runs core (parallel) -> runs modules (loop) -> runs output.
  • Verification: Run collect --dry-run (if implemented) or use mocks to trace the execution path without making network calls.

• Step 20: Resilience & Recovery

  • Verify that rerunning collect resumes from state.
  • Verify status command reads correctly from state file.
  • Verification: Manually edit a state file to simulate a partial run, then run collect and observe log output (should skip completed items).

Phase 7: Final Tests & Polish

• Step 21: Integration Test Suite

  • Create tests/integration/full-run.test.ts.
  • Implement a full mock run of one module + one core doc.
  • Verification: npm test passes all suites.

• Step 22: Documentation Finalization

  • Update README.md with usage instructions based on final CLI.
  • Ensure AGENTS.md is up to date for future maintenance.
  • Verification: Review all markdown files for broken links or outdated info.

• Step 23: Release Build

  • Clean dist/ and data/.
  • Run full build.
  • Verification: Execute the built binary against a real (or mocked) target to ensure startup is error-free.