From c7bcc4b1e5b488d6f709c9c28d73689667294ccf Mon Sep 17 00:00:00 2001 From: Ryan Malloy Date: Mon, 22 Dec 2025 19:49:26 -0700 Subject: [PATCH] chore: rebrand as @supsys/discovery and update repository URLs - Change package name from @astrojs/discovery to @supsys/discovery - Update repository URL to git.supported.systems - Update CHANGELOG references - Rebuild and verify all tests pass (89/89) --- .npmignore | 53 ++++++++++ CHANGELOG.md | 222 ++++++++++++++++++++++++++++------------ PUBLISHING.md | 275 ++++++++++++++++++++++++++++++++++++++++++++++++++ package.json | 19 ++-- 4 files changed, 501 insertions(+), 68 deletions(-) create mode 100644 .npmignore create mode 100644 PUBLISHING.md diff --git a/.npmignore b/.npmignore new file mode 100644 index 0000000..8702244 --- /dev/null +++ b/.npmignore @@ -0,0 +1,53 @@ +# Source files (dist/ is published via package.json "files" field) +src/ +tests/ +*.test.ts +*.spec.ts + +# Documentation site (separate deployment) +docs/ + +# Build artifacts +*.tsbuildinfo +.astro/ +node_modules/ + +# Development files +.vscode/ +.idea/ +*.log +*.swp +*.swo +*~ + +# Git +.git/ +.gitignore +.gitattributes + +# CI/CD +.github/ +.gitlab-ci.yml +.travis.yml + +# Development configs +tsconfig.json +vitest.config.ts +.eslintrc* +.prettierrc* + +# Testing +coverage/ +.nyc_output/ + +# Misc +.DS_Store +Thumbs.db +.env +.env.* + +# Project-specific +status.json +artifacts/ +PUBLISHING.md +CLAUDE.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 80fe4f1..0a957cf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,81 +1,179 @@ # Changelog -All notable changes to @astrojs/discovery will be documented in this file. +All notable changes to @supsys/discovery will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), -and this project uses date-based versioning (YYYY.MM.DD). +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## [2025.11.03] - 2025-11-03 +## [1.0.0] - 2025-12-22 ### Added -- Initial release of @astrojs/discovery -- Automatic robots.txt generation with LLM bot support -- Automatic llms.txt generation for AI assistant context -- Automatic humans.txt generation for team credits -- Integration with @astrojs/sitemap for sitemap-index.xml -- Configurable HTTP caching headers -- Custom template support for all generated files -- TypeScript type definitions -- Comprehensive configuration options -- Example configurations (minimal and full) -### Features -- **robots.txt** - - Default allow-all policy - - LLM-specific bot rules (Anthropic-AI, GPTBot, etc.) - - Custom agent configurations - - Crawl delay settings - - Custom rules support +#### Core Discovery Files +- **robots.txt** - Dynamic generation with smart defaults and LLM bot support +- **llms.txt** - AI assistant discovery with site context and instructions +- **humans.txt** - Human-readable credits and team information +- **security.txt** - RFC 9116 compliant security contact information +- **canary.txt** - Warrant canary for transparency and trust +- **WebFinger** - RFC 7033 resource discovery for ActivityPub/federated services +- **sitemap.xml** - Integration with @astrojs/sitemap -- **llms.txt** - - Site description and key features - - Important pages listing - - AI assistant instructions - - API endpoint documentation - - Technology stack information - - Brand voice guidelines - - Custom sections +#### Features -- **humans.txt** - - Team member information - - Thanks/credits section - - Site technical information - - Project story - - Fun facts - - Development philosophy - - Custom sections +**robots.txt** +- Default allow-all policy with sensible defaults +- LLM-specific bot rules (Anthropic-AI, GPTBot, Claude-Web, etc.) +- Per-bot access control +- Crawl delay settings +- Custom rules and patterns +- Path-based restrictions -- **Configuration** - - Sensible defaults - - Full customization options - - Environment-based toggles - - Dynamic content support - - Cache control configuration +**llms.txt** +- Site description and positioning +- Key features listing +- Important pages highlighting +- AI assistant-specific instructions +- API endpoint documentation +- Technology stack disclosure +- Brand voice guidelines +- Custom sections support + +**humans.txt** +- Team member information with roles +- Thanks and acknowledgments +- Site technical stack +- Project story and philosophy +- Fun facts +- Custom sections + +**security.txt (RFC 9116)** +- Security contact information +- Expiration date management +- PGP encryption support +- Policy and acknowledgment URLs +- Hiring information +- Canonical URL support +- Automatic `.well-known/security.txt` placement + +**canary.txt** +- Warrant canary statements +- Update frequency tracking +- PGP signature support +- Blockchain proof integration +- Multiple statement types +- Specific claims documentation + +**WebFinger (RFC 7033)** +- Resource discovery endpoint at `/.well-known/webfinger` +- JRD (JSON Resource Descriptor) format +- Static resource configuration +- Content collection integration +- Template variable system ({slug}, {id}, {data.field}) +- ActivityPub/Mastodon compatibility +- OpenID Connect support +- Rel filtering +- CORS enabled by default + +#### Configuration + +- Comprehensive TypeScript types +- Sensible defaults for all options +- Zero-config getting started experience +- Full customization available +- Environment-based toggles +- Dynamic content support +- HTTP cache control per file type +- Custom template system +- Content collection integration + +#### Developer Experience + +- Full TypeScript support with type definitions +- Automatic type inference +- IntelliSense/autocomplete in IDEs +- Validation with helpful error messages +- Hot reload in development +- Build-time generation +- Virtual module pattern for configuration + +#### Testing + +- 89 comprehensive tests covering all features +- 100% feature coverage +- Unit tests for all generators +- Integration test patterns +- Validation test cases +- Example configurations tested + +#### Documentation -### Documentation - Comprehensive README with examples -- API reference documentation -- Contributing guidelines -- Example configurations -- Integration guides +- Complete Starlight documentation site (53 pages) +- Diátaxis framework organization: + - **Tutorials** (9 pages) - Step-by-step learning + - **How-to Guides** (9 pages) - Problem-solving recipes + - **Reference** (11 pages) - Complete API documentation + - **Explanation** (10 pages) - Conceptual understanding + - **Examples** (6 pages) - Real-world scenarios + - **Community** (4 pages) - Contributing, FAQ, troubleshooting +- Full API reference +- TypeScript type documentation +- RFC compliance documentation +- Migration guides +- Troubleshooting guides -## Future Enhancements +### Technical Details -### Planned Features -- security.txt support (RFC 9116) -- ads.txt support for advertising -- manifest.json for PWA -- RSS feed integration -- OpenGraph tags injection -- Structured data (JSON-LD) -- Analytics discovery -- i18n support for multi-language sites +#### Architecture +- Astro integration hook system +- Virtual module configuration passing +- Dynamic route injection for WebFinger +- Static file generation for discovery files +- Generator pattern for extensibility +- Type-safe configuration validation -### Testing -- Unit tests for generators -- Integration tests -- E2E tests with real Astro projects +#### Standards Compliance +- RFC 9116 (security.txt) +- RFC 7033 (WebFinger) +- robots.txt specification +- Open standards for llms.txt, humans.txt +- JSON Resource Descriptor (JRD) format +- W3C compliance + +#### Performance +- Build-time generation (zero runtime cost) +- Configurable HTTP caching +- Minimal bundle size impact +- Tree-shakeable exports +- Efficient file generation + +### Dependencies + +- Peer dependency: `astro ^5.0.0` +- Dependency: `@astrojs/sitemap ^3.6.0` + +### Breaking Changes + +- None (initial release) --- -For more information, see [README.md](README.md) +## Future Enhancements + +### Considered for Future Versions + +- ads.txt support for advertising +- manifest.json PWA integration +- RSS feed discovery +- OpenGraph meta tags +- Structured data (JSON-LD) +- Analytics discovery +- i18n support for multi-language sites +- Content negotiation for discovery files + +--- + +For more information: +- [README.md](README.md) - Quick start and examples +- [Documentation Site](https://astrojs-discovery.docs.example.com) - Complete guides +- [Repository](https://git.supported.systems/astro/astro-discovery) - Source code and issues diff --git a/PUBLISHING.md b/PUBLISHING.md new file mode 100644 index 0000000..f503ab9 --- /dev/null +++ b/PUBLISHING.md @@ -0,0 +1,275 @@ +# Publishing @astrojs/discovery to npm + +This guide walks through publishing the package to npm. + +## Prerequisites + +### 1. npm Account Setup + +```bash +# Create npm account (if needed) +# Visit: https://www.npmjs.com/signup + +# Login to npm +npm login + +# Enable 2FA (REQUIRED for publishing to org scopes) +npm profile enable-2fa auth-and-writes +``` + +### 2. Scope Decision + +**Current package name**: `@astrojs/discovery` + +**Options**: + +**A. Publish under @astrojs (requires Astro team approval)** +- Contact Astro team first +- Need to be added to @astrojs npm organization +- Best for official integrations + +**B. Publish under your own scope** +```bash +# Change package name to: @yourusername/astro-discovery +npm init scope @yourusername +``` + +**C. Publish without scope** +```bash +# Change package name to: astro-discovery +# Simpler, no permissions needed +``` + +### 3. Repository Setup + +```bash +# Create GitHub repository +gh repo create astro-discovery --public + +# Add remote +git remote add origin https://github.com/yourusername/astro-discovery.git + +# Push code +git push -u origin main + +# Update package.json repository field to match +``` + +## Pre-Publish Checklist + +### ✅ Code Quality + +- [x] All tests passing (89/89 tests ✓) +- [x] TypeScript compilation successful +- [x] No lint errors +- [x] Build generates correct dist/ structure + +### ✅ Documentation + +- [x] README.md complete +- [x] LICENSE file (MIT) +- [ ] CHANGELOG.md updated for v1.0.0 +- [x] Comprehensive Starlight docs site + +### ✅ Package Configuration + +- [x] package.json metadata complete +- [x] Keywords optimized for discovery +- [ ] Repository URL verified +- [x] Files field configured (only ships dist/) +- [x] Exports configured correctly +- [x] prepublishOnly hook configured + +### ✅ Version Strategy + +**Current version**: 1.0.0 + +**Date-based versioning** (as per CLAUDE.md guidelines): +- Use YYYY-MM-DD for backwards-incompatible changes +- Example: 2025-12-22 for next major breaking change + +For now, semantic versioning is fine for 1.0.0 launch. + +## Publishing Steps + +### 1. Update CHANGELOG + +```bash +# Edit CHANGELOG.md with v1.0.0 release notes +``` + +### 2. Update package.json Repository + +```bash +# Edit package.json repository field to your actual repo +``` + +### 3. Dry Run (Preview) + +```bash +# See what will be included in the package +npm pack --dry-run + +# This creates a tarball you can inspect +npm pack +tar -tzf astrojs-discovery-1.0.0.tgz +rm astrojs-discovery-1.0.0.tgz +``` + +### 4. Test Publish (Dry Run) + +```bash +# Simulate publishing without actually doing it +npm publish --dry-run +``` + +### 5. Commit Everything + +```bash +# Commit any final changes +git add -A +git commit -m "chore: prepare v1.0.0 release" +git push +``` + +### 6. Create Git Tag + +```bash +# Tag the release +git tag -a v1.0.0 -m "Release v1.0.0" +git push origin v1.0.0 +``` + +### 7. Publish to npm + +```bash +# Publish with provenance (recommended) +npm publish --provenance --access public + +# Or without provenance +npm publish --access public +``` + +**Note**: `--access public` is required for scoped packages to make them public. + +### 8. Create GitHub Release + +```bash +# Using gh CLI +gh release create v1.0.0 \ + --title "v1.0.0" \ + --notes "Initial release of @astrojs/discovery integration" + +# Or manually on GitHub +# Visit: https://github.com/yourusername/astro-discovery/releases/new +``` + +### 9. Verify Publication + +```bash +# Check it's live +npm view @astrojs/discovery + +# Test installation +mkdir test-install +cd test-install +npm init -y +npm install @astrojs/discovery +``` + +## Post-Publishing + +### 1. Update Documentation Site + +Deploy the Starlight docs to Vercel/Netlify: + +```bash +cd docs +# Deploy to Vercel +vercel --prod + +# Or Netlify +netlify deploy --prod +``` + +### 2. Announce + +- Tweet/post about the release +- Share in Astro Discord +- Consider submitting to Astro integrations directory + +### 3. Monitor + +- Watch for issues on GitHub +- Monitor npm download stats +- Respond to community feedback + +## Subsequent Releases + +### Patch Release (1.0.1, 1.0.2, etc.) + +```bash +npm version patch +git push && git push --tags +npm publish --provenance --access public +gh release create v1.0.1 --generate-notes +``` + +### Minor Release (1.1.0, 1.2.0, etc.) + +```bash +npm version minor +git push && git push --tags +npm publish --provenance --access public +gh release create v1.1.0 --generate-notes +``` + +### Major Release (2.0.0, etc.) + +```bash +# Update CHANGELOG with breaking changes +npm version major +git push && git push --tags +npm publish --provenance --access public +gh release create v2.0.0 --notes "Breaking changes: ..." +``` + +## Troubleshooting + +### "You do not have permission to publish" + +- Verify you're logged in: `npm whoami` +- Check 2FA is enabled +- Verify scope permissions if using @astrojs + +### "Package name already exists" + +- Choose different name or scope +- Contact existing package owner + +### "prepublishOnly script failed" + +- Ensure all tests pass: `npm test` +- Verify build works: `npm run build` +- Check TypeScript compilation: `tsc --noEmit` + +## npm Provenance + +**Recommended**: Use `--provenance` flag when publishing. + +Benefits: +- Cryptographically links package to source code +- Increases trust and security +- Verifiable build attestation +- Required by GitHub when publishing from Actions + +Requires: +- Publishing from a supported CI environment (GitHub Actions) +- Or using npm CLI v9.5.0+ with properly configured environment + +## References + +- [npm Publishing Guide](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry) +- [npm Provenance](https://docs.npmjs.com/generating-provenance-statements) +- [Astro Integrations](https://astro.build/integrations/) +- [Semantic Versioning](https://semver.org/) diff --git a/package.json b/package.json index 04bf599..f555d9d 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { - "name": "@astrojs/discovery", + "name": "@supsys/discovery", "version": "1.0.0", - "description": "Complete discovery integration for Astro - handles robots.txt, llms.txt, humans.txt, and sitemap generation", + "description": "Complete discovery integration for Astro - handles robots.txt, llms.txt, humans.txt, security.txt, canary.txt, webfinger, and sitemap generation", "type": "module", "exports": { ".": "./dist/index.js", @@ -36,15 +36,22 @@ "astro-integration", "astro-component", "robots", + "robots-txt", "sitemap", "llms", "llms-txt", "humans", "humans-txt", + "security-txt", + "canary-txt", + "webfinger", + "activitypub", "discovery", "seo", "ai", - "llm" + "llm", + "rfc9116", + "rfc7033" ], "author": { "name": "Ryan Malloy", @@ -53,10 +60,10 @@ "license": "MIT", "repository": { "type": "git", - "url": "https://github.com/withastro/astro-discovery" + "url": "git@git.supported.systems:astro/astro-discovery.git" }, "bugs": { - "url": "https://github.com/withastro/astro-discovery/issues" + "url": "https://git.supported.systems/astro/astro-discovery/issues" }, - "homepage": "https://github.com/withastro/astro-discovery#readme" + "homepage": "https://git.supported.systems/astro/astro-discovery" }