npm - codeforge-dev - Versions diffs - 1.7.0 → 1.9.0 - Mend

codeforge-dev 1.7.0 → 1.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (158) hide show

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/migration-patterns/references/javascript-migrations.md ADDED Viewed

@@ -0,0 +1,179 @@
+# JavaScript / TypeScript Migration Patterns
+## Express → Fastify
+### Route Mapping
+| Express | Fastify | Notes |
+|---------|---------|-------|
+| `app.get('/path', handler)` | `fastify.get('/path', handler)` | Similar signature |
+| `app.post('/path', handler)` | `fastify.post('/path', handler)` | Similar signature |
+| `app.use(middleware)` | `fastify.register(plugin)` | Middleware → plugin model |
+| `app.use('/prefix', router)` | `fastify.register(plugin, { prefix: '/prefix' })` | Router → registered plugin |
+### Request / Response API
+| Express | Fastify | Notes |
+|---------|---------|-------|
+| `req.body` | `request.body` | Same concept, different naming convention |
+| `req.params.id` | `request.params.id` | Same |
+| `req.query.page` | `request.query.page` | Same |
+| `req.headers` | `request.headers` | Same |
+| `res.status(200).json(data)` | `reply.code(200).send(data)` | `status` → `code`, `json` → `send` |
+| `res.send('text')` | `reply.send('text')` | Same |
+| `res.redirect('/url')` | `reply.redirect('/url')` | Same |
+| `res.set('header', 'value')` | `reply.header('header', 'value')` | `set` → `header` |
+### Middleware → Plugin Conversion
+```javascript
+// Express middleware
+app.use((req, res, next) => {
+  req.startTime = Date.now();
+  next();
+});
+// Fastify equivalent (using hooks)
+fastify.addHook('onRequest', async (request, reply) => {
+  request.startTime = Date.now();
+});
+```
+### Error Handling
+```javascript
+// Express error handler
+app.use((err, req, res, next) => {
+  res.status(err.status || 500).json({ error: err.message });
+});
+// Fastify error handler
+fastify.setErrorHandler((error, request, reply) => {
+  reply.code(error.statusCode || 500).send({ error: error.message });
+});
+```
+### Migration Steps
+1. Install Fastify: `npm install fastify`
+2. Create Fastify app instance to replace Express app
+3. Convert middleware to Fastify plugins/hooks
+4. Convert route handlers (update request/response API calls)
+5. Convert error handling
+6. Update tests to use `fastify.inject()` instead of `supertest`
+7. Remove Express: `npm uninstall express`
+---
+## React Version Upgrades
+### React 17 → 18
+| Change | Action |
+|--------|--------|
+| `ReactDOM.render()` | Replace with `createRoot().render()` |
+| `ReactDOM.hydrate()` | Replace with `hydrateRoot()` |
+| Automatic batching | No code change — now batches all state updates by default |
+| `useId()` hook | New — use for accessible server/client IDs |
+| Strict Mode double-rendering | Now also double-invokes effects in dev mode |
+```javascript
+// React 17
+import ReactDOM from 'react-dom';
+ReactDOM.render(<App />, document.getElementById('root'));
+// React 18
+import { createRoot } from 'react-dom/client';
+const root = createRoot(document.getElementById('root'));
+root.render(<App />);
+```
+### React 18 → 19
+| Change | Action |
+|--------|--------|
+| `forwardRef` | No longer needed — `ref` is a regular prop |
+| `React.lazy` | Now supports server components |
+| Context | `<Context>` replaces `<Context.Provider>` |
+| `use()` hook | New — reads resources (promises, context) during render |
+| `ref` callbacks | Now support cleanup functions (return from callback) |
+| Metadata tags | `<title>`, `<meta>`, `<link>` in components hoist to `<head>` |
+---
+## TypeScript Version Upgrades
+### Key Changes by Version
+| Version | Notable Changes |
+|---------|----------------|
+| 4.7 → 4.8 | Stricter type narrowing in `in` operator |
+| 4.8 → 4.9 | `satisfies` operator |
+| 4.9 → 5.0 | Decorators (TC39 standard), `bundler` module resolution |
+| 5.0 → 5.1 | Easier implicit returns for `undefined`, linked cursors |
+| 5.1 → 5.2 | `using` declarations (explicit resource management) |
+| 5.2 → 5.3 | Import attributes, narrowing in `switch(true)` |
+| 5.3 → 5.4 | `NoInfer<T>` utility type, improved narrowing in closures |
+| 5.4 → 5.5 | Inferred type predicates, regex syntax checking |
+### tsconfig Changes
+| Old Option | New Option | Version |
+|-----------|-----------|---------|
+| `moduleResolution: "node"` | `moduleResolution: "bundler"` | 5.0+ (for bundled apps) |
+| `target: "es2020"` | `target: "es2022"` | 5.0+ (enables native decorators) |
+| `importsNotUsedAsValues` | `verbatimModuleSyntax` | 5.0 (consolidates 3 flags into 1) |
+---
+## CommonJS → ESM Migration
+### Step-by-Step
+1. **Update `package.json`**: Add `"type": "module"`
+2. **Rename if needed**: `.js` files become ESM by default; use `.cjs` for files that must stay CommonJS
+3. **Convert imports**:
+| CommonJS | ESM |
+|----------|-----|
+| `const x = require('pkg')` | `import x from 'pkg'` |
+| `const { a, b } = require('pkg')` | `import { a, b } from 'pkg'` |
+| `module.exports = x` | `export default x` |
+| `module.exports = { a, b }` | `export { a, b }` |
+| `exports.a = x` | `export const a = x` |
+4. **Fix path imports**: ESM requires file extensions in relative imports: `import x from './utils.js'` (not `'./utils'`)
+5. **Replace `__dirname` / `__filename`**:
+```javascript
+// CommonJS
+const dir = __dirname;
+const file = __filename;
+// ESM
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+```
+6. **Replace `require.resolve`**:
+```javascript
+// CommonJS
+const resolved = require.resolve('pkg');
+// ESM
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const resolved = require.resolve('pkg');
+```
+7. **Update tooling configs**: Jest, ESLint, and other tools may need config changes for ESM support.
+### Common Gotchas
+- JSON imports require import assertions: `import data from './data.json' with { type: 'json' }`
+- Dynamic imports (`import()`) return a module namespace object with a `.default` property
+- Top-level `await` is available in ESM (not in CommonJS)
+- Some packages only export CommonJS — use `import pkg from 'pkg'` (default import) or dynamic `import()`

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/migration-patterns/references/python-migrations.md ADDED Viewed

