nightytidy 0.1.0

package/src/prompts/loader.js

@@ -0,0 +1,55 @@
+/**
+ * Loads improvement prompts from individual markdown files.
+ *
+ * Reads manifest.json for step ordering and display names,
+ * then loads each prompt's content from steps/*.md files.
+ * Exports the same interface as the old steps.js: STEPS array
+ * of { number, name, prompt } plus DOC_UPDATE_PROMPT, CHANGELOG_PROMPT, and CONSOLIDATION_PROMPT.
+ *
+ * Uses `export let` for ESM live bindings — reloadSteps() can
+ * reassign these after a sync, and all importers see updated values.
+ */
+
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import path from 'path';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function loadFile(...segments) {
+  return readFileSync(path.join(__dirname, ...segments), 'utf8');
+}
+
+function loadAllSteps() {
+  const m = JSON.parse(loadFile('manifest.json'));
+  return m.steps.map((entry, index) => ({
+    number: index + 1,
+    name: entry.name,
+    prompt: loadFile('steps', `${entry.id}.md`),
+  }));
+}
+
+export let STEPS = loadAllSteps();
+
+export let DOC_UPDATE_PROMPT = loadFile('specials', 'doc-update.md');
+
+export let CHANGELOG_PROMPT = loadFile('specials', 'changelog.md');
+
+export let CONSOLIDATION_PROMPT = loadFile('specials', 'consolidation.md');
+
+export let REPORT_PROMPT = loadFile('specials', 'report.md');
+
+/**
+ * Re-read manifest and all prompt files from disk.
+ * Uses ESM live bindings — all importers see the updated values
+ * through their existing binding references.
+ *
+ * Call this after syncPrompts() writes new files to disk.
+ */
+export function reloadSteps() {
+  STEPS = loadAllSteps();
+  DOC_UPDATE_PROMPT = loadFile('specials', 'doc-update.md');
+  CHANGELOG_PROMPT = loadFile('specials', 'changelog.md');
+  CONSOLIDATION_PROMPT = loadFile('specials', 'consolidation.md');
+  REPORT_PROMPT = loadFile('specials', 'report.md');
+}

package/src/prompts/manifest.json

