@ameshkin/ticket-mate 0.1.20

package/config/_design-specs.json

@@ -0,0 +1,39 @@
+{
+  "nav": {
+    "background": "#050816",
+    "backgroundElevated": "#080B1F",
+    "border": "#1C2340",
+    "text": "#E5E9FF",
+    "textMuted": "#9AA4D0",
+    "accentPrimary": "#5B5FFF",
+    "accentSecondary": "#BE79FF",
+    "accentDanger": "#FF4F7B",
+    "hoverBackground": "#101735",
+    "activeIndicator": "#5B5FFF",
+    "divider": "rgba(255,255,255,0.06)"
+  },
+  "logo": {
+    "wordmark": {
+      "fontFamily": "Inter, system-ui, sans-serif",
+      "fontWeight": 700,
+      "fontSize": "1.5rem",
+      "letterSpacing": "0.05em"
+    },
+    "emblem": {
+      "size": "32px",
+      "strokeWidth": "2px",
+      "rotation": "3deg"
+    }
+  },
+  "animations": {
+    "duration": {
+      "fast": "120ms",
+      "normal": "160ms",
+      "slow": "300ms"
+    },
+    "easing": {
+      "easeOut": "cubic-bezier(0.4, 0, 0.2, 1)"
+    }
+  }
+}
+

package/config/bugs-demo.json