@@ -0,0 +1,141 @@
+# Python Migration Patterns
+## Python Version Upgrades (3.8 → 3.12)
+### Typing Modernization
+| Old Pattern (3.8) | New Pattern (3.10+) | Search Pattern |
+|-------------------|---------------------|----------------|
+| `Optional[X]` | `X \| None` | `from typing import Optional` |
+| `Union[X, Y]` | `X \| Y` | `from typing import Union` |
+| `List[str]` | `list[str]` | `from typing import List` |
+| `Dict[str, int]` | `dict[str, int]` | `from typing import Dict` |
+| `Tuple[int, ...]` | `tuple[int, ...]` | `from typing import Tuple` |
+| `Set[str]` | `set[str]` | `from typing import Set` |
+| `FrozenSet[str]` | `frozenset[str]` | `from typing import FrozenSet` |
+| `Type[X]` | `type[X]` | `from typing import Type` |
+**Migration step**: Replace all `typing` imports of built-in generics with lowercase equivalents. Remove unused `typing` imports after replacement.
+### Deprecated / Removed Modules
+| Module | Removed In | Replacement |
+|--------|-----------|-------------|
+| `distutils` | 3.12 | `setuptools`, `shutil` |
+| `imp` | 3.12 | `importlib` |
+| `lib2to3` | 3.13 | `libcst` or manual |
+| `aifc` | 3.13 | Third-party audio libraries |
+| `cgi` | 3.13 | `urllib.parse`, `email.message` |
+| `cgitb` | 3.13 | `traceback` |
+### collections.abc Migration
+```python
+# Old (deprecated in 3.9, removed warning in 3.10+)
+from collections import MutableMapping, Sequence, Iterable
+# New
+from collections.abc import MutableMapping, Sequence, Iterable
+```
+Search for: `from collections import` and check if any imported names are ABCs.
+### asyncio Changes
+| Old Pattern | New Pattern (3.10+) | Version |
+|------------|---------------------|---------|
+| `asyncio.get_event_loop()` | `asyncio.get_running_loop()` (in async context) | 3.10 |
+| `@asyncio.coroutine` / `yield from` | `async def` / `await` | 3.8 (removed 3.11) |
+| `loop.create_task()` | `asyncio.create_task()` | 3.7 |
+| `asyncio.wait(tasks)` | `asyncio.wait(tasks)` (must pass set) | 3.11 |
+---
+## Pydantic v1 → v2
+### Complete API Mapping
+| Pydantic v1 | Pydantic v2 | Notes |
+|-------------|-------------|-------|
+| `@validator('field')` | `@field_validator('field')` | Import from `pydantic` |
+| `@validator('field', pre=True)` | `@field_validator('field', mode='before')` | `mode='before'` replaces `pre=True` |
+| `@validator('field', always=True)` | `@field_validator('field')` + `@model_validator` | `always` removed; use model validator for defaults |
+| `@root_validator` | `@model_validator` | Import from `pydantic` |
+| `@root_validator(pre=True)` | `@model_validator(mode='before')` | Mode parameter |
+| `.dict()` | `.model_dump()` | Method renamed |
+| `.json()` | `.model_dump_json()` | Method renamed |
+| `.parse_obj(data)` | `.model_validate(data)` | Class method renamed |
+| `.parse_raw(json_str)` | `.model_validate_json(json_str)` | Class method renamed |
+| `.schema()` | `.model_json_schema()` | Class method renamed |
+| `.construct()` | `.model_construct()` | Class method renamed |
+| `.copy()` | `.model_copy()` | Method renamed |
+| `class Config:` | `model_config = ConfigDict(...)` | Inline config dict |
+| `Config.schema_extra` | `model_config = ConfigDict(json_schema_extra=...)` | Renamed field |
+| `Config.orm_mode = True` | `model_config = ConfigDict(from_attributes=True)` | Renamed field |
+| `Config.allow_population_by_field_name` | `model_config = ConfigDict(populate_by_name=True)` | Renamed field |
+| `Field(regex=...)` | `Field(pattern=...)` | Parameter renamed |
+### Migration Steps
+1. Update `pydantic` version in manifest: `pydantic>=2.0`
+2. Convert `class Config:` blocks to `model_config = ConfigDict(...)` — add `from pydantic import ConfigDict`
+3. Convert `@validator` to `@field_validator` — update signatures (first arg is now `cls`, values accessed differently)
+4. Convert `@root_validator` to `@model_validator` — update mode parameter
+5. Replace `.dict()` → `.model_dump()`, `.json()` → `.model_dump_json()`
+6. Replace `.parse_obj()` → `.model_validate()`, `.parse_raw()` → `.model_validate_json()`
+7. Run `pytest` after each step
+### Validator Signature Change
+```python
+# v1
+@validator('name')
+def validate_name(cls, v, values):
+    return v.strip()
+# v2
+@field_validator('name')
+@classmethod
+def validate_name(cls, v: str, info: ValidationInfo) -> str:
+    return v.strip()
+```
+Note: In v2, `info.data` replaces `values` for accessing other fields.
+---
+## Django Version Upgrades
+### Common Breaking Changes by Version
+| Version | Key Changes |
+|---------|------------|
+| 3.2 → 4.0 | `default_app_config` removed, `USE_L10N` default changed to True |
+| 4.0 → 4.1 | Async view support expanded, `assertFormError` signature changed |
+| 4.1 → 4.2 | `CSRF_TRUSTED_ORIGINS` requires scheme, psycopg3 support |
+| 4.2 → 5.0 | `DEFAULT_AUTO_FIELD` required, `logout()` changed to POST-only |
+| 5.0 → 5.1 | `LoginRequiredMiddleware` added, `HttpResponse.content` stricter |
+### Migration Steps
+1. Run `python -m django check --deploy` to identify deprecation warnings.
+2. Read the release notes for each version between current and target.
+3. Upgrade one minor version at a time (4.0→4.1→4.2, not 4.0→4.2).
+4. Run `python manage.py migrate` and `python manage.py test` after each version bump.
+---
+## SQLAlchemy 1.x → 2.x
+### Key Changes
+| SQLAlchemy 1.x | SQLAlchemy 2.x | Notes |
+|----------------|----------------|-------|
+| `session.query(Model)` | `select(Model)` + `session.execute()` | New select() style |
+| `query.filter()` | `select().where()` | Method renamed |
+| `query.all()` | `session.execute(stmt).scalars().all()` | Execution separated from query building |
+| `Column(Integer)` | `mapped_column(Integer)` | New declarative style |
+| `relationship()` | `relationship()` | Mostly compatible |
+| `engine.execute()` | Removed | Use `with engine.connect() as conn: conn.execute()` |
+Run with `SQLALCHEMY_WARN_20=1` environment variable to get deprecation warnings for 1.x patterns before migrating.

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/spec-check/SKILL.md ADDED Viewed

