@cubis/foundry 0.3.64 → 0.3.66

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/code-documenter/references/api-docs-nestjs-express.md

@@ -0,0 +1,223 @@
+# API Documentation: NestJS & Express
+
+> Reference for: Code Documenter
+> Load when: Documenting Node.js API frameworks
+
+## NestJS (@nestjs/swagger)
+
+NestJS requires explicit decorators for OpenAPI documentation.
+
+### Controller Documentation
+
+```typescript
+import { Controller, Post, Body, Get, Param } from '@nestjs/common';
+import {
+  ApiTags,
+  ApiOperation,
+  ApiResponse,
+  ApiParam,
+  ApiBearerAuth,
+} from '@nestjs/swagger';
+
+@ApiTags('Users')
+@ApiBearerAuth()
+@Controller('users')
+export class UsersController {
+  @Post()
+  @ApiOperation({ summary: 'Create a new user' })
+  @ApiResponse({
+    status: 201,
+    description: 'User created successfully',
+    type: UserDto,
+  })
+  @ApiResponse({
+    status: 400,
+    description: 'Invalid input data',
+  })
+  async create(@Body() dto: CreateUserDto): Promise<UserDto> {
+    return this.usersService.create(dto);
+  }
+
+  @Get(':id')
+  @ApiOperation({ summary: 'Get user by ID' })
+  @ApiParam({
+    name: 'id',
+    description: 'User unique identifier',
+    example: '123',
+  })
+  @ApiResponse({ status: 200, type: UserDto })
+  @ApiResponse({ status: 404, description: 'User not found' })
+  async findOne(@Param('id') id: string): Promise<UserDto> {
+    return this.usersService.findOne(id);
+  }
+}
+```
+
+### DTO Documentation
+
+```typescript
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { IsEmail, IsString, MinLength } from 'class-validator';
+
+export class CreateUserDto {
+  @ApiProperty({
+    description: "User's display name",
+    example: 'John Doe',
+    minLength: 1,
+    maxLength: 100,
+  })
+  @IsString()
+  @MinLength(1)
+  name: string;
+
+  @ApiProperty({
+    description: "User's email address",
+    example: 'john@example.com',
+  })
+  @IsEmail()
+  email: string;
+
+  @ApiPropertyOptional({
+    description: 'Profile picture URL',
+    example: 'https://example.com/avatar.jpg',
+  })
+  avatarUrl?: string;
+}
+```
+
+## Express (swagger-jsdoc)
+
+Express uses JSDoc comments with swagger annotations.
+
+### Setup
+
+```javascript
+const swaggerJsdoc = require('swagger-jsdoc');
+const swaggerUi = require('swagger-ui-express');
+
+const options = {
+  definition: {
+    openapi: '3.0.0',
+    info: {
+      title: 'API Documentation',
+      version: '1.0.0',
+    },
+  },
+  apis: ['./routes/*.js'],
+};
+
+const specs = swaggerJsdoc(options);
+app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));
+```
+
+### Route Documentation
+
+```javascript
+/**
+ * @swagger
+ * /users:
+ *   post:
+ *     summary: Create a new user
+ *     tags: [Users]
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             $ref: '#/components/schemas/CreateUser'
+ *     responses:
+ *       201:
+ *         description: User created successfully
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/User'
+ *       400:
+ *         description: Invalid input
+ */
+router.post('/users', createUser);
+
+/**
+ * @swagger
+ * /users/{id}:
+ *   get:
+ *     summary: Get user by ID
+ *     tags: [Users]
+ *     parameters:
+ *       - in: path
+ *         name: id
+ *         required: true
+ *         schema:
+ *           type: string
+ *         description: User ID
+ *     responses:
+ *       200:
+ *         description: User found
+ *         content:
+ *           application/json:
+ *             schema:
+ *               $ref: '#/components/schemas/User'
+ *       404:
+ *         description: User not found
+ */
+router.get('/users/:id', getUser);
+```
+
+### Schema Documentation
+
+```javascript
+/**
+ * @swagger
+ * components:
+ *   schemas:
+ *     CreateUser:
+ *       type: object
+ *       required:
+ *         - name
+ *         - email
+ *       properties:
+ *         name:
+ *           type: string
+ *           description: User's display name
+ *           example: John Doe
+ *         email:
+ *           type: string
+ *           format: email
+ *           description: User's email address
+ *           example: john@example.com
+ *     User:
+ *       allOf:
+ *         - $ref: '#/components/schemas/CreateUser'
+ *         - type: object
+ *           properties:
+ *             id:
+ *               type: string
+ *               description: Unique identifier
+ *             createdAt:
+ *               type: string
+ *               format: date-time
+ */
+```
+
+## Quick Reference
+
+| NestJS Decorator | Purpose |
+|------------------|---------|
+| `@ApiTags()` | Group endpoints |
+| `@ApiOperation()` | Endpoint summary |
+| `@ApiResponse()` | Response documentation |
+| `@ApiParam()` | Path parameter |
+| `@ApiQuery()` | Query parameter |
+| `@ApiBody()` | Request body |
+| `@ApiBearerAuth()` | Auth requirement |
+| `@ApiProperty()` | DTO property |
+
+| Express swagger-jsdoc | Purpose |
+|-----------------------|---------|
+| `@swagger` | Start swagger block |
+| `tags` | Group endpoints |
+| `summary` | Short description |
+| `parameters` | Path/query params |
+| `requestBody` | Request body schema |
+| `responses` | Response schemas |
+| `$ref` | Reference schema |

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/code-documenter/references/coverage-reports.md

