aethex-forge/scripts/README.md

GitHub Issues Import Script

Automatically converts markdown issue documentation into GitHub Issues.

Quick Start

1. Install Dependencies

npm install @octokit/rest

2. Get GitHub Token

1. Go to https://github.com/settings/tokens
2. Click "Generate new token (classic)"
3. Give it a name: "Issue Import Script"
4. Select scope: repo (full control of private repositories)
5. Click "Generate token"
6. Copy the token (you won't see it again!)

3. Set Token

export GITHUB_TOKEN=your_github_token_here

Or add to your shell profile (~/.bashrc, ~/.zshrc):

echo 'export GITHUB_TOKEN=your_token_here' >> ~/.bashrc
source ~/.bashrc

4. Run the Script

node scripts/import-github-issues.js

What It Does

The script will:

1. ✅ Create all necessary labels (P0, P1, P2, bug, feature, etc.)

2. 📄 Parse docs/issues/P0-ISSUES.md, P1-ISSUES.md, P2-ISSUES.md

3. 🎯 Create GitHub Issues with:

   • Proper titles with priority prefix
   • Full issue body with formatting
   • Appropriate labels
   • Links to referenced files

4. 📊 Output summary with issue URLs

Example Output

🚀 GitHub Issues Import Script

📝 Ensuring labels exist...
  ✓ Label "P0" exists
  ✓ Created label "P1"
  ✓ Created label "bug"

📄 Processing P0-ISSUES.md...
   Found 5 issues

  ✓ Created: [P0] Fix onboarding progress loss on page refresh
    → https://github.com/AeThex-Corporation/aethex-forge/issues/1
  ✓ Created: [P0] Complete Stripe payment integration
    → https://github.com/AeThex-Corporation/aethex-forge/issues/2
  ...

✅ Done! Created 25 GitHub issues

View issues: https://github.com/AeThex-Corporation/aethex-forge/issues

Troubleshooting

Error: GITHUB_TOKEN not set

export GITHUB_TOKEN=your_token_here

Error: 404 Not Found

• Check that REPO_OWNER and REPO_NAME in the script match your repository
• Verify your token has repo scope

Error: 403 Forbidden

• Your token doesn't have permission
• Generate a new token with repo scope

Error: npm ERR! Cannot find module '@octokit/rest'

npm install @octokit/rest

Customization

Edit scripts/import-github-issues.js:

// Change repository
const REPO_OWNER = 'YourGitHubUsername';
const REPO_NAME = 'your-repo-name';

// Add custom labels
const LABELS = {
  P0: { name: 'P0', color: 'B60205', description: 'Critical' },
  // Add more...
};

What Gets Created

Labels

• P0 (red) - Critical priority
• P1 (orange) - Medium priority
• P2 (yellow) - Low priority
• bug (red) - Something isn't working
• feature (green) - New feature
• enhancement (blue) - Enhancement
• tech-debt (purple) - Technical debt
• security (red) - Security issue

Issues from P0-ISSUES.md

1. Fix onboarding progress loss (bug, P0)
2. Complete Stripe integration (bug, P0)
3. Refactor large components (tech-debt, P0)
4. Add error tracking (feature, P0)
5. Add form validation (feature, P0)

Issues from P1-ISSUES.md

1. Build notification system (feature, P1)
2. Complete project workflows (feature, P1)
3. Add image upload (feature, P1)
4. Implement moderation (feature, P1)
5. Add 2FA (security, P1)

Issues from P2-ISSUES.md

15 enhancement issues (dark mode, i18n, PWA, etc.)

Advanced Usage

Dry Run (Preview)

Edit the script and comment out the createIssue call to see what would be created:

// await createIssue(issue);  // Comment this out
console.log('Would create:', issue.title);

Assign Issues

Add assignees to created issues:

await octokit.rest.issues.create({
  // ...existing params
  assignees: ['your-github-username'],
});

Create Milestone

Group issues under a milestone:

// Create milestone first
const milestone = await octokit.rest.issues.createMilestone({
  owner: REPO_OWNER,
  repo: REPO_NAME,
  title: 'Q1 2026 Priorities',
});

// Then assign to issues
await octokit.rest.issues.create({
  // ...existing params
  milestone: milestone.data.number,
});

Clean Up

To delete all created issues (use with caution!):

# List all issues
gh issue list --limit 100

# Close specific issue
gh issue close <issue-number>

# Or delete (requires admin access)
gh api -X DELETE /repos/OWNER/REPO/issues/ISSUE_NUMBER

Notes

• Script waits 1 second between creating issues to respect GitHub API rate limits
• Issues are created in order: P0 → P1 → P2
• Existing labels won't be overwritten
• Run as many times as needed (won't create duplicates if you don't re-run)