@@ -0,0 +1,86 @@
+---
+name: spec-check
+description: >-
+  This skill should be used when the user asks to "check spec status",
+  "audit specs", "which specs are stale", "spec health", "find missing
+  specs", "review spec quality", or needs a comprehensive audit of all
+  specifications in the project.
+version: 0.1.0
+context: fork
+agent: explorer
+---
+# Spec Health Audit
+Audit all specifications in the current project and report their health status.
+## Workflow
+### Step 1: Discover Specs
+```
+Glob: .specs/**/*.md
+```
+If `.specs/` does not exist, report: "No specification directory found. Use `/spec-new` to create your first spec."
+Exclude non-spec files:
+- `ROADMAP.md`
+- `BACKLOG.md`
+- `LESSONS_LEARNED.md`
+- Files in `archive/`
+- `_overview.md` files (report them separately as parent specs)
+### Step 2: Read Each Spec
+For each spec file, extract:
+- **Feature name** from the `# Feature: [Name]` header
+- **Version** from the `**Version:**` field
+- **Status** from the `**Status:**` field
+- **Last Updated** from the `**Last Updated:**` field
+- **Line count** (wc -l)
+- **Sections present** — check for each required section header
+- **Acceptance criteria** — count total, count checked `[x]`
+- **Discrepancies** — check if section has content
+### Step 3: Flag Issues
+For each spec, check these conditions:
+| Issue | Condition | Severity |
+|-------|-----------|----------|
+| **Stale** | Status is `planned` but Last Updated is >30 days ago | High |
+| **Incomplete** | Missing required sections (Intent, Acceptance Criteria, Key Files, Requirements, Out of Scope) | High |
+| **Oversized** | Exceeds 200 lines | Medium |
+| **No criteria** | Acceptance Criteria section is empty or has no checkboxes | High |
+| **Open discrepancies** | Discrepancies section has content | Medium |
+| **Missing as-built** | Status is `implemented` but Implementation Notes is empty | Medium |
+| **Stale paths** | Key Files references paths that don't exist | Low |
+### Step 4: Report
+Output a summary table:
+```
+## Spec Health Report
+| Feature | Version | Status | Updated | Lines | Issues |
+|---------|---------|--------|---------|-------|--------|
+| Session History | v0.2.0 | implemented | 2026-02-08 | 74 | None |
+| Auth Flow | v0.3.0 | planned | 2026-01-15 | 45 | Stale (26 days) |
+| Settings Page | v0.2.0 | partial | 2026-02-05 | 210 | Oversized |
+## Issues Found
+### High Priority
+- **Auth Flow** (`.specs/v0.3.0/auth-flow.md`): Status is `planned` but last updated 26 days ago. Either implementation is stalled or the spec needs an as-built update.
+### Medium Priority
+- **Settings Page** (`.specs/v0.2.0/settings-page.md`): 210 lines exceeds the 200-line limit. Split into sub-specs.
+### Suggested Actions
+1. Run `/spec-update auth-flow` to update the auth flow spec
+2. Split settings-page.md into sub-specs
+```
+If no issues are found, report: "All specs healthy. N specs across M versions."

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/spec-init/SKILL.md ADDED Viewed

