noah-cursor 1.1.0 → 1.3.0

package/dist/noah-registry/skills/larastan-fix/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: larastan-fix
+description: >-
+  Runs Larastan (PHPStan for Laravel), constructs fixes for all findings, and
+  verifies that implementations, features, and functionalities are not broken
+  after changes. Use when the user runs /larastan-fix, asks to run Larastan,
+  PHPStan on a Laravel app, clean up static analysis errors, or fix Larastan
+  findings without regressions.
+disable-model-invocation: true
+---
+
+# /larastan-fix
+
+Run **Larastan** (PHPStan + Laravel extension), fix **all** findings, and prove behavior still works.
+
+Do **not** stop after the first file. Do **not** mass-ignore or regenerate a baseline to “pass.” Prefer root-cause fixes. After every batch of edits, re-verify with project checks so implementations, features, and functionalities are not broken.
+
+## Workflow
+
+Copy this checklist and track progress:
+
+```
+Larastan Fix Progress:
+- [ ] 1. Confirm Laravel project + Larastan setup + verification commands
+- [ ] 2. Baseline analyse
+- [ ] 3. Triage findings (priority order)
+- [ ] 4. Fix in batches (explain → edit → verify)
+- [ ] 5. Re-analyse until clean (or document intentional leftovers)
+- [ ] 6. Final verification + report
+```
+
+### 1. Confirm Laravel project + Larastan setup + verification commands
+
+From the project root:
+
+1. Confirm this is a Laravel app (`artisan`, `composer.json` with `laravel/framework`) — abort with a clear message if not.
+2. Confirm Larastan is available:
+
+```bash
+composer show larastan/larastan 2>/dev/null || composer show nunomaduro/larastan 2>/dev/null
+test -f phpstan.neon -o -f phpstan.neon.dist -o -f phpstan.dist.neon
+test -x vendor/bin/phpstan
+```
+
+If Larastan / PHPStan is missing, install only with user approval:
+
+```bash
+composer require --dev larastan/larastan
+```
+
+Ensure config includes the Larastan extension (create `phpstan.neon` only if none exists and the user wants setup):
+
+```neon
+includes:
+    - vendor/larastan/larastan/extension.neon
+    - vendor/nesbot/carbon/extension.neon
+
+parameters:
+    paths:
+        - app/
+    level: 5
+```
+
+Do **not** raise the configured level unless the user asks. Analyse at the project’s configured level.
+
+3. Detect verification commands. Prefer existing Composer / Artisan scripts:
+
+```bash
+composer test                    # or phpunit / pest
+php artisan test
+vendor/bin/pest
+vendor/bin/phpunit
+vendor/bin/pint --test           # style check only; not a substitute for tests
+php artisan route:list           # smoke when helpful
+```
+
+Record the chosen commands before editing. If no tests exist, say so and still use the strongest available checks (at least a second Larastan run + Pint if present).
+
+### 2. Baseline analyse
+
+Use the project binary (respects `phpstan.neon*`):
+
+```bash
+./vendor/bin/phpstan analyse --memory-limit=2G
+```
+
+If Composer defines a script (`composer phpstan` / `composer analyse`), prefer that.
+
+For machine-readable output when practical:
+
+```bash
+./vendor/bin/phpstan analyse --memory-limit=2G --error-format=json > .larastan-baseline.json
+```
+
+Delete or leave untracked any temporary report files before finishing.
+
+Path-scoped cleanup only when the user asks:
+
+```bash
+./vendor/bin/phpstan analyse app/Http/Controllers --memory-limit=2G
+```
+
+Default for this skill is a **full** configured analyse unless the user scopes it.
+
+### 3. Triage findings
+
+Work findings in this priority:
+
+1. **Runtime-breaking** — undefined methods/properties, wrong argument counts, impossible types that would crash
+2. **Null safety** — unsafe property/method access on nullable models, requests, relations
+3. **Laravel / Eloquent correctness** — wrong relation types, builder misuse, container/`auth`/`request` type gaps Larastan flags
+4. **PHPDoc / generics** — collection/model generics, `@var` / `@param` / `@return` that hide real bugs
+5. **Dead code / unreachable** — always-true/false conditions, unused private methods (only remove when safe)
+6. **Remaining level noise** — stricter level complaints that need small, local typing improvements
+
+Group by file or by shared root cause (e.g. one incomplete Form Request type used everywhere).
+
+### 4. Fix in batches (explain → edit → verify)
+
+For each batch (prefer one error identifier / one file group):
+
+1. **Explain the fix** briefly: what PHPStan reported, why the change is safe, what runtime behavior must stay the same.
+2. **Edit** the minimum code needed. Match Laravel project patterns (Form Requests, Actions, Eloquent APIs, API Resources).
+3. **Verify immediately** with the commands from step 1 (fastest relevant suite after each batch; full suite before the final report).
+4. If verification fails: **revert or repair** before continuing. Never leave the tree broken to chase a clean Larastan run.
+
+#### Fix construction rules
+
+- Preserve HTTP contracts: routes, status codes, JSON shapes, validation rules, auth/gates, jobs/events side effects.
+- Prefer real types and narrowing (`=== null` checks, early returns, assert helpers) over silencing.
+- Prefer accurate PHPDoc / generics on Eloquent models and collections when the code is already correct.
+- Do not change business logic to satisfy the analyser when a precise type assertion or request DTO is enough.
+- Do not upgrade Laravel/PHP major versions or rewrite architecture unless the user expands scope.
+- Keep diffs small and reviewable.
+
+#### Ignores / baseline (last resort only)
+
+Prefer fixing the root cause. Use ignores only when:
+
+- the finding is a true false positive for this Laravel version/package, **or**
+- a correct fix would be an out-of-scope rewrite the user did not approve
+
+Narrow inline ignore:
+
+```php
+// @phpstan-ignore-next-line
+```
+
+Or identifier-based ignores when the project PHPStan version supports them. Prefer next-line / specific `ignoreErrors` path patterns over global rules.
+
+Do **not** run `--generate-baseline` to clear findings unless the user explicitly asks for a baseline workflow.
+
+Document every ignore in the final report with file, message/identifier, and reason.
+
+### 5. Re-analyse until clean
+
+After fixes:
+
+```bash
+./vendor/bin/phpstan analyse --memory-limit=2G
+```
+
+Repeat triage → fix → verify until:
+
+- analyse exits 0 with no errors, **or**
+- only explicitly approved / documented ignores or deferred items remain
+
+Do not claim “all clear” if analyse still fails.
+
+### 6. Final verification + report
+
+Run the full verification set from step 1 again.
+
+Report in this shape:
+
+```markdown
+## Larastan fix report
+
+### Analyse
+- Config: <phpstan.neon*|level>
+- Baseline: <N errors>
+- Final: <clean | N remaining>
+
+### Fixed
+- <error summary> — file(s) — one-line fix summary
+
+### Ignores
+- none | file:line — reason
+
+### Verification
+- <command> — pass/fail
+- <command> — pass/fail
+
+### Deferred (needs user decision)
+- <finding> — why not fixed
+```
+
+## Safety
+
+- Do not commit or push unless the user asks.
+- Do not use `--force` git commands.
+- Do not commit secrets (`.env`, credentials).
+- Stop and ask if a “fix” requires deleting substantial features, changing API contracts, or broad behavioral changes.