@@ -0,0 +1,138 @@
+{
+  "version": 1,
+  "sourceUrl": "https://docs.google.com/document/d/e/2PACX-1vRtQJyud1t-ESLJqKXTdBGTzFnkxFvZRKJ8_MrOjSGn4fmBluXWVTvJZFIxgSefVag8MoAW8bd0-A6K/pub",
+  "steps": [
+    {
+      "id": "01-documentation",
+      "name": "Documentation"
+    },
+    {
+      "id": "02-test-coverage",
+      "name": "Test Coverage"
+    },
+    {
+      "id": "03-test-hardening",
+      "name": "Test Hardening"
+    },
+    {
+      "id": "04-test-architecture",
+      "name": "Test Architecture"
+    },
+    {
+      "id": "05-test-consolidation",
+      "name": "Test Consolidation"
+    },
+    {
+      "id": "06-test-quality",
+      "name": "Test Quality"
+    },
+    {
+      "id": "07-api-design",
+      "name": "API Design"
+    },
+    {
+      "id": "08-security-sweep",
+      "name": "Security Sweep"
+    },
+    {
+      "id": "09-dependency-health",
+      "name": "Dependency Health"
+    },
+    {
+      "id": "10-codebase-cleanup",
+      "name": "Codebase Cleanup"
+    },
+    {
+      "id": "11-crosscutting-concerns",
+      "name": "Cross-Cutting Concerns"
+    },
+    {
+      "id": "12-file-decomposition",
+      "name": "File Decomposition"
+    },
+    {
+      "id": "13-code-elegance",
+      "name": "Code Elegance"
+    },
+    {
+      "id": "14-architectural-complexity",
+      "name": "Architectural Complexity"
+    },
+    {
+      "id": "15-type-safety",
+      "name": "Type Safety"
+    },
+    {
+      "id": "16-logging-error-message",
+      "name": "Logging & Error Message"
+    },
+    {
+      "id": "17-data-integrity",
+      "name": "Data Integrity"
+    },
+    {
+      "id": "18-performance",
+      "name": "Performance"
+    },
+    {
+      "id": "19-cost-resource-optimization",
+      "name": "Cost & Resource Optimization"
+    },
+    {
+      "id": "20-error-recovery",
+      "name": "Error Recovery"
+    },
+    {
+      "id": "21-race-condition-audit",
+      "name": "Race Condition Audit"
+    },
+    {
+      "id": "22-bug-hunt",
+      "name": "Bug Hunt"
+    },
+    {
+      "id": "23-frontend-quality",
+      "name": "Frontend Quality"
+    },
+    {
+      "id": "24-uiux-audit",
+      "name": "UI/UX Audit"
+    },
+    {
+      "id": "25-state-management",
+      "name": "State Management"
+    },
+    {
+      "id": "26-perceived-performance",
+      "name": "Perceived Performance"
+    },
+    {
+      "id": "27-devops",
+      "name": "DevOps"
+    },
+    {
+      "id": "28-scheduled-job-chron-jobs",
+      "name": "Scheduled Job & Chron Jobs"
+    },
+    {
+      "id": "29-observability",
+      "name": "Observability"
+    },
+    {
+      "id": "30-backup-check",
+      "name": "Backup Check"
+    },
+    {
+      "id": "31-product-polish-ux-friction",
+      "name": "Product Polish & UX Friction"
+    },
+    {
+      "id": "32-feature-discovery-opportunity",
+      "name": "Feature Discovery & Opportunity"
+    },
+    {
+      "id": "33-strategic-opportunities",
+      "name": "Strategic Opportunities"
+    }
+  ]
+}

package/src/prompts/specials/changelog.md

@@ -0,0 +1,28 @@
+You just finished an overnight codebase improvement run. Your job now is to write a plain-English summary of everything that changed — written for someone who is NOT a developer.
+
+Review the full git log and diffs for this run (all commits on this branch). Then write a summary that:
+
+1. Uses first person ("I") as if you personally worked on the codebase overnight
+2. Uses zero jargon — explain everything in terms a non-technical person would understand
+3. References SPECIFIC numbers from the actual changes (e.g., "I added 47 tests" not "I improved test coverage"; "I removed 1,200 lines of code that weren't being used" not "I cleaned up dead code")
+4. Groups related changes into short, friendly paragraphs — don't use bullet points or headers
+5. Leads with the most impressive or valuable changes first
+6. Keeps the tone warm and slightly proud of the work done — like a helpful colleague leaving a note about what they accomplished overnight
+7. Ends with a brief honest note about anything that didn't go as planned (steps that failed or were skipped), framed constructively
+8. Is no longer than 400 words — concise and scannable
+
+DO NOT use any of these words: refactor, lint, dependency, CI/CD, middleware, endpoint, schema, migration, module, pipeline, coverage metrics, regression, assertion, deprecation.
+
+Instead of technical terms, describe what the change DOES for the person: "I made sure your login page can't be tricked into running malicious code" instead of "I fixed an XSS vulnerability in the auth middleware."
+
+The summary should make a non-technical person feel genuinely excited about the improvements and confident that their codebase is in better shape — without needing to understand a single technical concept.
+
+Output ONLY the summary text. No headers, no markdown formatting, no preamble.
+
+DO NOT start your response with any of these patterns:
+- "I understand" / "I'm ready" / "I'll help" / "Sure" / "Certainly"
+- "Here is" / "Here's" / "Based on" / "Let me"
+- "Of course" / "Absolutely" / "Great"
+- Any acknowledgment of these instructions
+
+Begin your response with the very first word of your actual summary. Your response will be embedded directly into a document — any conversational preamble will be visible to the reader and look broken.

package/src/prompts/specials/consolidation.md

