hale-commenting-system 2.2.6 → 2.2.9

package/README.md

@@ -1,109 +1,134 @@
-# Patternfly Seed
+# Hale Commenting System
 
-Patternfly Seed is an open source build scaffolding utility for web apps. The primary purpose of this project is to give developers a jump start when creating new projects that will use patternfly. A secondary purpose of this project is to serve as a reference for how to configure various aspects of an application that uses patternfly, webpack, react, typescript, etc.
+A commenting system for PatternFly React applications that allows designers and developers to add comments directly on design pages, sync with GitHub Issues, and link Jira tickets.
 
-Out of the box you'll get an app layout with chrome (header/sidebar), routing, build pipeline, test suite, and some code quality tools. Basically, all the essentials.
+## Features
 
-<img width="1058" alt="Out of box dashboard view of patternfly seed" src="https://github.com/user-attachments/assets/0227b366-67f1-4df8-8d92-e8e95d6e08b3" />
+- 📌 **Pin-based commenting** - Click anywhere on a page to add a comment pin
+- 💬 **Thread discussions** - Organize comments into threads with replies
+- 🔄 **GitHub Integration** - Sync comments with GitHub Issues automatically
+- 🎫 **Jira Integration** - Link Jira tickets to specific pages or sections
+- 🎨 **PatternFly Design** - Built with PatternFly React components
+- 📱 **Responsive** - Works on desktop and mobile devices
+- 🚀 **Easy Integration** - Automated setup script for seamless installation
 
-## Quick-start
+## Installation
 
 ```bash
-git clone https://github.com/patternfly/patternfly-react-seed
-cd patternfly-react-seed
-npm install && npm run start:dev
+npm install hale-commenting-system
 ```
-## Development scripts
-```sh
-# Install development/build dependencies
-npm install
 
-# Start the development server
-npm run start:dev
+## Quick Start
 
-# Run a production build (outputs to "dist" dir)
-npm run build
+1. **Install the package:**
+   ```bash
+   npm install hale-commenting-system
+   ```
 
-# Run the test suite
-npm run test
+2. **Run the integration script:**
+   ```bash
+   npx hale-commenting-system init
+   ```
 
-# Run the test suite with coverage
-npm run test:coverage
+3. **Follow the interactive setup:**
+   - The script will guide you through project setup
+   - Optionally configure GitHub OAuth integration
+   - Optionally configure Jira integration
+   - Configuration files (`.env` and `.env.server`) will be created automatically
 
-# Run the linter
-npm run lint
+4. **Start your dev server:**
+   ```bash
+   npm run start:dev
+   ```
 
-# Run the code formatter
-npm run format
+## Usage
 
-# Launch a tool to inspect the bundle size
-npm run bundle-profile:analyze
+After running the integration script, the commenting system will be available in your PatternFly React Seed application.
 
-# Start the express server (run a production build first)
-npm run start
-```
+### Adding Comments
 
-## Configurations
-* [TypeScript Config](./tsconfig.json)
-* [Webpack Config](./webpack.common.js)
-* [Jest Config](./jest.config.js)
-* [Editor Config](./.editorconfig)
+- **Click anywhere** on a page to add a comment pin
+- **View all comments** in the "Comments" menu item in the sidebar
+- **Reply to comments** to create discussion threads
+- **Navigate to pins** using the "Go to pin" button in the comments view
 
-## Raster image support
+### GitHub Integration (Optional)
 
-To use an image asset that's shipped with PatternFly core, you'll prefix the paths with "@assets". `@assets` is an alias for the PatternFly assets directory in node_modules.
+When configured, comments automatically sync with GitHub Issues:
+- Each comment thread becomes a GitHub Issue
+- Replies sync as Issue comments
+- Status changes (open/closed) sync between the app and GitHub
 
-For example:
-```js
-import imgSrc from '@assets/images/g_sizing.png';
-<img src={imgSrc} alt="Some image" />
-```
+### Jira Integration (Optional)
 