package/dist/noah-registry/skills/nestjs-knip-fix/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: nestjs-knip-fix
+description: >-
+  Runs Knip on NestJS projects, constructs fixes for unused files, exports, and
+  dependencies, and verifies that implementations, features, and functionalities
+  are not broken after changes. Use when the user runs /nestjs-knip-fix, asks
+  to run knip on NestJS, clean up unused NestJS code, or fix Knip findings
+  without regressions.
+disable-model-invocation: true
+---
+
+# /nestjs-knip-fix
+
+Run **`npx knip`** on a **NestJS** app, fix **all** findings, and prove behavior still works.
+
+Do **not** stop after the first issue type. Do **not** mass-ignore. Prefer root-cause removals and export cleanups. After every batch of edits, re-verify so implementations, features, and functionalities are not broken.
+
+## Workflow
+
+Copy this checklist and track progress:
+
+```
+NestJS Knip Fix Progress:
+- [ ] 1. Confirm NestJS project + verification commands
+- [ ] 2. Ensure Knip config (Nest-aware)
+- [ ] 3. Baseline knip scan
+- [ ] 4. Triage findings (priority order)
+- [ ] 5. Fix in batches (explain → edit → verify)
+- [ ] 6. Re-scan until clean (or document intentional leftovers)
+- [ ] 7. Final verification + report
+```
+
+### 1. Confirm NestJS project + verification commands
+
+From the project root:
+
+1. Confirm NestJS (`@nestjs/core` in `package.json`, usually `nest-cli.json` / `src/main.ts`) — abort if not.
+2. Detect verification commands (prefer existing scripts):
+
+```bash
+npm test                 # or pnpm / yarn / bun
+npm run test:e2e
+npm run build            # nest build / tsc
+npm run lint
+npx tsc --noEmit
+```
+
+Record the chosen commands before editing.
+
+### 2. Ensure Knip config (Nest-aware)
+
+If the project has no `knip.json` / `knip.ts` / `knip` field in `package.json`, copy the skill template into the project root as `knip.json`:
+
+- Template: [`config/knip.nestjs.json`](config/knip.nestjs.json)
+
+Adjust `entry` / `project` for monorepos (`apps/*`, `libs/*`) when needed. Prefer extending the template over inventing a blank config.
+
+Do not overwrite an existing Knip config unless the user asks — merge Nest entry patterns into the existing config instead.
+
+### 3. Baseline knip scan
+
+```bash
+npx knip --no-progress
+```
+
+If a local config path is required:
+
+```bash
+npx knip --config knip.json --no-progress
+```
+
+Optional production-only pass (after the default scan is clean or when the user asks):
+
+```bash
+npx knip --production --no-progress
+```
+
+Capture output for triage. Default for this skill is a **full** workspace scan unless the user scopes it.
+
+### 4. Triage findings
+
+Work findings in this priority:
+
+1. **Unused dependencies / devDependencies** — remove from `package.json` only after confirming Nest/CLI/plugins do not need them
+2. **Unlisted dependencies** — add the real import to `dependencies` / `devDependencies` (do not rely on transitive deps)
+3. **Unused files** — delete only when not dynamically loaded (`i18n`, `assets`, `path.join(__dirname, …)`, Nest schematics paths)
+4. **Unused exports** — remove `export` or delete dead symbols; keep Nest decorators’ public APIs (`@Module` providers/controllers/imports that Knip misunderstands → fix config, don’t gut the module)
+5. **Duplicate / enum / namespace export noise** — resolve carefully; suppress only as last resort
+
+**NestJS cautions**
+
+- Controllers, providers, guards, interceptors, pipes, filters registered only via module metadata must stay reachable from entry modules — if Knip says unused, verify `*.module.ts` wiring first.
+- Do not remove `main.ts`, `app.module.ts`, or Nest CLI schematics entrypoints.
+- Spec / e2e files: prefer config `ignore` / project patterns over deleting tests.
+
+### 5. Fix in batches (explain → edit → verify)
+
+For each batch:
+
+1. **Explain** what Knip reported and why the change is safe.
+2. **Edit** the minimum (package.json, exports, delete files).
+3. **Verify** with build + unit tests (and e2e when relevant).
+4. If verification fails: **revert or repair** before continuing.
+
+#### Fix construction rules
+
+- Preserve HTTP routes, DTO contracts, swagger models, queues, cron jobs, and microservice patterns.
+- Prefer removing unused exports over deleting whole Nest providers that are still registered.
+- Run `npm install` / lockfile update after dependency changes.
+- Keep diffs small. No drive-by refactors.
+
+#### Ignores (last resort)
+
+Use Knip `ignore`, `ignoreDependencies`, or `ignoreBinaries` only for true false positives (Nest dynamic modules, intentional public SDK barrels). Document each ignore in the final report.
+
+### 6. Re-scan until clean
+
+```bash
+npx knip --no-progress
+```
+
+Repeat until exit 0 or only approved ignores remain.
+
+### 7. Final verification + report
+
+```markdown
+## NestJS Knip fix report
+
+### Scan
+- Baseline: <summary>
+- Final: <clean | remaining>
+
+### Fixed
+- <issue type> — <what changed>
+
+### Ignores / config
+- none | <item> — reason
+
+### Verification
+- <command> — pass/fail
+```
+
+## Safety
+
+- Do not commit or push unless the user asks.
+- Do not delete `.env` or secrets.
+- Stop and ask before removing large feature modules or public API packages.