@@ -0,0 +1,97 @@
+---
+name: spec-init
+description: >-
+  This skill should be used when the user asks to "initialize specs",
+  "set up specs", "bootstrap specs", "start using specs", "create spec
+  directory", "init specs for this project", or needs to set up the
+  .specs/ directory structure for a project that doesn't have one yet.
+version: 0.1.0
+---
+# Initialize Specification Directory
+## Mental Model
+Before any spec can be created, the project needs a `.specs/` directory with its supporting files: a ROADMAP (what each version delivers) and a BACKLOG (deferred items). This skill bootstraps that structure so `/spec-new` has a home.
+---
+## Workflow
+### Step 1: Check Existing State
+```
+Glob: .specs/**/*.md
+```
+**If `.specs/` already exists:**
+- Report current state: how many specs, versions, whether ROADMAP.md and BACKLOG.md exist
+- Suggest `/spec-check` to audit health instead
+- Do NOT recreate or overwrite anything
+- Stop here
+**If `.specs/` does not exist:** proceed to Step 2.
+### Step 2: Create Directory Structure
+Create the `.specs/` directory at the project root.
+### Step 3: Create ROADMAP.md
+Write `.specs/ROADMAP.md` using the template from `references/roadmap-template.md`.
+### Step 4: Create BACKLOG.md
+Write `.specs/BACKLOG.md` using the template from `references/backlog-template.md`.
+### Step 5: Retroactive Documentation
+Ask the user:
+> "Are there existing features in this project that should be documented retroactively? I can help create specs for them using `/spec-new`."
+If yes, guide the user through creating a spec for each feature using `/spec-new`.
+If no, proceed to Step 6.
+### Step 6: Report
+Summarize what was created:
+```
+## Spec Directory Initialized
+Created:
+- `.specs/` directory
+- `.specs/ROADMAP.md` — version tracking table
+- `.specs/BACKLOG.md` — deferred items list
+Next steps:
+- Use `/spec-new <feature-name> <version>` to create your first feature spec
+- Use `/spec-check` to audit spec health at any time
+```
+---
+## Hard Constraints
+- **Never overwrite** an existing `.specs/` directory or its contents.
+- **ROADMAP.md** must stay under 30 lines (it's a summary, not a plan document).
+- **BACKLOG.md** must stay under 15 lines (it grows as items are added).
+- Templates are starting points — the user will extend them.
+---
+## Ambiguity Policy
+- If the user runs this in a workspace root with multiple projects, ask which project to initialize.
+- If `.specs/` exists but is missing ROADMAP.md or BACKLOG.md, offer to create only the missing files.
+---
+## Reference Files
+| File | Contents |
+|------|----------|
+| `references/roadmap-template.md` | Starter ROADMAP with version table format |
+| `references/backlog-template.md` | Starter BACKLOG with item format |

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/spec-init/references/backlog-template.md ADDED Viewed

@@ -0,0 +1,7 @@
+# Backlog
+Deferred items not yet scheduled for a version.
+## Items
+- [ ] [Item description] — [context/rationale]

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/spec-init/references/roadmap-template.md ADDED Viewed

@@ -0,0 +1,13 @@
+# Roadmap
+What each version delivers and why.
+| Version | Status | Summary |
+|---------|--------|---------|
+| v0.1.0  | planned | [Initial release — describe core features] |
+## Versioning
+- **Major**: Breaking changes to public APIs or data models
+- **Minor**: New features, non-breaking changes
+- **Patch**: Bug fixes, documentation, internal refactors

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/spec-new/SKILL.md ADDED Viewed

@@ -0,0 +1,101 @@
+---
+name: spec-new
+description: >-
+  This skill should be used when the user asks to "create a spec",
+  "new feature spec", "write a spec for", "spec this feature",
+  "start a new spec", "plan a feature", or needs to create a new
+  specification file from the standard template.
+version: 0.1.0
+---
+# Create New Feature Specification
+## Mental Model
+A specification is a contract between the person requesting a feature and the person building it. Writing the spec BEFORE implementation forces you to think through edge cases, acceptance criteria, and scope boundaries while changes are cheap — before any code exists.
+Every project uses `.specs/` as the specification directory. Specs are version-organized, independently loadable, and capped at 200 lines.
+---
+## Workflow
+### Step 1: Parse Arguments
+Extract the feature name and version from `$ARGUMENTS`:
+- **Feature name**: kebab-case identifier (e.g., `session-history`, `auth-flow`)
+- **Version**: semver string (e.g., `v0.3.0`)
+If arguments are missing, ask the user for:
+1. Feature name (what is being built)
+2. Target version (which release this belongs to)
+### Step 2: Determine File Path
+- **Multi-feature version** (directory already exists or multiple features planned):
+  `.specs/{version}/{feature-name}.md`
+- **Single-feature version** (one spec covers the whole version):
+  `.specs/{version}.md`
+If `.specs/` does not exist at the project root, create it.
+If `.specs/{version}/` does not exist and you're using the directory form, create it.
+### Step 3: Create the Spec File
+Write the file using the standard template from `references/template.md`.
+Pre-fill:
+- **Version**: from arguments
+- **Status**: `planned`
+- **Last Updated**: today's date (YYYY-MM-DD)
+- **Feature name**: from arguments
+Leave all other sections as placeholders for the user to fill.
+### Step 4: Guide Content Creation
+After creating the file, guide the user through filling it out:
+1. **Intent** — What problem does this solve? Who has this problem? (2-3 sentences)
+2. **Acceptance Criteria** — Use the `specification-writing` skill for EARS format and Given/When/Then patterns
+3. **Key Files** — Glob the codebase to identify existing files relevant to this feature
+4. **Schema / Data Model** — Reference file paths only, never inline schemas
+5. **API Endpoints** — Table format: Method | Path | Description
+6. **Requirements** — EARS format, numbered FR-1, FR-2, NFR-1, etc.
+7. **Dependencies** — What this feature depends on
+8. **Out of Scope** — Explicit non-goals to prevent scope creep
+### Step 5: Validate
+Before finishing:
+- [ ] File is ≤200 lines
+- [ ] No source code, SQL, or type definitions reproduced inline
+- [ ] Status is `planned`
+- [ ] All required sections present (even if some are "N/A" or "TBD")
+- [ ] Acceptance criteria are testable
+---
+## Hard Constraints
+- **≤200 lines per spec.** If a feature needs more, split into sub-specs with a parent `_overview.md` (≤50 lines) linking them.
+- **Reference, don't reproduce.** Write `see src/engine/db/migrations/002.sql lines 48-70` — never paste the SQL.
+- **Independently loadable.** Each spec file must be useful without loading any other file.
+- **EARS format for requirements.** Use the `specification-writing` skill for templates and examples.
+---
+## Ambiguity Policy
+- If the user doesn't specify a version, ask — do not assume.
+- If the feature scope is unclear, write a minimal spec with `## Open Questions` listing what needs clarification.
+- If a spec already exists for this feature, inform the user and suggest `/spec-update` instead.
+---
+## Reference Files
+| File | Contents |
+|------|----------|
+| `references/template.md` | Full standard template with field descriptions and examples |