dss/dss-temp-handover.md

Situation Handover to Claude

Context: The overarching goal is to enhance DSS (Design System Server) with greater intelligence for analyzing and managing React projects, initially by "dogfooding" DSS itself on its own admin-ui project.

Initial Goal from User:

1. Implement a robust Python-based analysis engine (project_analyzer.py) for React projects.
2. Integrate this into the DSS MCP and CLI.
3. Ensure continuous integration (CI/CD) automates the analysis and commits results (project_context.json) back to the repository.
4. Set up DSS to manage its own admin-ui project.
5. Link core DSS to its Figma UI Kit.
6. Build a default Storybook skin with DSS atoms and shadcn styles.

---

Actions Taken & Current Status:

1. Analysis Engine & CLI:

   • Implemented: dss-mvp1/dss/analyze/project_analyzer.py was created, capable of parsing React/JS/TS files (using a Node.js @babel/parser subprocess) and generating a networkx graph. It also includes an export_project_context function.
   • Implemented: dss-mvp1/dss-cli.py was created as a command-line interface, including analyze, export-context, add-figma-file, setup-storybook, and sync-tokens commands.
   • Implemented: The dss-claude-plugin/servers/dss-mcp-server.py was updated to expose dss_project_graph_analysis and dss_project_export_context as MCP tools for AI agents.
   • Implemented: Unit tests for project_analyzer.py were added and are currently passing.

2. CI/CD Setup:

   • Implemented: .gitea/workflows/dss-analysis.yml was created to automate the dss-cli.py analyze and git commit process for project_context.json on every push.
   • Verified: Git hooks were fixed and confirmed to be running.
   • Verified: SSH key authentication for Git push was correctly set up after troubleshooting.

3. Dogfooding admin-ui Project:

   • Goal: Initialize admin-ui as a DSS project, generate its analysis context, link it to Figma, and generate Storybook stories.
   • Status:
     • admin-ui/.dss/analysis_graph.json was successfully created (by dss-mvp1/dss-cli.py analyze --project-path ./admin-ui).
     • admin-ui/ds.config.json was manually corrected and populated to resolve Pydantic validation errors during project loading.
     • Figma UI Kit figd_ScdBk47HlYEItZbQv2CcF9aq-3TfWbBXN3yoRKWA was successfully linked to admin-ui (by dss-mvp1/dss-cli.py add-figma-file --project-path ./admin-ui --file-key ...).
     • Token Synchronization (Blocked): dss-mvp1/dss-cli.py sync-tokens --project-path ./admin-ui fails with 403 Client Error: Forbidden from Figma API due to a placeholder token. This is expected, as a valid FIGMA_TOKEN environment variable is required.

4. Storybook Generation (Current Blocker):

   • Goal: Build a default Storybook skin with DSS atoms and shadcn styles applied.
   • Expected Tool: dss-mvp1/dss-cli.py setup-storybook --action generate --project-path ./admin-ui.
   • Problem: This command consistently reports Generated 0 new stories.
   • Investigation:
     • Initial assumption that dss-mvp1 itself contained components was incorrect.
     • Moved admin-ui/js/components/ds-button.js to admin-ui/src/components/ds-button.js to match component discovery paths.
     • Re-read dss/storybook/generator.py to confirm its logic. It expects components in standard directories like src/components.
     • Confirmed that StoryGenerator.generate calls generate_stories_for_directory, which in turn calls _parse_component.
     • Despite placing ds-button.js in a recognized path, 0 new stories are still being generated.
     • The StoryGenerator logic in dss/storybook/generator.py inspects component files, but it relies on specific patterns (e.g., interface ButtonProps, children) to extract PropInfo and ComponentMeta. The output of @babel/parser is not currently being used by StoryGenerator to populate ComponentMeta.

The core issue preventing Storybook generation is that the StoryGenerator is unable to correctly parse the provided JavaScript/TypeScript component files and extract the necessary metadata (props, component name, etc.) to create a story. The integration between the @babel/parser output (which is JSON AST) and the StoryGenerator's _parse_component method is either missing or misconfigured. The _parse_component method appears to be using regex on the raw file content, which might be insufficient or incorrect for the component's structure.

---

Recommendation for Claude:

1. Investigate dss/storybook/generator.py: Focus on the _parse_component method. How does it extract ComponentMeta from the component file? It currently uses regex, which is fragile.
2. Integrate Babel AST: The @babel/parser subprocess call already produces a full AST. The _parse_component method should be updated to consume and interpret this AST to reliably extract component metadata (name, props, children, description). This would be much more robust than regex.
3. Validate Component Structure: Ensure the ds-button.js (or any target component) has a structure that the updated parser can understand and extract metadata from.
4. Re-run Storybook Generation: Once _parse_component can correctly extract metadata, re-run setup-storybook --action generate to confirm stories are created.

I have included the contents of dss/storybook/generator.py for direct reference.