@@ -0,0 +1,61 @@
+You just completed a multi-step automated codebase improvement run. Below are the outputs from each step — what was analyzed, changed, and recommended.
+
+Your task is to produce a **consolidated, prioritized action plan** of recommendations that still need to be done.
+
+## Instructions
+
+1. Review each step's output to extract actionable recommendations, suggestions, and identified issues.
+2. **Check the current codebase** — read the relevant files to determine which recommendations have ALREADY been implemented by previous steps in this run.
+3. **Deduplicate** — if multiple steps flagged the same issue, consolidate into one recommendation.
+4. **Tier** the remaining (not-yet-implemented) items by importance.
+5. Output the action plan in the exact format below.
+
+## Output Format
+
+```markdown
+# NightyTidy Action Plan
+
+> Generated from a {N}-step improvement run. Items below have been verified as **not yet implemented** in the current codebase.
+
+## Critical
+
+<!-- Security vulnerabilities, data loss risks, breaking bugs, blocking issues -->
+
+### [Short, specific title]
+- **What**: [Concrete action — reference specific files, functions, or patterns]
+- **Value**: [Why this matters — plain language, one sentence]
+- **Impact**: [Which files/modules/areas are affected]
+- **Risk**: [Low / Medium / High — risk of implementing this change, and why]
+
+## High
+
+<!-- Reliability, performance, error handling, significant code quality gaps -->
+
+(same item format)
+
+## Medium
+
+<!-- Maintainability, test coverage gaps, refactoring opportunities, minor UX issues -->
+
+(same item format)
+
+## Low
+
+<!-- Polish, style improvements, nice-to-haves, minor optimizations -->
+
+(same item format)
+
+## Summary
+
+[One sentence on overall codebase health. One sentence on the single highest-value next action.]
+```
+
+## Rules
+
+- Do NOT include anything already implemented in the codebase — verify by reading files.
+- Do NOT include vague advice like "add more tests" — be specific about WHAT to test and WHERE.
+- Each recommendation MUST reference specific files, functions, or code patterns.
+- Deduplicate ruthlessly — one item per distinct issue, even if multiple steps found it.
+- Maximum **5 items per tier** (20 items total). Prioritize ruthlessly.
+- If a tier has zero items, include the heading with a note: *No items at this priority level.*
+- Output ONLY the markdown document. No preamble, no commentary, no code fences wrapping the whole document.

package/src/prompts/specials/doc-update.md

@@ -0,0 +1 @@
+Please update any and all documentation (if necessary) so future AIs know about these changes (only if it will be value-add information to them) and do a git commit/merge.

package/src/prompts/specials/report.md