-You can use a similar technique to import assets from your local app, just prefix the paths with "@app". `@app` is an alias for the main src/app directory.
+When configured, you can:
+- Link Jira tickets to specific pages or sections
+- View ticket details in the commenting panel
+- Track design work alongside development tickets
 
-```js
-import loader from '@app/assets/images/loader.gif';
-<img src={loader} alt="Content loading" />
-```
+## Configuration
 
-## Vector image support
-Inlining SVG in the app's markup is also possible.
+The integration script creates two configuration files:
 
-```js
-import logo from '@app/assets/images/logo.svg';
-<span dangerouslySetInnerHTML={{__html: logo}} />
-```
+### `.env`
+Contains client-side configuration (safe to commit):
+- GitHub OAuth client ID
+- Jira base URL
+- Other public configuration
 
-You can also use SVG when applying background images with CSS. To do this, your SVG's must live under a `bgimages` directory (this directory name is configurable in [webpack.common.js](./webpack.common.js#L5)). This is necessary because you may need to use SVG's in several other context (inline images, fonts, icons, etc.) and so we need to be able to differentiate between these usages so the appropriate loader is invoked.
-```css
-body {
-  background: url(./assets/bgimages/img_avatar.svg);
-}
-```
+### `.env.server`
+Contains server-side secrets (should NOT be committed):
+- GitHub OAuth client secret
+- Jira API tokens
+- Other sensitive credentials
+
+**Important:** The `.env.server` file is automatically added to `.gitignore` to prevent committing secrets.
+
+See the generated files for detailed setup instructions.
+
+## Requirements
+
+- **PatternFly React Seed** project (or compatible PatternFly React application)
+- **Node.js 18+** (required for webpack middleware with native `fetch()` support)
+- **React 18+**
 
-## Adding custom CSS
-When importing CSS from a third-party package for the first time, you may encounter the error `Module parse failed: Unexpected token... You may need an appropriate loader to handle this file typ...`. You need to register the path to the stylesheet directory in [stylePaths.js](./stylePaths.js). We specify these explicitly for performance reasons to avoid webpack needing to crawl through the entire node_modules directory when parsing CSS modules.
+## What Gets Integrated
 