@@ -0,0 +1,186 @@
+{
+  "bugs": [
+    {
+      "id": "BUG-0001",
+      "title": "BugTracker forgot which framework it lived in",
+      "category": "existing-bug",
+      "status": "fixed",
+      "severity": "high",
+      "area": "frontend",
+      "component": "BugTracker",
+      "filePath": "src/components/bugtracker/BugTracker.tsx",
+      "summary": "BugTracker had TypeScript errors, incorrect MUI imports, and was acting like this was a Next.js app when it very much was not.",
+      "rootCause": "Component was created with Next.js assumptions in a Vite React app. Identity crisis ensued.",
+      "fixSummary": "Corrected imports, added proper typings, removed Next.js-only assumptions, created a dedicated bugs service, and ensured bugs.json is served correctly.",
+      "testStatus": "missing",
+      "createdAt": "2025-01-28T00:00:00.000Z",
+      "updatedAt": "2025-01-28T00:00:00.000Z"
+    },
+    {
+      "id": "BUG-0002",
+      "title": "BugTracker tried to fetch an API route that never existed",
+      "category": "existing-bug",
+      "status": "fixed",
+      "severity": "medium",
+      "area": "frontend",
+      "component": "BugTracker",
+      "filePath": "src/components/bugtracker/BugTracker.tsx",
+      "summary": "BugTracker attempted to fetch /api/dev/bugs in a Vite app, where API routes go to die.",
+      "rootCause": "Designed for Next.js API routes in a non-Next.js environment.",
+      "fixSummary": "Implemented a proper service layer and switched to fetching a public bugs.json file copied during build.",
+      "testStatus": "missing",
+      "createdAt": "2025-01-28T00:00:00.000Z",
+      "updatedAt": "2025-01-28T00:00:00.000Z"
+    },
+    {
+      "id": "BUG-0003",
+      "title": "BugTracker has no tests (confidence-based development)",
+      "category": "missing-test",
+      "status": "fixed",
+      "severity": "medium",
+      "area": "tests",
+      "component": "BugTracker",
+      "filePath": "src/components/bugtracker/__tests__/BugTracker.test.tsx",
+      "summary": "BugTracker shipped without tests, relying entirely on vibes and hope.",
+      "rootCause": "Initial implementation prioritized features over verification.",
+      "fixSummary": "Added tests covering loading state, bug rendering, Jira ticket creation, and error handling.",
+      "testStatus": "passing",
+      "createdAt": "2025-01-28T00:00:00.000Z"
+    },
+    {
+      "id": "BUG-0004",
+      "title": "Several components also believed testing was optional",
+      "category": "missing-test",
+      "status": "fixed",
+      "severity": "medium",
+      "area": "tests",
+      "component": "Multiple",
+      "filePath": "src/components/",
+      "summary": "Multiple UI components existed without tests, quietly hoping no one would notice.",
+      "rootCause": "Test scaffolding existed but coverage lagged behind component creation.",
+      "fixSummary": "Added baseline render and interaction tests for all listed components.",
+      "testStatus": "passing",
+      "createdAt": "2025-01-28T00:00:00.000Z"
+    },
+    {
+      "id": "BUG-0005",
+      "title": "Services layer also skipped leg day (and tests)",
+      "category": "missing-test",
+      "status": "fixed",
+      "severity": "medium",
+      "area": "tests",
+      "component": "Services",
+      "filePath": "src/services/__tests__/",
+      "summary": "Several core services had no test coverage, which is exciting but dangerous.",
+      "rootCause": "Services were implemented faster than test coverage could keep up.",
+      "fixSummary": "Added unit tests for all listed services, including failure and edge cases.",
+      "testStatus": "passing",
+      "createdAt": "2025-01-28T00:00:00.000Z"
+    },
+    {
+      "id": "BUG-0006",
+      "title": "useProjects hook trusted the network too much",
+      "category": "missing-test",
+      "status": "fixed",
+      "severity": "medium",
+      "area": "tests",
+      "component": "useProjects",
+      "filePath": "src/hooks/__tests__/useProjects.test.tsx",
+      "summary": "useProjects had no tests and assumed the network would always behave.",
+      "rootCause": "Hook was implemented without test coverage.",
+      "fixSummary": "Added tests for loading, success, error, and cache invalidation scenarios.",
+      "testStatus": "passing",
+      "createdAt": "2025-01-28T00:00:00.000Z"
+    },
+    {
+      "id": "BUG-0007",
+      "title": "Placeholder pages multiplied quietly",
+      "category": "potential-bug",
+      "status": "fixed",
+      "severity": "high",
+      "area": "frontend",
+      "component": "Pages",
+      "filePath": "src/pages/",
+      "summary": "Multiple pages were placeholders, confidently pretending to be finished.",
+      "rootCause": "Pages were scaffolded early and deferred for later implementation.",
+      "fixSummary": "Each placeholder page was either fully implemented or clearly marked as preview with proper empty states.",
+      "testStatus": "passing",
+      "createdAt": "2025-01-28T00:00:00.000Z"
+    },
+    {
+      "id": "BUG-0009",
+      "title": "No integration tests existed (the system just trusted itself)",
+      "category": "missing-test",
+      "status": "fixed",
+      "severity": "medium",
+      "area": "tests",
+      "component": "Integration",
+      "filePath": "src/__tests__/integration/",
+      "summary": "There were no integration tests verifying that anything worked together.",
+      "rootCause": "Integration testing was planned but not executed.",
+      "fixSummary": "Added integration tests covering hooks + services, pages + hooks, and Jira integration flows.",
+      "testStatus": "passing",
+      "createdAt": "2025-01-28T00:00:00.000Z"
+    },
+    {
+      "id": "BUG-0010",
+      "title": "E2E tests asserted that true is true",
+      "category": "missing-test",
+      "status": "fixed",
+      "severity": "low",
+      "area": "tests",
+      "component": "E2E",
+      "filePath": "e2e/",
+      "summary": "End-to-end tests only asserted expect(true).toBe(true), which was technically correct.",
+      "rootCause": "E2E scaffolding was created without real scenarios.",
+      "fixSummary": "Implemented real E2E flows covering login, board navigation, bug creation, and sync.",
+      "testStatus": "passing",
+      "createdAt": "2025-01-28T00:00:00.000Z"
+    },
+    {
+      "id": "BUG-0018",
+      "title": "Test imports pointed somewhere that did not exist",
+      "category": "existing-bug",
+      "status": "fixed",
+      "severity": "medium",
+      "area": "tests",
+      "component": "Tests",
+      "filePath": "src/components/**/__tests__/",
+      "summary": "Test files imported utilities from paths that were optimistic at best.",
+      "rootCause": "Incorrect relative paths after refactoring.",
+      "fixSummary": "Corrected all test utility import paths and added path aliases where appropriate.",
+      "testStatus": "passing",
+      "createdAt": "2025-01-28T00:00:00.000Z"
+    },
+    {
+      "id": "BUG-0019",
+      "title": "Vitest globals assumed everyone just knew",
+      "category": "existing-bug",
+      "status": "fixed",
+      "severity": "medium",
+      "area": "tests",
+      "component": "Tests",
+      "filePath": "src/pages/__tests__/",
+      "summary": "Tests used vi without importing it, assuming TypeScript would just understand.",
+      "rootCause": "Vitest globals were enabled at runtime but not recognized by TypeScript.",
+      "fixSummary": "Explicitly imported vi where needed and updated tsconfig types to include vitest.",
+      "testStatus": "passing",
+      "createdAt": "2025-01-28T00:00:00.000Z"
+    },
+    {
+      "id": "BUG-0020",
+      "title": ".env.example did not exist (classic)",
+      "category": "potential-bug",
+      "status": "fixed",
+      "severity": "low",
+      "area": "ops",
+      "component": "Configuration",
+      "filePath": ".env.example",
+      "summary": "Required environment variables were undocumented, leading to surprise failures.",
+      "rootCause": "Environment documentation was deferred.",
+      "fixSummary": "Added .env.example with all required and optional configuration variables.",
+      "testStatus": "passing",
+      "createdAt": "2025-01-28T00:00:00.000Z"
+    }
+  ]
+}