package/dist/noah-registry/skills/nestjs-knip-fix/config/knip.nestjs.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://unpkg.com/knip@5/schema.json",
+  "entry": [
+    "src/main.ts",
+    "src/main.js",
+    "apps/**/src/main.ts",
+    "src/**/*.module.ts",
+    "apps/**/*.module.ts",
+    "libs/**/src/index.ts",
+    "test/**/*.ts",
+    "test/**/*.js"
+  ],
+  "project": [
+    "src/**/*.{ts,js}",
+    "apps/**/*.{ts,js}",
+    "libs/**/*.{ts,js}",
+    "test/**/*.{ts,js}"
+  ],
+  "ignore": [
+    "**/*.spec.ts",
+    "**/*.e2e-spec.ts",
+    "dist/**",
+    "coverage/**"
+  ],
+  "ignoreDependencies": [
+    "@nestjs/schematics",
+    "@nestjs/testing"
+  ]
+}

package/dist/noah-registry/skills/node-doctor-fix/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: node-doctor-fix
+description: >-
+  Runs the bundled node-doctor tool (Knip + package hygiene) on generic Node.js
+  projects, constructs fixes for all findings, and verifies that implementations,
+  features, and functionalities are not broken after changes. Use when the user
+  runs /node-doctor-fix, asks to doctor a Node.js package/CLI, clean unused
+  Node exports/deps, or fix node-doctor findings without regressions.
+disable-model-invocation: true
+---
+
+# /node-doctor-fix
+
+Run the bundled **`node-doctor`** tool on a **generic Node.js** project (library, CLI, or service — not Nest/Next-first apps), fix **all** findings, and prove behavior still works.
+
+`node-doctor` = **Knip** (unused files / exports / dependencies) using [`config/node-doctor.knip.json`](config/node-doctor.knip.json) when the project has no Knip config, **plus** package hygiene checks (`bin` / `main` / `exports` / script paths / `engines.node`).
+
+Do **not** mass-ignore. Prefer root-cause fixes. After every batch of edits, re-verify so implementations, features, and functionalities are not broken.
+
+## Workflow
+
+Copy this checklist and track progress:
+
+```
+Node Doctor Fix Progress:
+- [ ] 1. Confirm Node project + route frameworks elsewhere
+- [ ] 2. Baseline node-doctor scan
+- [ ] 3. Triage findings (priority order)
+- [ ] 4. Fix in batches (explain → edit → verify)
+- [ ] 5. Re-scan until clean (or document intentional leftovers)
+- [ ] 6. Final verification + report
+```
+
+### 1. Confirm Node project + route frameworks elsewhere
+
+From the project root:
+
+1. Confirm `package.json` exists.
+2. If the app is primarily **NestJS** → use `/nestjs-knip-fix` instead.
+3. If the app is primarily **React** → use `/react-doctor-fix` (optionally Knip later).
+4. Detect verification commands:
+
+```bash
+npm test
+npm run typecheck   # or npx tsc --noEmit
+npm run lint
+npm run build
+node ./dist/index.js --help   # CLIs when applicable
+```
+
+### 2. Baseline node-doctor scan
+
+Resolve the skill directory (installed under `.cursor/skills/node-doctor-fix` or this registry path), then:
+
+```bash
+node <skillDir>/scripts/node-doctor.mjs . --json > .node-doctor-baseline.json
+node <skillDir>/scripts/node-doctor.mjs .
+```
+
+Examples:
+
+```bash
+node .cursor/skills/node-doctor-fix/scripts/node-doctor.mjs .
+node skills/node-doctor-fix/scripts/node-doctor.mjs .
+```
+
+Flags:
+
+- `--json` — machine-readable findings
+- `--knip-only` — skip package hygiene
+- `--hygiene-only` — skip Knip
+
+If the project already has `knip.json` / `package.json#knip`, node-doctor uses that for Knip; otherwise it uses the bundled [`config/node-doctor.knip.json`](config/node-doctor.knip.json).
+
+Delete temporary report files before finishing (or keep them untracked).
+
+### 3. Triage findings
+
+Priority:
+
+1. **Broken package entrypoints** — missing `bin` / `main` / `exports` / script paths (hygiene errors)
+2. **Unlisted dependencies** — add real imports to package.json
+3. **Unused dependencies** — remove only when not required by tooling/config plugins
+4. **Unused files** — delete when not dynamically required
+5. **Unused exports / types** — remove or stop exporting
+6. **Hygiene warnings** — e.g. missing `engines.node`
+
+### 4. Fix in batches (explain → edit → verify)
+
+For each batch:
+
+1. **Explain** the finding and why the fix is safe.
+2. **Edit** minimally (`package.json`, exports, delete dead files).
+3. **Verify** with test / typecheck / build / CLI smoke.
+4. On failure: **revert or repair** before continuing.
+
+#### Fix construction rules
+
+- Preserve public package API (`exports`, documented CLI flags, published bin names).
+- Do not remove files loaded dynamically (`fs.readFile`, runtime plugin paths) without proof.
+- Update the lockfile after dependency changes.
+- Do not convert the project into Nest/Next-specific structure.
+
+#### Ignores (last resort)
+
+Prefer fixing. If Knip false-positives remain, add narrow `ignore` / `ignoreDependencies` to the **project** Knip config (create one from the bundled config rather than silencing the tool). Document every ignore.
+
+### 5. Re-scan until clean
+
+```bash
+node <skillDir>/scripts/node-doctor.mjs .
+```
+
+Exit code must be `0` (or only approved documented leftovers remain).
+
+### 6. Final verification + report
+
+```markdown
+## Node doctor fix report
+
+### Scan
+- Baseline: <N findings>
+- Final: <clean | N remaining>
+
+### Fixed
+- <type> — summary
+
+### Ignores / config
+- none | item — reason
+
+### Verification
+- <command> — pass/fail
+```
+
+## Tool reference
+
+| Path | Role |
+|------|------|
+| `scripts/node-doctor.mjs` | CLI analyser |
+| `config/node-doctor.knip.json` | Default Knip config for generic Node |
+
+## Safety
+
+- Do not commit or push unless the user asks.
+- Do not commit secrets.
+- Stop and ask before deleting public API surface or major packages.

package/dist/noah-registry/skills/node-doctor-fix/config/node-doctor.knip.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://unpkg.com/knip@5/schema.json",
+  "entry": [
+    "{index,cli,main,app,server}.{js,cjs,mjs,ts,cts,mts}",
+    "src/{index,cli,main,app,server}.{js,cjs,mjs,ts,cts,mts}",
+    "bin/**/*.{js,cjs,mjs,ts}",
+    "scripts/**/*.{js,cjs,mjs,ts}"
+  ],
+  "project": [
+    "**/*.{js,cjs,mjs,ts,cts,mts}!"
+  ],
+  "ignore": [
+    "**/dist/**",
+    "**/build/**",
+    "**/coverage/**",
+    "**/.next/**",
+    "**/node_modules/**"
+  ],
+  "ignoreBinaries": [
+    "noah-cursor"
+  ]
+}