@@ -0,0 +1,128 @@
+# Coverage Reports
+
+> Reference for: Code Documenter
+> Load when: Generating documentation reports
+
+## Documentation Coverage Report Template
+
+```markdown
+# Documentation Report: {project_name}
+
+## Summary
+- **Files analyzed**: 45
+- **Functions documented**: 120/150 (80%)
+- **Classes documented**: 25/25 (100%)
+- **API endpoints documented**: 30/30 (100%)
+
+## Coverage Before/After
+- Before: 45%
+- After: 92%
+
+## Files Modified
+
+| File | Functions Added | Notes |
+|------|-----------------|-------|
+| src/services/user.ts | 8 | All public methods |
+| src/services/auth.ts | 5 | Added examples |
+| src/controllers/users.ts | 6 | Added @Api decorators |
+| src/dto/user.dto.ts | 4 | Added @ApiProperty |
+
+## API Documentation
+
+- **Framework**: NestJS
+- **Strategy**: @nestjs/swagger decorators
+- **Swagger UI**: /api/docs
+- **OpenAPI spec**: /api-json
+
+## Documentation Style
+
+- **Python**: Google style docstrings
+- **TypeScript**: JSDoc with @param, @returns
+- **API**: OpenAPI 3.0 via decorators
+
+## Next Steps
+
+### Recommendations
+1. Run `npm run docs:lint` to validate JSDoc
+2. Add `eslint-plugin-jsdoc` to enforce documentation
+3. Consider adding examples for complex functions
+4. Set up documentation CI checks
+
+### Missing Documentation
+| File | Missing | Priority |
+|------|---------|----------|
+| src/utils/crypto.ts | 3 functions | High |
+| src/helpers/date.ts | 2 functions | Medium |
+
+### CI Integration
+```yaml
+# Add to CI pipeline
+- name: Check documentation
+  run: npm run docs:check
+
+- name: Generate API docs
+  run: npm run docs:generate
+```
+```
+
+## Checklist During Documentation
+
+```markdown
+## Documentation Checklist
+
+### Before Starting
+- [ ] Confirmed format preference (Google/JSDoc/etc.)
+- [ ] Identified files to exclude (tests, generated)
+- [ ] Detected framework for API docs
+
+### Functions/Methods
+- [ ] All public functions documented
+- [ ] Parameters described with types
+- [ ] Return values documented
+- [ ] Exceptions/errors documented
+- [ ] Examples added for complex functions
+
+### Classes
+- [ ] Class purpose described
+- [ ] Constructor parameters documented
+- [ ] Public methods documented
+- [ ] Important attributes explained
+
+### API Endpoints
+- [ ] All endpoints have summaries
+- [ ] Request bodies documented
+- [ ] Response schemas defined
+- [ ] Error responses documented
+- [ ] Authentication requirements noted
+
+### Final Checks
+- [ ] Ran documentation linter
+- [ ] Verified Swagger UI renders correctly
+- [ ] No inaccurate documentation
+- [ ] Coverage report generated
+```
+
+## Framework-Specific Linting
+
+```bash
+# JavaScript/TypeScript - ESLint
+npm install eslint-plugin-jsdoc --save-dev
+# Add to .eslintrc: "plugins": ["jsdoc"]
+
+# Python - pydocstyle
+pip install pydocstyle
+pydocstyle --convention=google src/
+
+# Python - interrogate (coverage)
+pip install interrogate
+interrogate -v src/
+```
+
+## Quick Reference
+
+| Metric | Good | Acceptable | Poor |
+|--------|------|------------|------|
+| Function coverage | >90% | 70-90% | <70% |
+| Class coverage | 100% | >90% | <90% |
+| API endpoint coverage | 100% | 100% | <100% |
+| Example coverage | >50% | 30-50% | <30% |

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/code-documenter/references/documentation-systems.md