package/config/design-specs.ts

@@ -0,0 +1,39 @@
+export const designSpecs = {
+  nav: {
+    background: "#050816",
+    backgroundElevated: "#080B1F",
+    border: "#1C2340",
+    text: "#E5E9FF",
+    textMuted: "#9AA4D0",
+    accentPrimary: "#5B5FFF",
+    accentSecondary: "#BE79FF",
+    accentDanger: "#FF4F7B",
+    hoverBackground: "#101735",
+    activeIndicator: "#5B5FFF",
+    divider: "rgba(255,255,255,0.06)",
+  },
+  logo: {
+    wordmark: {
+      fontFamily: "Inter, system-ui, sans-serif",
+      fontWeight: 700,
+      fontSize: "1.5rem",
+      letterSpacing: "0.05em",
+    },
+    emblem: {
+      size: "32px",
+      strokeWidth: "2px",
+      rotation: "3deg",
+    },
+  },
+  animations: {
+    duration: {
+      fast: "120ms",
+      normal: "160ms",
+      slow: "300ms",
+    },
+    easing: {
+      easeOut: "cubic-bezier(0.4, 0, 0.2, 1)",
+    },
+  },
+} as const;
+

package/config/envSpec.ts

@@ -0,0 +1,120 @@
+/**
+ * Canonical Environment Variable Specification for ticket-mate
+ * 
+ * This file defines all environment variables used by ticket-mate.
+ * It's used for documentation, validation, and tooling.
+ */
+
+export const envSpec = {
+  required: [
+    "JIRA_BASE_URL",
+    "JIRA_EMAIL",
+    "JIRA_API_KEY",
+  ],
+  
+  optional: [
+    // Authentication & OAuth
+    "JIRA_API_TOKEN",              // DEPRECATED: Use JIRA_API_KEY instead (backward compatibility only, will be removed)
+    "ATLASSIAN_CLIENT_ID",              // OAuth client ID (for OAuth flow)
+    "ATLASSIAN_CLIENT_SECRET",          // OAuth client secret
+    "JIRA_REDIRECT_URI",           // OAuth redirect URI (defaults to localhost:4000)
+    "JIRA_SCOPES",                 // OAuth scopes (defaults to read:jira-work write:jira-work read:jira-user offline_access)
+    
+    // Project Configuration
+    "JIRA_PROJECT_KEY",            // Default project key (e.g., NOVA)
+    "JIRA_SUPPORT_PROJECT_KEY",    // Legacy alias for JIRA_PROJECT_KEY
+    "JIRA_EPIC_KEY",               // Default epic key
+    "JIRA_SUPPORT_EPIC_KEY",       // Legacy alias for JIRA_EPIC_KEY
+    "JIRA_LABEL",                  // Default label
+    "JIRA_SUPPORT_LABEL",          // Legacy alias for JIRA_LABEL
+    
+    // User Configuration
+    "JIRA_DEFAULT_REPORTER",       // Default reporter email/accountId for ticket creation
+    "JIRA_AUTOMATION_EMAIL",       // Automation user email (e.g., cursor.automation@domain.com)
+    "JIRA_AUTO_WORK_ASSIGNEE",     // Default assignee for automation (defaults to "cursor.automation")
+    "JIRA_CURSOR_DEV_ACCOUNT_ID",  // Cursor dev account ID
+    "JIRA_LEAD_ACCOUNT_ID",        // Project lead account ID
+    
+    // Cloud API Configuration
+    "JIRA_CLOUD_ID",               // Atlassian cloud ID for scoped API tokens
+    "JIRA_USE_CLOUD_API",          // Use cloud API URL (set to "true")
+    
+    // Webhooks & Integration
+    "JIRA_WEBHOOK_SECRET",         // Secret for validating Jira webhooks
+    "NEXT_PUBLIC_APP_URL",         // Public app URL (for webhooks, defaults to localhost:4000)
+    "NEXT_PUBLIC_WEBHOOK_URL",     // Public webhook URL
+    "NEXT_PUBLIC_NGROK_URL",       // Ngrok URL for local development
+    "NGROK_DEV_DOMAIN",            // Ngrok dev domain
+    
+    // Custom Fields
+    "JIRA_EPIC_LINK_FIELD_ID",     // Epic link custom field ID (defaults to customfield_10014)
+    "JIRA_ACCEPTANCE_CRITERIA_FIELD_ID", // Acceptance criteria custom field ID
+    
+    // Status Transitions
+    "JIRA_TRANSITION_TODO",        // "To Do" transition name (defaults to "To Do")
+    "JIRA_TRANSITION_IN_PROGRESS", // "In Progress" transition name (defaults to "In Progress")
+    "JIRA_TRANSITION_IN_REVIEW",   // "In Review" transition name (defaults to "In Review")
+    "JIRA_TRANSITION_DONE",        // "Done" transition name (defaults to "Done")
+    
+    // AI Configuration
+    "JIRA_AI_READY_LABEL",         // Label for AI-ready tickets (defaults to "AI-READY")
+    "JIRA_AI_READY_STATUS_CATEGORY", // Status category for AI-ready (defaults to "In Progress")
+    "JIRA_ISSUE_TYPE_MAPPING",     // CSV mapping of issue types
+    
+    // Frontend Configuration
+    "NEXT_PUBLIC_JIRA_BASE_URL",   // Public Jira base URL (exposed to browser)
+    "NEXT_PUBLIC_JIRA_MATE_API_KEY", // Public API key for frontend API calls
+    "NEXT_PUBLIC_GITHUB_REPO_URL", // GitHub repository URL
+    "NEXT_PUBLIC_GOOGLE_MAPS_API_KEY", // Google Maps API key
+    
+    // Development & Debugging
+    "DEBUG",                       // Enable debug mode (set to "true")
+    "JIRA_MATE_DEBUG",             // Enable ticket-mate debug mode (set to "true")
+    "NODE_ENV",                    // Node environment (development, production, test)
+    "VERCEL_ENV",                  // Vercel environment
+    "VERCEL_URL",                  // Vercel deployment URL
+  ],
+} as const;
+
+export type EnvVarName = typeof envSpec.required[number] | typeof envSpec.optional[number];
+
+/**
+ * Get description for an environment variable
+ */
+export function getEnvVarDescription(key: string): string {
+  const descriptions: Record<string, string> = {
+    // Required
+    JIRA_BASE_URL: "Base URL for your Jira Cloud instance (e.g., https://pamcms.atlassian.net)",
+    JIRA_EMAIL: "Atlassian account email used for API calls",
+    JIRA_API_KEY: "Jira personal access token (192 characters). Generate at https://id.atlassian.com/manage-profile/security/api-tokens",
+    
+    // Optional - Auth (deprecated)
+    JIRA_API_TOKEN: "DEPRECATED: Use JIRA_API_KEY instead (backward compatibility only)",
+    ATLASSIAN_CLIENT_ID: "OAuth client ID from Atlassian app",
+    ATLASSIAN_CLIENT_SECRET: "OAuth client secret from Atlassian app",
+    JIRA_REDIRECT_URI: "OAuth redirect URI (defaults to http://localhost:4000/api/auth/jira/callback)",
+    JIRA_SCOPES: "OAuth scopes (defaults to read:jira-work write:jira-work read:jira-user offline_access)",
+    
+    // Optional - Project
+    JIRA_PROJECT_KEY: "Default project key (e.g., NOVA)",
+    JIRA_DEFAULT_REPORTER: "Default reporter email/accountId for ticket creation",
+    JIRA_AUTOMATION_EMAIL: "Automation user email (e.g., cursor.automation@domain.com)",
+    JIRA_AUTO_WORK_ASSIGNEE: "Default assignee for automation (defaults to cursor.automation)",
+    
+    // Optional - Cloud API (PAT mode only)
+    JIRA_CLOUD_ID: "Optional: Atlassian cloud ID (for PAT mode Cloud API calls only; OAuth mode stores this in DB, not env)",
+    JIRA_USE_CLOUD_API: "Optional: Use cloud API URL (set to 'true' for PAT mode scoped tokens)",
+    JIRA_AUTH_MODE: "Optional: Explicit auth mode ('PAT' or 'OAUTH', defaults to PAT if not set)",
+    
+    // Optional - Webhooks
+    JIRA_WEBHOOK_SECRET: "Secret for validating Jira webhooks",
+    NEXT_PUBLIC_APP_URL: "Public app URL (for webhooks, defaults to http://localhost:4000)",
+    
+    // Optional - Frontend
+    NEXT_PUBLIC_JIRA_BASE_URL: "Public Jira base URL (exposed to browser)",
+    NEXT_PUBLIC_JIRA_MATE_API_KEY: "Public API key for frontend API calls",
+  };
+  
+  return descriptions[key] || "See documentation for details";
+}
+