-## Code quality tools
-* For accessibility compliance, we use [react-axe](https://github.com/dequelabs/react-axe)
-* To keep our bundle size in check, we use [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer)
-* To keep our code formatting in check, we use [prettier](https://github.com/prettier/prettier)
-* To keep our code logic and test coverage in check, we use [jest](https://github.com/facebook/jest)
-* To ensure code styles remain consistent, we use [eslint](https://eslint.org/)
+The integration script automatically modifies your project:
 
-## Multi environment configuration
-This project uses [dotenv-webpack](https://www.npmjs.com/package/dotenv-webpack) for exposing environment variables to your code. Either export them at the system level like `export MY_ENV_VAR=http://dev.myendpoint.com && npm run start:dev` or simply drop a `.env` file in the root that contains your key-value pairs like below:
+1. **`src/app/index.tsx`** - Adds `CommentProvider` and `GitHubAuthProvider`
+2. **`src/app/routes.tsx`** - Adds "Comments" route group with "View all" route
+3. **`src/app/AppLayout/AppLayout.tsx`** - Adds `CommentPanel` and `CommentOverlay` components
+4. **`webpack.dev.js`** - Adds middleware for GitHub OAuth and Jira API proxying
+5. **`src/app/Comments/Comments.tsx`** - Creates the Comments view component
+6. **`.env` and `.env.server`** - Creates configuration files
 
-```sh
-ENV_1=http://1.myendpoint.com
-ENV_2=http://2.myendpoint.com
+## Development
+
+### Running Locally
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server
+npm run start:dev
 ```
 
+### Building for Production
+
+```bash
+# Run production build
+npm run build
+
+# Start production server
+npm run start
+```
 
-With that in place, you can use the values in your code like `console.log(process.env.ENV_1);`
+## License
 
-### GitHub OAuth / Issues env vars (local dev)
+MIT
 
-For the commenting system, see `GITHUB_OAUTH_ENV_TEMPLATE.md`.
+## Support
 
-**Important:** because webpack injects `.env` values into the browser bundle, do **not** put secrets (like OAuth client secrets) into `.env`.
+For issues, questions, or contributions, please visit the [repository](https://github.com/patternfly/patternfly-react-seed).

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "hale-commenting-system",
-  "version": "2.2.6",
-  "description": "An open source build scaffolding utility for web apps.",
+  "version": "2.2.9",
+  "description": "A commenting system for PatternFly React applications that allows designers and developers to add comments directly on design pages, sync with GitHub Issues, and link Jira tickets.",
   "repository": "https://github.com/patternfly/patternfly-react-seed.git",
-  "homepage": "https://patternfly-react-seed.surge.sh",
+  "homepage": "https://www.npmjs.com/package/hale-commenting-system",
   "license": "MIT",
   "main": "src/app/commenting-system/index.ts",
   "types": "src/app/commenting-system/index.ts",

package/scripts/integrate.js

@@ -512,6 +512,41 @@ JIRA_API_TOKEN=
   }
 }
 
+function createCommentsComponent() {
+  const cwd = process.cwd();
+  const commentsDir = path.join(cwd, 'src', 'app', 'Comments');
+  const commentsFile = path.join(commentsDir, 'Comments.tsx');
+
+  // Check if already exists
+  if (fs.existsSync(commentsFile)) {
+    return; // Already exists, skip
+  }
+
+  // Create directory if it doesn't exist
+  if (!fs.existsSync(commentsDir)) {
+    fs.mkdirSync(commentsDir, { recursive: true });
+  }
+
+  // Read the Comments component from the package and modify the import
+  // The file is in the package at src/app/Comments/Comments.tsx
+  const scriptDir = __dirname || path.dirname(require.resolve('./integrate.js'));
+  const packageCommentsFile = path.join(scriptDir, '..', 'src', 'app', 'Comments', 'Comments.tsx');
+  
+  let commentsComponentContent;
+  if (fs.existsSync(packageCommentsFile)) {
+    // Read from package and replace import path
+    commentsComponentContent = fs.readFileSync(packageCommentsFile, 'utf8')
+      .replace(/from ['"]@app\/commenting-system['"]/g, "from 'hale-commenting-system'");
+  } else {
+    // Fallback: create a minimal version (shouldn't happen if package is properly built)
+    console.log('   ⚠️  Comments component not found in package, skipping creation');
+    return;
+  }
+
+  fs.writeFileSync(commentsFile, commentsComponentContent);
+  console.log('   ✅ Created Comments component');
+}
+
 function integrateWebpackMiddleware() {
   const cwd = process.cwd();
   const webpackDevPath = path.join(cwd, 'webpack.dev.js');
@@ -759,13 +794,47 @@ function integrateWebpackMiddleware() {
 `;
 
   // Find the setupMiddlewares function and inject our code
-  const setupMiddlewaresRegex = /(setupMiddlewares\s*:\s*\([^)]+\)\s*=>\s*\{)/;
-  const match = webpackContent.match(setupMiddlewaresRegex);
+  // Try multiple patterns to match different webpack.dev.js structures
+  const setupMiddlewaresPatterns = [
+    /(setupMiddlewares\s*:\s*\([^)]+\)\s*=>\s*\{)/,  // Arrow function
+    /(setupMiddlewares\s*:\s*function\s*\([^)]+\)\s*\{)/,  // Function declaration
+    /(setupMiddlewares\s*:\s*\([^)]+\)\s*\{)/,  // Shorthand method
+  ];
+  
+  let match = null;
+  for (const pattern of setupMiddlewaresPatterns) {
+    match = webpackContent.match(pattern);
+    if (match) break;
+  }
 
   if (!match) {
-    console.log('   ⚠️  Could not find setupMiddlewares in webpack.dev.js');
-    console.log('   📋 Manual integration required. See webpack middleware documentation\n');
-    return;
+    // If setupMiddlewares doesn't exist, we need to add it to devServer config
+    // Check if devServer config exists
+    const devServerMatch = webpackContent.match(/(devServer\s*:\s*\{)/);
+    if (devServerMatch) {
+      // Add setupMiddlewares to devServer config
+      const insertIndex = devServerMatch.index + devServerMatch[0].length;
+      const before = webpackContent.substring(0, insertIndex);
+      const after = webpackContent.substring(insertIndex);
+      
+      const setupMiddlewaresCode = `
+    setupMiddlewares: (middlewares, devServer) => {
+      if (!devServer || !devServer.app) {
+        return middlewares;
+      }
+${middlewareCode}
+      return middlewares;
+    },`;
+      
+      webpackContent = before + setupMiddlewaresCode + '\n' + after;
+      fs.writeFileSync(webpackDevPath, webpackContent);
+      console.log('   ✅ Added setupMiddlewares to webpack.dev.js');
+      return;
+    } else {
+      console.log('   ⚠️  Could not find setupMiddlewares or devServer config in webpack.dev.js');
+      console.log('   📋 Manual integration required. See webpack middleware documentation\n');
+      return;
+    }
   }
 
   // Find where to inject (after express.json() setup, before return middlewares)
@@ -992,10 +1061,62 @@ function modifyRoutesTsx(filePath) {
     });
 
     if (routesArray) {
-      // Add Comments route group
+      // Check if Comments component is imported
+      let hasCommentsImport = false;
+      let commentsImportName = 'Comments';
+      
+      traverse(ast, {
+        ImportDeclaration(path) {
+          const source = path.node.source.value;
+          if (source.includes('Comments') || source.includes('@app/Comments')) {
+            hasCommentsImport = true;
+            // Get the imported name
+            path.node.specifiers.forEach(spec => {
+              if (spec.type === 'ImportSpecifier' && spec.imported.name === 'Comments') {
+                commentsImportName = spec.local.name;
+              }
+            });
+          }
+        }
+      });
+
+      // Add Comments import if missing
+      if (!hasCommentsImport) {
+        let lastImportIndex = -1;
+        for (let i = ast.program.body.length - 1; i >= 0; i--) {
+          if (ast.program.body[i].type === 'ImportDeclaration') {
+            lastImportIndex = i;
+            break;
+          }
+        }
+        const importIndex = lastImportIndex >= 0 ? lastImportIndex + 1 : 0;
+        
+        const commentsImport = types.importDeclaration(
+          [types.importSpecifier(types.identifier('Comments'), types.identifier('Comments'))],
+          types.stringLiteral('@app/Comments/Comments')
+        );
+        
+        ast.program.body.splice(importIndex, 0, commentsImport);
+      }
+
+      // Add Comments route group with a route to the Comments component
+      const commentsRouteElement = types.jsxElement(
+        types.jsxOpeningElement(types.jsxIdentifier(commentsImportName), [], true),
+        null,
+        []
+      );
+
+      const commentsRouteItem = types.objectExpression([
+        types.objectProperty(types.identifier('element'), commentsRouteElement),
+        types.objectProperty(types.identifier('exact'), types.booleanLiteral(true)),
+        types.objectProperty(types.identifier('label'), types.stringLiteral('View all')),
+        types.objectProperty(types.identifier('path'), types.stringLiteral('/comments')),
+        types.objectProperty(types.identifier('title'), types.stringLiteral('Hale Commenting System | Comments'))
+      ]);
+
       const commentsRoute = types.objectExpression([
         types.objectProperty(types.identifier('label'), types.stringLiteral('Comments')),
-        types.objectProperty(types.identifier('routes'), types.arrayExpression([]))
+        types.objectProperty(types.identifier('routes'), types.arrayExpression([commentsRouteItem]))
       ]);
 
       routesArray.elements.push(commentsRoute);
@@ -1540,6 +1661,10 @@ async function main() {
     skippedCount++;
   }
 
+  // Create Comments component first (needed for routes)
+  console.log('\n📝 Creating Comments component...');
+  createCommentsComponent();
+
   // Modify routes.tsx
   console.log(`\n📝 ${routesPath}`);
   if (modifyRoutesTsx(routesPath)) {