astro/astro-discovery
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: rebrand as @supsys/discovery and update repository URLs

Browse Source 
- 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)
This commit is contained in:
Ryan Malloy 2025-12-22 19:49:26 -07:00
parent 192ce8194f
commit c7bcc4b1e5
4 changed files with 501 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
.npmignore Normal file
View File

@ -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

208
CHANGELOG.md
View File

@ -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
#### 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
#### Features
**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 support
- Custom rules and patterns
- Path-based restrictions
- **llms.txt**
- Site description and key features
- Important pages listing
- AI assistant instructions
**llms.txt**
- Site description and positioning
- Key features listing
- Important pages highlighting
- AI assistant-specific instructions
- API endpoint documentation
- Technology stack information
- Technology stack disclosure
- Brand voice guidelines
- Custom sections
- Custom sections support
- **humans.txt**
- Team member information
- Thanks/credits section
- Site technical information
- Project story
**humans.txt**
- Team member information with roles
- Thanks and acknowledgments
- Site technical stack
- Project story and philosophy
- Fun facts
- Development philosophy
- Custom sections
- **Configuration**
- Sensible defaults
- Full customization options
**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
- Cache control configuration
- 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

275
PUBLISHING.md Normal file
View File

@ -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/)

19
package.json
View File

@ -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"
}