package/config/nav.admin.ts

@@ -0,0 +1,165 @@
+export const adminNavConfig = [
+  {
+    section: "Overview",
+    items: [
+      {
+        id: "analytics",
+        label: "Analytics",
+        icon: "chart",
+        href: "/admin/dashboard/analytics",
+      },
+      {
+        id: "metrics",
+        label: "Metrics",
+        icon: "metrics",
+        href: "/metrics",
+      },
+    ],
+  },
+  {
+    section: "Work",
+    items: [
+      {
+        id: "sites-jira",
+        label: "Jira Dash",
+        icon: "projects",
+        href: "/admin/jira",
+      },
+      {
+        id: "project-tracking",
+        label: "Site",
+        icon: "tracking",
+        href: "/admin/sites",
+      },
+      {
+        id: "issues",
+        label: "Issues",
+        icon: "issues",
+        href: "/issues",
+      },
+      // Deprecated: Sync page is still available at /sync but hidden from navigation.
+      // It is superseded by orchestrator-driven sync flows.
+      // {
+      //   id: "sync",
+      //   label: "Sync",
+      //   icon: "sync",
+      //   href: "/sync",
+      // },
+      {
+        id: "progress",
+        label: "Progress",
+        icon: "progress",
+        href: "/progress",
+      },
+      {
+        id: "jira-cloud",
+        label: "Open Jira Cloud",
+        icon: "projects",
+        href: "https://pamcms.atlassian.net",
+      },
+    ],
+  },
+  {
+    section: "Automation",
+    items: [
+      {
+        id: "pipelines",
+        label: "Pipelines",
+        icon: "pipeline",
+        children: [
+          {
+            id: "nightly",
+            label: "Nightly Builds",
+            href: "/pipelines/nightly",
+          },
+          {
+            id: "webhooks",
+            label: "Webhooks",
+            href: "/webhooks",
+          },
+          {
+            id: "ci",
+            label: "CI Integration",
+            href: "/ci",
+          },
+        ],
+      },
+      {
+        id: "batch",
+        label: "Batch Operations",
+        icon: "batch",
+        href: "/batch",
+      },
+      {
+        id: "execute",
+        label: "AI Execution",
+        icon: "execute",
+        href: "/execute",
+      },
+    ],
+  },
+  {
+    section: "Content",
+    items: [
+      {
+        id: "prompts",
+        label: "Prompts",
+        icon: "prompts",
+        href: "/prompts",
+      },
+      {
+        id: "pr",
+        label: "PR Builder",
+        icon: "pr",
+        href: "/pr",
+      },
+      {
+        id: "acceptance",
+        label: "Acceptance Criteria",
+        icon: "acceptance",
+        href: "/acceptance",
+      },
+    ],
+  },
+  {
+    section: "Security",
+    items: [
+      {
+        id: "api-keys",
+        label: "API Keys",
+        icon: "key",
+        href: "/security/api-keys",
+      },
+      {
+        id: "audit",
+        label: "Audit Logs",
+        icon: "audit",
+        href: "/security/audit",
+      },
+    ],
+  },
+  {
+    section: "Settings",
+    items: [
+      {
+        id: "config",
+        label: "Configuration",
+        icon: "config",
+        href: "/config",
+      },
+      {
+        id: "git",
+        label: "Git Validation",
+        icon: "git",
+        href: "/git",
+      },
+      {
+        id: "task-folders",
+        label: "Task Folders",
+        icon: "folder",
+        href: "/task-folders",
+      },
+    ],
+  },
+] as const;
+