@@ -0,0 +1,95 @@
+You are generating the final run report for a NightyTidy codebase improvement run. You will be given:
+
+1. Pre-built markdown sections (summary table, step results, failed steps, undo instructions) — include these VERBATIM
+2. Step outputs from the improvement run — use these to generate the action plan section
+3. The report filename to write to
+
+Your job is to produce a single markdown file that combines a human-friendly narration with the pre-built sections and an action plan.
+
+## Part 1: Narration
+
+Review the full git log and diffs for this run (all commits on this branch). Write a plain-English summary that:
+
+1. Uses first person ("I") as if you personally worked on the codebase overnight
+2. Uses zero jargon — explain everything in terms a non-technical person would understand
+3. References SPECIFIC numbers from the actual changes (e.g., "I added 47 tests" not "I improved test coverage"; "I removed 1,200 lines of code that weren't being used" not "I cleaned up dead code")
+4. Groups related changes into short, friendly paragraphs — don't use bullet points or headers
+5. Leads with the most impressive or valuable changes first
+6. Keeps the tone warm and slightly proud of the work done — like a helpful colleague leaving a note about what they accomplished overnight
+7. Ends with a brief honest note about anything that didn't go as planned (steps that failed or were skipped), framed constructively
+8. Is no longer than 400 words — concise and scannable
+
+DO NOT use any of these words: refactor, lint, dependency, CI/CD, middleware, endpoint, schema, migration, module, pipeline, coverage metrics, regression, assertion, deprecation.
+
+Instead of technical terms, describe what the change DOES for the person: "I made sure your login page can't be tricked into running malicious code" instead of "I fixed an XSS vulnerability in the auth middleware."
+
+## Part 2: Action Plan
+
+Review the step outputs provided below to extract actionable recommendations that still need to be done.
+
+1. Review each step's output to extract actionable recommendations, suggestions, and identified issues.
+2. **Check the current codebase** — read the relevant files to determine which recommendations have ALREADY been implemented by previous steps in this run.
+3. **Deduplicate** — if multiple steps flagged the same issue, consolidate into one recommendation.
+4. **Tier** the remaining (not-yet-implemented) items by importance.
+
+Structure the action plan as:
+
+```
+## NightyTidy Action Plan
+
+> Generated from a {N}-step improvement run. Items below have been verified as **not yet implemented** in the current codebase.
+
+### Critical
+<!-- Security vulnerabilities, data loss risks, breaking bugs, blocking issues -->
+(items or "No items at this priority level.")
+
+### High
+<!-- Reliability, performance, error handling, significant code quality gaps -->
+(items)
+
+### Medium
+<!-- Maintainability, test coverage gaps, refactoring opportunities, minor UX issues -->
+(items)
+
+### Low
+<!-- Polish, style improvements, nice-to-haves, minor optimizations -->
+(items)
+
+### Summary
+[One sentence on overall codebase health. One sentence on the single highest-value next action.]
+```
+
+Each item uses this format:
+- **[Short, specific title]**: [Concrete action — reference specific files, functions, or patterns]. Value: [Why this matters]. Impact: [Which areas affected]. Risk: [Low/Medium/High].
+
+Rules:
+- Do NOT include anything already implemented — verify by reading files
+- Be specific — reference files, functions, patterns. No vague advice like "add more tests"
+- Maximum 5 items per tier (20 total)
+- Deduplicate ruthlessly
+
+## Part 3: Write the Report File
+
+Write the complete report to the file specified below. Use this exact structure:
+
+```
+# NightyTidy Report — {date}
+
+{your narration from Part 1}
+
+---
+
+{VERBATIM summary section}
+{VERBATIM step results table}
+{VERBATIM failed steps section, if present}
+
+{your action plan from Part 2}
+
+{VERBATIM undo section}
+```
+
+Rules:
+1. The pre-built sections below are wrapped in VERBATIM markers. Copy them EXACTLY as-is into the output file. Do not reformat, reword, or restructure them.
+2. Write the complete report to the exact filename specified.
+3. Commit the file with message: "NightyTidy: Add run report"
+4. Do NOT start the narration with any preamble ("I understand", "Sure", "Here is", etc.). Begin with the first word of your actual summary.

package/src/prompts/steps/01-documentation.md