@@ -0,0 +1,336 @@
+# Documentation Systems & Infrastructure
+
+> Reference for: Code Documenter
+> Load when: Building documentation sites, static generators, multi-version docs, search systems
+
+## Static Site Generators
+
+### Docusaurus (Meta)
+
+```bash
+# Setup
+npx create-docusaurus@latest docs classic
+cd docs && npm start
+
+# Structure
+docs/
+├── docs/           # Documentation pages
+├── blog/           # Blog posts
+├── src/
+│   └── pages/      # Custom pages
+└── docusaurus.config.js
+```
+
+**docusaurus.config.js:**
+```javascript
+module.exports = {
+  title: 'My API',
+  tagline: 'Build amazing things',
+  url: 'https://docs.example.com',
+  baseUrl: '/',
+
+  themeConfig: {
+    navbar: {
+      items: [
+        {to: '/docs/intro', label: 'Docs', position: 'left'},
+        {to: '/api', label: 'API', position: 'left'},
+      ],
+    },
+
+    // Algolia search
+    algolia: {
+      apiKey: 'YOUR_API_KEY',
+      indexName: 'your_index',
+      contextualSearch: true,
+    },
+
+    prism: {
+      theme: lightCodeTheme,
+      darkTheme: darkCodeTheme,
+      additionalLanguages: ['python', 'rust'],
+    },
+  },
+};
+```
+
+### MkDocs (Python)
+
+```yaml
+# mkdocs.yml
+site_name: My API Documentation
+theme:
+  name: material
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - toc.integrate
+    - search.suggest
+    - search.highlight
+  palette:
+    - scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            show_source: true
+  - git-revision-date-localized
+
+markdown_extensions:
+  - pymdownx.highlight
+  - pymdownx.superfences
+  - admonition
+  - codehilite
+
+nav:
+  - Home: index.md
+  - Getting Started: getting-started.md
+  - API Reference: api/
+```
+
+### VitePress (Vue)
+
+```typescript
+// .vitepress/config.ts
+export default defineConfig({
+  title: 'API Docs',
+  description: 'Developer documentation',
+
+  themeConfig: {
+    nav: [
+      { text: 'Guide', link: '/guide/' },
+      { text: 'API', link: '/api/' },
+    ],
+
+    sidebar: {
+      '/guide/': [
+        {
+          text: 'Introduction',
+          items: [
+            { text: 'Getting Started', link: '/guide/getting-started' },
+            { text: 'Configuration', link: '/guide/config' },
+          ],
+        },
+      ],
+    },
+
+    search: {
+      provider: 'local',
+    },
+
+    editLink: {
+      pattern: 'https://github.com/user/repo/edit/main/docs/:path',
+    },
+  },
+});
+```
+
+## Multi-Version Documentation
+
+### Version Switcher
+
+```javascript
+// Docusaurus versions
+{
+  versions: {
+    current: {
+      label: '2.0 (Next)',
+      path: 'next',
+    },
+  },
+  onlyIncludeVersions: ['current', '1.5', '1.4'],
+}
+```
+
+### Migration Guides
+
+```markdown
+# Migration Guide: v1 to v2
+
+## Breaking Changes
+
+### Authentication
+**v1:**
+```python
+client.authenticate(api_key)
+```
+
+**v2:**
+```python
+client = Client(api_key=api_key)  # Pass in constructor
+```
+
+### Renamed Methods
+| v1 | v2 | Notes |
+|----|----|----- |
+| `get_user()` | `fetch_user()` | Async now |
+| `delete_user()` | `remove_user()` | Returns Promise |
+
+## Deprecation Timeline
+- v1.x: Supported until Dec 2025
+- v2.0: Released Jan 2025
+- v2.1: Current (June 2025)
+```
+
+## Search Implementation
+
+### Algolia DocSearch
+
+```html
+<!-- Add to theme -->
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@3" />
+
+<script src="https://cdn.jsdelivr.net/npm/@docsearch/js@3"></script>
+<script>
+  docsearch({
+    appId: 'YOUR_APP_ID',
+    apiKey: 'YOUR_API_KEY',
+    indexName: 'your_index',
+    container: '#docsearch',
+  });
+</script>
+```
+
+### Local Search (Lunr.js)
+
+```javascript
+const idx = lunr(function() {
+  this.ref('id');
+  this.field('title', { boost: 10 });
+  this.field('content');
+
+  documents.forEach(doc => this.add(doc));
+});
+
+// Search
+const results = idx.search('authentication');
+```
+
+## Documentation Testing
+
+### Link Checking
+
+```bash
+# linkcheck (Python)
+pip install linkchecker
+linkchecker http://localhost:3000/docs
+
+# broken-link-checker (Node)
+npm install -g broken-link-checker
+blc http://localhost:3000 -ro
+```
+
+### Code Example Testing
+
+```python
+# doctest for Python examples
+"""
+>>> add(2, 3)
+5
+>>> add(-1, 1)
+0
+"""
+
+# Run tests
+python -m doctest -v docs/*.md
+```
+
+```javascript
+// Jest for TypeScript examples
+// Extract code blocks and test
+import { runExamples } from './test-docs';
+
+test('API examples work', async () => {
+  const examples = extractExamples('./docs/api.md');
+  await expect(runExamples(examples)).resolves.toBeTruthy();
+});
+```
+
+## Performance Optimization
+
+### Build Optimization
+
+```javascript
+// Webpack/Vite config
+export default {
+  build: {
+    rollupOptions: {
+      output: {
+        manualChunks: {
+          'vendor': ['react', 'react-dom'],
+        },
+      },
+    },
+  },
+
+  optimizeDeps: {
+    include: ['prismjs'],
+  },
+};
+```
+
+### CDN & Caching
+
+```nginx
+# nginx.conf
+location /docs {
+  expires 1y;
+  add_header Cache-Control "public, immutable";
+}
+
+location ~* \.(html)$ {
+  expires 1h;
+  add_header Cache-Control "public, must-revalidate";
+}
+```
+
+## Analytics Integration
+
+### Google Analytics
+
+```javascript
+// Docusaurus
+gtag: {
+  trackingID: 'G-XXXXXXXXXX',
+  anonymizeIP: true,
+},
+```
+
+### Custom Analytics
+
+```javascript
+// Track search queries
+function trackSearch(query, results) {
+  analytics.track('docs_search', {
+    query,
+    resultCount: results.length,
+    timestamp: new Date(),
+  });
+}
+```
+
+## Quick Reference
+
+| Tool | Best For | Tech Stack |
+|------|----------|-----------|
+| Docusaurus | React projects, versioning | React, MDX |
+| MkDocs | Python projects, simple setup | Python, Jinja2 |
+| VitePress | Vue projects, fast builds | Vue, Vite |
+| Nextra | Next.js integration | React, Next.js |
+| Mintlify | Modern UI, AI search | React |
+
+| Search Solution | Cost | Features |
+|----------------|------|----------|
+| Algolia DocSearch | Free (OSS) | Fast, typo-tolerant |
+| Local (Lunr.js) | Free | Offline, no server |
+| Typesense | Free (self-host) | Privacy-focused |
+| Meilisearch | Free (self-host) | Fast, relevance |