package/config/nav.main.json

@@ -0,0 +1,90 @@
+[
+  {
+    "id": "platform",
+    "label": "Platform",
+    "type": "mega",
+    "columns": [
+      {
+        "title": "Orchestrator Core",
+        "items": [
+          {
+            "label": "Dashboard",
+            "href": "/dashboard",
+            "icon": "dashboard",
+            "description": "Overview and analytics"
+          },
+          {
+            "label": "Sites",
+            "href": "/sites",
+            "icon": "sites",
+            "description": "Manage all sites"
+          },
+          {
+            "label": "Jira Integration",
+            "href": "/jira",
+            "icon": "jira",
+            "description": "Jira ticket management"
+          }
+        ]
+      },
+      {
+        "title": "Automation",
+        "items": [
+          {
+            "label": "Pipelines",
+            "href": "/pipelines",
+            "description": "CI/CD workflows"
+          },
+          {
+            "label": "Nightly Builds",
+            "href": "/nightly-builds",
+            "description": "Automated builds"
+          },
+          {
+            "label": "Webhooks",
+            "href": "/webhooks",
+            "description": "Event integrations"
+          }
+        ]
+      },
+      {
+        "title": "AI & Agents",
+        "items": [
+          {
+            "label": "AI Execution",
+            "href": "/execute",
+            "description": "AI-powered workflows"
+          },
+          {
+            "label": "Prompts",
+            "href": "/prompts",
+            "description": "Prompt management"
+          }
+        ]
+      }
+    ]
+  },
+  {
+    "id": "resources",
+    "label": "Resources",
+    "type": "dropdown",
+    "items": [
+      {
+        "label": "Blog",
+        "href": "/blog"
+      },
+      {
+        "label": "Community",
+        "href": "/community"
+      },
+      {
+        "label": "Support",
+        "href": "/support"
+      },
+      {
+        "label": "Status",
+        "href": "/status"
+      }
+    ]
+  }
+]