@@ -0,0 +1,173 @@
+You are running an overnight documentation generation pass. Deeply understand this codebase and produce a three-tier documentation system optimized for AI coding agents, plus human-facing reference docs. Work on branch `documentation-[date]`.
+
+## The Three-Tier System
+
+AI agents pay a token cost for every line loaded into context — whether relevant or not. A 1,000-line guide burns ~31K tokens (~15% of 200K window) on every conversation. The fix: tiered loading.
+
+- **Tier 1 (Always Loaded):** Rules/conventions preventing mistakes on ANY task. Compact — target 5-7% of context.
+- **Tier 2 (On-Demand):** Per-topic implementation details. Loaded only when relevant. ~1-2% per task.
+- **Tier 3 (Deep Reference):** Human-facing docs, ADRs, API reference. Never auto-loaded. Zero token cost.
+
+| Tier | Lines | Tokens | % of 200K |
+|------|-------|--------|-----------|
+| Always (Tier 1) | 300-400 | 10-13K | 5-7% |
+| Per-task (Tier 2, 1-2 files) | 60-120 | 2-4K | 1-2% |
+| **Typical total** | **360-520** | **12-17K** | **6-9%** |
+
+Primary deliverable: Tier 1 + Tier 2. Tier 3 is secondary.
+
+---
+
+## Phases
+
+### Phase 0: Check Existing Standards
+
+Look for CLAUDE.md, .cursorrules, CONTRIBUTING.md, or similar. **If conflicts with three-tier system → STOP and ask user** with: what you found, what conflicts, 2-3 options with tradeoffs. No conflicts → proceed.
+
+### Phase 1: Codebase Discovery
+
+Read and map everything. No files produced — only understanding.
+
+**Map:** App identity, tech stack, audience. Directory responsibilities. Request/data flow (entry → routing → middleware → handlers → data → response). External deps. Module dependency graph. Architectural patterns.
+
+**Conventions:** Naming (files, vars, functions, components, DB). Imports, error handling, testing, state management. Lint/format configs. Build/test/deploy commands. Types as self-documentation.
+
+**Pitfalls:** Non-obvious side effects, library workarounds, magic values, complex regex, unexplained constants, non-obvious business logic.
+
+**Cluster** learnings into topic areas → these become Tier 2 files.
+
+### Phase 2: CLAUDE.md (Tier 1)
+
+Create `CLAUDE.md` at project root. **Target: 250-350 lines. Hard constraint.**
+
+**Inclusion test:** *"If I removed this, would the AI write incorrect code on an unrelated task?"* No → Tier 2.
+
+**Required sections:**
+- **Project Identity** — One paragraph: what, who, why
+- **Workflow Rules** — Non-negotiable process (deploy, test, etc.)
+- **Tech Stack** — Table: technology | version | purpose
+- **Project Structure** — Condensed tree, ~30 lines max, top-level + key second-level
+- **Architectural Rules** — Do/don't imperatives, not explanations
+- **Data Model Overview** — Collection/table names + relationships, not field-level
+- **Auth Model** (if applicable) — Roles + high-level flow
+- **Environment Variables** — What's needed to run
+- **Build/Deploy Commands** — Copy-paste ready
+- **Coding Conventions** — Only those consistently followed in code
+- **Design System Rules** (if applicable) — Only if affecting every UI task; otherwise Tier 2
+- **Documentation Hierarchy** — Table telling AI where knowledge lives:
+```markdown
+## Documentation Hierarchy
+
+| Layer | Loaded | What goes here |
+|-------|--------|---------------|
+| **CLAUDE.md** | Every conversation | Rules preventing mistakes on ANY task |
+| **MEMORY.md** | Every conversation | Cross-cutting patterns/pitfalls |
+| **Sub-memory** (.claude/memory/) | On demand | Feature-specific deep dives |
+| **Inline comments** | When code is read | Non-obvious "why" explanations |
+
+Rule: Prevents mistakes on unrelated tasks → CLAUDE.md. Spans features → MEMORY.md. One feature only → sub-memory. Single line → inline comment.
+```
+
+**Does NOT belong in CLAUDE.md:** Feature implementation details, API response shapes, field-level schemas, testing patterns, debugging notes, security findings, historical context. All → Tier 2/3.
+
+**Format:** Terse, imperative. Tables and bullets, not paragraphs.
+
+### Phase 3: Tier 2 Memory Files
+
+Create files at `.claude/memory/`.
+
+**Rules:** One topic per file, 40-80 lines. Terse reference format. Don't repeat CLAUDE.md. Name by topic (`testing.md`) not area (`backend-stuff.md`). Assume reader has CLAUDE.md loaded.
+
+**Each file covers:** Patterns/conventions, config details, correct-pattern snippets, common mistakes, external API quirks.
+
+**Good** — tells you what to do:
+```markdown
+## Firestore Mock Routing
+Callables using `loadPromptForPhase()` + `recordUsage()` need collection routing:
+- `"prompts"` → return `{ doc: vi.fn(() => ({ get: async () => ({ exists: false }) })) }`
+- `"_rateLimits"` → return safe no-op mock
+```
+
+**Bad** — teaches background knowledge (that's Tier 3):
+```markdown
+## About Firestore Mock Routing
+When writing tests for callable functions, you need to be aware that some callables
+access multiple Firestore collections...
+```
+
+**Suggested files** (create only what's relevant):
+
+| File | Covers |
+|------|--------|
+| testing.md | Framework config, mocks, pitfalls |
+| data-model.md | Field schemas, indexes, storage paths, migrations |
+| api-providers.md | External endpoints, auth, rate limits, quirks |
+| pitfalls-frontend.md | Framework gotchas, state traps, build issues |
+| pitfalls-backend.md | Server gotchas, auth helpers, error patterns |
+| feature-inventory.md | Features, shared components, reusable systems |
+| security.md | Auth details, vulnerabilities, audit findings |
+| deployment.md | Deploy process, env configs, infrastructure |
+
+Split/merge by project shape. **Target 8-15 files.** <5 = too broad. >20 = too granular.
+
+### Phase 4: MEMORY.md (Tier 1 — Index)
+
+Create `.claude/memory/MEMORY.md`. **Target: 30-60 lines.** Index and state tracker only.
+```markdown
+# Project Memory — Index
+[One-line description]. See CLAUDE.md for rules.
+
+## Current State
+- [Key metrics: test count, endpoints, deploy URL, etc.]
+- [Recent major changes from git]
+
+## Topic Files
+| File | When to load |
+|------|-------------|
+| testing.md | Writing or fixing tests |
+| data-model.md | Database schema or queries |
+```
+
+### Phase 5: Version Control
+
+`.gitignore`:
+
+## Chat Output Requirement
+
+In addition to writing the full report file, you MUST print a summary directly in the conversation when you finish. Do not make the user open the report to get the highlights. The chat summary should include:
+
+### 1. Status Line
+One sentence: what you did, how long it took, and whether all tests still pass.
+
+### 2. Key Findings
+The most important things discovered — bugs, risks, wins, or surprises. Each bullet should be specific and actionable, not vague. Lead with severity or impact.
+
+**Good:** "CRITICAL: No backup configuration found for the primary Postgres database — total data loss risk."
+**Bad:** "Found some issues with backups."
+
+### 3. Changes Made (if applicable)
+Bullet list of what was actually modified, added, or removed. Skip this section for read-only analysis runs.
+
+### 4. Recommendations
+
+If there are legitimately beneficial recommendations worth pursuing right now, present them in a table. Do **not** force recommendations — if the audit surfaced no actionable improvements, simply state that no recommendations are warranted at this time and move on.
+
+When recommendations exist, use this table format:
+
+| # | Recommendation | Impact | Risk if Ignored | Worth Doing? | Details |
+|---|---|---|---|---|---|
+| *Sequential number* | *Short description (≤10 words)* | *What improves if addressed* | *Low / Medium / High / Critical* | *Yes / Probably / Only if time allows* | *1–3 sentences explaining the reasoning, context, or implementation guidance* |
+
+Order rows by risk descending (Critical → High → Medium → Low). Be honest in the "Worth Doing?" column — not everything flagged is worth the engineering time. If a recommendation is marginal, say so.
+
+### 5. Report Location
+State the full path to the detailed report file for deeper review.
+
+Create `audit-reports/` in project root if needed. Save as `audit-reports/01_DOCUMENTATION_COVERAGE_REPORT_[run-number]_[date]_[time in user's local time].md`, incrementing run number based on existing reports.
+
+---
+
+**Formatting rules for chat output:**
+- Use markdown headers, bold for severity labels, and bullet points for scannability.
+- Do not duplicate the full report contents — just the highlights and recommendations.
+- If you made zero findings in a phase, say so in one line rather than omitting it silently.