xithead 1.4.0 → 1.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.actrc +14 -0
- package/.actrc.local.example +15 -0
- package/.changelog.md +2 -0
- package/.claude/agents/academic-anthropologist.md +125 -0
- package/.claude/agents/academic-geographer.md +127 -0
- package/.claude/agents/academic-historian.md +123 -0
- package/.claude/agents/academic-narratologist.md +118 -0
- package/.claude/agents/academic-psychologist.md +118 -0
- package/.claude/agents/academic-statistician.md +144 -0
- package/.claude/agents/accounts-payable-agent.md +205 -0
- package/.claude/agents/agentic-identity-trust.md +394 -0
- package/.claude/agents/agents-orchestrator.md +367 -0
- package/.claude/agents/automation-governance-architect.md +216 -0
- package/.claude/agents/blender-addon-engineer.md +243 -0
- package/.claude/agents/business-strategist.md +488 -0
- package/.claude/agents/change-management-consultant.md +497 -0
- package/.claude/agents/chief-financial-officer.md +388 -0
- package/.claude/agents/corporate-training-designer.md +192 -0
- package/.claude/agents/customer-service.md +398 -0
- package/.claude/agents/customer-success-manager.md +460 -0
- package/.claude/agents/data-consolidation-agent.md +60 -0
- package/.claude/agents/data-privacy-officer.md +412 -0
- package/.claude/agents/design-brand-guardian.md +322 -0
- package/.claude/agents/design-image-prompt-engineer.md +236 -0
- package/.claude/agents/design-inclusive-visuals-specialist.md +73 -0
- package/.claude/agents/design-persona-walkthrough.md +272 -0
- package/.claude/agents/design-ui-designer.md +386 -0
- package/.claude/agents/design-ui-finish-gate-reviewer.md +217 -0
- package/.claude/agents/design-ux-architect.md +482 -0
- package/.claude/agents/design-ux-researcher.md +329 -0
- package/.claude/agents/design-visual-storyteller.md +149 -0
- package/.claude/agents/design-whimsy-injector.md +460 -0
- package/.claude/agents/economy-designer.md +156 -0
- package/.claude/agents/engineering-ai-data-remediation-engineer.md +211 -0
- package/.claude/agents/engineering-ai-engineer.md +146 -0
- package/.claude/agents/engineering-api-platform-engineer.md +181 -0
- package/.claude/agents/engineering-ats-validator-architect.md +383 -0
- package/.claude/agents/engineering-autonomous-optimization-architect.md +121 -0
- package/.claude/agents/engineering-backend-architect.md +255 -0
- package/.claude/agents/engineering-china-network-engineer.md +252 -0
- package/.claude/agents/engineering-cms-developer.md +536 -0
- package/.claude/agents/engineering-code-reviewer.md +76 -0
- package/.claude/agents/engineering-codebase-onboarding-engineer.md +173 -0
- package/.claude/agents/engineering-data-engineer.md +349 -0
- package/.claude/agents/engineering-data-visualization-engineer.md +151 -0
- package/.claude/agents/engineering-database-optimizer.md +188 -0
- package/.claude/agents/engineering-database-reliability-engineer.md +201 -0
- package/.claude/agents/engineering-desktop-app-engineer.md +209 -0
- package/.claude/agents/engineering-developer-tooling-engineer.md +153 -0
- package/.claude/agents/engineering-devops-automator.md +385 -0
- package/.claude/agents/engineering-drupal-performance.md +347 -0
- package/.claude/agents/engineering-drupal-shopping-cart.md +360 -0
- package/.claude/agents/engineering-electrical-engineer.md +575 -0
- package/.claude/agents/engineering-email-intelligence-engineer.md +390 -0
- package/.claude/agents/engineering-embedded-firmware-engineer.md +196 -0
- package/.claude/agents/engineering-feishu-integration-developer.md +606 -0
- package/.claude/agents/engineering-filament-optimization-specialist.md +283 -0
- package/.claude/agents/engineering-finops-engineer.md +164 -0
- package/.claude/agents/engineering-frontend-developer.md +257 -0
- package/.claude/agents/engineering-gaussdb-expert.md +334 -0
- package/.claude/agents/engineering-git-workflow-master.md +98 -0
- package/.claude/agents/engineering-i18n-engineer.md +214 -0
- package/.claude/agents/engineering-identity-access-engineer.md +217 -0
- package/.claude/agents/engineering-incident-response-commander.md +444 -0
- package/.claude/agents/engineering-iot-fleet-engineer.md +148 -0
- package/.claude/agents/engineering-it-service-manager.md +561 -0
- package/.claude/agents/engineering-knowledge-graph-engineer.md +372 -0
- package/.claude/agents/engineering-llm-post-training-engineer.md +166 -0
- package/.claude/agents/engineering-minimal-change-engineer.md +207 -0
- package/.claude/agents/engineering-mobile-app-builder.md +493 -0
- package/.claude/agents/engineering-mobile-release-engineer.md +164 -0
- package/.claude/agents/engineering-multi-agent-systems-architect.md +600 -0
- package/.claude/agents/engineering-network-engineer.md +245 -0
- package/.claude/agents/engineering-orgscript-engineer.md +113 -0
- package/.claude/agents/engineering-payments-billing-engineer.md +228 -0
- package/.claude/agents/engineering-pdf-engine-architect.md +696 -0
- package/.claude/agents/engineering-platform-engineer.md +270 -0
- package/.claude/agents/engineering-privacy-engineer.md +152 -0
- package/.claude/agents/engineering-prompt-engineer.md +209 -0
- package/.claude/agents/engineering-rag-pipeline-engineer.md +450 -0
- package/.claude/agents/engineering-rapid-prototyper.md +466 -0
- package/.claude/agents/engineering-realtime-collaboration-engineer.md +200 -0
- package/.claude/agents/engineering-rust-refactoring-specialist.md +313 -0
- package/.claude/agents/engineering-search-relevance-engineer.md +237 -0
- package/.claude/agents/engineering-section-508-specialist.md +339 -0
- package/.claude/agents/engineering-senior-developer.md +176 -0
- package/.claude/agents/engineering-servicenow-developer-mentor.md +180 -0
- package/.claude/agents/engineering-software-architect.md +112 -0
- package/.claude/agents/engineering-solidity-smart-contract-engineer.md +522 -0
- package/.claude/agents/engineering-sre.md +90 -0
- package/.claude/agents/engineering-technical-writer.md +393 -0
- package/.claude/agents/engineering-universal-document-compiler.md +370 -0
- package/.claude/agents/engineering-uswds-developer.md +340 -0
- package/.claude/agents/engineering-video-streaming-engineer.md +151 -0
- package/.claude/agents/engineering-voice-ai-integration-engineer.md +584 -0
- package/.claude/agents/engineering-webassembly-engineer.md +153 -0
- package/.claude/agents/engineering-wechat-mini-program-developer.md +356 -0
- package/.claude/agents/engineering-wordpress-performance.md +346 -0
- package/.claude/agents/engineering-wordpress-shopping-cart.md +346 -0
- package/.claude/agents/esg-sustainability-officer.md +396 -0
- package/.claude/agents/finance-bookkeeper-controller.md +260 -0
- package/.claude/agents/finance-financial-analyst.md +234 -0
- package/.claude/agents/finance-fpa-analyst.md +263 -0
- package/.claude/agents/finance-investment-researcher.md +272 -0
- package/.claude/agents/finance-tax-strategist.md +239 -0
- package/.claude/agents/game-audio-engineer.md +264 -0
- package/.claude/agents/game-designer.md +167 -0
- package/.claude/agents/gis-3d-scene-developer.md +111 -0
- package/.claude/agents/gis-analyst.md +91 -0
- package/.claude/agents/gis-bim-specialist.md +108 -0
- package/.claude/agents/gis-cartography-designer.md +150 -0
- package/.claude/agents/gis-drone-reality-mapping.md +120 -0
- package/.claude/agents/gis-geoai-ml-engineer.md +105 -0
- package/.claude/agents/gis-geoprocessing-specialist.md +97 -0
- package/.claude/agents/gis-qa-engineer.md +133 -0
- package/.claude/agents/gis-solution-engineer.md +101 -0
- package/.claude/agents/gis-spatial-data-engineer.md +97 -0
- package/.claude/agents/gis-spatial-data-scientist.md +111 -0
- package/.claude/agents/gis-technical-consultant.md +86 -0
- package/.claude/agents/gis-web-gis-developer.md +108 -0
- package/.claude/agents/godot-gameplay-scripter.md +338 -0
- package/.claude/agents/godot-multiplayer-engineer.md +301 -0
- package/.claude/agents/godot-shader-developer.md +267 -0
- package/.claude/agents/government-digital-presales-consultant.md +363 -0
- package/.claude/agents/grant-writer.md +511 -0
- package/.claude/agents/healthcare-aging-parent-care-companion.md +414 -0
- package/.claude/agents/healthcare-clinical-evidence-agent.md +231 -0
- package/.claude/agents/healthcare-customer-service.md +389 -0
- package/.claude/agents/healthcare-innovation-strategist.md +433 -0
- package/.claude/agents/healthcare-marketing-compliance.md +395 -0
- package/.claude/agents/healthcare-sovereign-health-systems-agent.md +312 -0
- package/.claude/agents/hospitality-guest-services.md +603 -0
- package/.claude/agents/hr-onboarding.md +451 -0
- package/.claude/agents/identity-graph-operator.md +303 -0
- package/.claude/agents/language-translator.md +264 -0
- package/.claude/agents/legal-billing-time-tracking.md +569 -0
- package/.claude/agents/legal-client-intake.md +492 -0
- package/.claude/agents/legal-document-review.md +454 -0
- package/.claude/agents/level-designer.md +208 -0
- package/.claude/agents/loan-officer-assistant.md +555 -0
- package/.claude/agents/lsp-index-engineer.md +320 -0
- package/.claude/agents/ma-integration-manager.md +427 -0
- package/.claude/agents/macos-spatial-metal-engineer.md +337 -0
- package/.claude/agents/marketing-aeo-foundations.md +264 -0
- package/.claude/agents/marketing-agentic-search-optimizer.md +279 -0
- package/.claude/agents/marketing-ai-citation-strategist.md +172 -0
- package/.claude/agents/marketing-app-store-optimizer.md +321 -0
- package/.claude/agents/marketing-baidu-seo-specialist.md +226 -0
- package/.claude/agents/marketing-bilibili-content-strategist.md +199 -0
- package/.claude/agents/marketing-book-co-author.md +110 -0
- package/.claude/agents/marketing-carousel-growth-engine.md +204 -0
- package/.claude/agents/marketing-china-ecommerce-operator.md +283 -0
- package/.claude/agents/marketing-china-market-localization-strategist.md +283 -0
- package/.claude/agents/marketing-content-creator.md +54 -0
- package/.claude/agents/marketing-cross-border-ecommerce.md +259 -0
- package/.claude/agents/marketing-developer-community-builder.md +285 -0
- package/.claude/agents/marketing-douyin-strategist.md +149 -0
- package/.claude/agents/marketing-email-strategist.md +249 -0
- package/.claude/agents/marketing-global-podcast-strategist.md +206 -0
- package/.claude/agents/marketing-growth-hacker.md +54 -0
- package/.claude/agents/marketing-instagram-curator.md +113 -0
- package/.claude/agents/marketing-kuaishou-strategist.md +223 -0
- package/.claude/agents/marketing-linkedin-content-creator.md +214 -0
- package/.claude/agents/marketing-livestream-commerce-coach.md +305 -0
- package/.claude/agents/marketing-multi-platform-publisher.md +217 -0
- package/.claude/agents/marketing-podcast-strategist.md +277 -0
- package/.claude/agents/marketing-pr-communications-manager.md +473 -0
- package/.claude/agents/marketing-private-domain-operator.md +308 -0
- package/.claude/agents/marketing-reddit-community-builder.md +123 -0
- package/.claude/agents/marketing-seo-specialist.md +370 -0
- package/.claude/agents/marketing-short-video-editing-coach.md +412 -0
- package/.claude/agents/marketing-social-media-strategist.md +125 -0
- package/.claude/agents/marketing-tiktok-strategist.md +125 -0
- package/.claude/agents/marketing-twitter-engager.md +126 -0
- package/.claude/agents/marketing-video-optimization-specialist.md +119 -0
- package/.claude/agents/marketing-wechat-official-account.md +145 -0
- package/.claude/agents/marketing-weibo-strategist.md +240 -0
- package/.claude/agents/marketing-x-twitter-intelligence-analyst.md +161 -0
- package/.claude/agents/marketing-xiaohongshu-specialist.md +138 -0
- package/.claude/agents/marketing-zhihu-strategist.md +162 -0
- package/.claude/agents/medical-billing-coding-specialist.md +491 -0
- package/.claude/agents/narrative-designer.md +243 -0
- package/.claude/agents/operations-manager.md +399 -0
- package/.claude/agents/organizational-psychologist.md +391 -0
- package/.claude/agents/paid-media-auditor.md +71 -0
- package/.claude/agents/paid-media-creative-strategist.md +71 -0
- package/.claude/agents/paid-media-paid-social-strategist.md +71 -0
- package/.claude/agents/paid-media-ppc-strategist.md +71 -0
- package/.claude/agents/paid-media-programmatic-buyer.md +71 -0
- package/.claude/agents/paid-media-search-query-analyst.md +71 -0
- package/.claude/agents/paid-media-tracking-specialist.md +71 -0
- package/.claude/agents/personal-growth-mentor.md +159 -0
- package/.claude/agents/product-behavioral-nudge-engine.md +83 -0
- package/.claude/agents/product-dx-engineer.md +332 -0
- package/.claude/agents/product-feedback-synthesizer.md +119 -0
- package/.claude/agents/product-manager.md +469 -0
- package/.claude/agents/product-sprint-prioritizer.md +154 -0
- package/.claude/agents/product-trend-researcher.md +159 -0
- package/.claude/agents/project-management-experiment-tracker.md +198 -0
- package/.claude/agents/project-management-jira-workflow-steward.md +233 -0
- package/.claude/agents/project-management-meeting-notes-specialist.md +95 -0
- package/.claude/agents/project-management-project-shepherd.md +194 -0
- package/.claude/agents/project-management-studio-operations.md +200 -0
- package/.claude/agents/project-management-studio-producer.md +203 -0
- package/.claude/agents/project-manager-senior.md +135 -0
- package/.claude/agents/real-estate-buyer-seller.md +596 -0
- package/.claude/agents/recruitment-specialist.md +515 -0
- package/.claude/agents/report-distribution-agent.md +65 -0
- package/.claude/agents/research-synthesist.md +136 -0
- package/.claude/agents/resume-tailor.md +230 -0
- package/.claude/agents/retail-customer-returns.md +566 -0
- package/.claude/agents/roblox-avatar-creator.md +297 -0
- package/.claude/agents/roblox-experience-designer.md +306 -0
- package/.claude/agents/roblox-systems-scripter.md +332 -0
- package/.claude/agents/sales-account-strategist.md +227 -0
- package/.claude/agents/sales-coach.md +271 -0
- package/.claude/agents/sales-data-extraction-agent.md +67 -0
- package/.claude/agents/sales-deal-strategist.md +180 -0
- package/.claude/agents/sales-discovery-coach.md +225 -0
- package/.claude/agents/sales-engineer.md +182 -0
- package/.claude/agents/sales-offer-lead-gen-strategist.md +257 -0
- package/.claude/agents/sales-outbound-strategist.md +201 -0
- package/.claude/agents/sales-outreach.md +425 -0
- package/.claude/agents/sales-pipeline-analyst.md +267 -0
- package/.claude/agents/sales-proposal-strategist.md +217 -0
- package/.claude/agents/security-ai-generated-code-auditor.md +207 -0
- package/.claude/agents/security-appsec-engineer.md +536 -0
- package/.claude/agents/security-architect.md +307 -0
- package/.claude/agents/security-blockchain-security-auditor.md +482 -0
- package/.claude/agents/security-cloud-security-architect.md +576 -0
- package/.claude/agents/security-compliance-auditor.md +158 -0
- package/.claude/agents/security-incident-responder.md +450 -0
- package/.claude/agents/security-penetration-tester.md +399 -0
- package/.claude/agents/security-secrets-credential-engineer.md +189 -0
- package/.claude/agents/security-senior-secops.md +760 -0
- package/.claude/agents/security-threat-detection-engineer.md +553 -0
- package/.claude/agents/security-threat-intelligence-analyst.md +661 -0
- package/.claude/agents/specialized-chief-of-staff.md +279 -0
- package/.claude/agents/specialized-civil-engineer.md +356 -0
- package/.claude/agents/specialized-codebase-archaeologist.md +341 -0
- package/.claude/agents/specialized-cultural-intelligence-strategist.md +88 -0
- package/.claude/agents/specialized-developer-advocate.md +317 -0
- package/.claude/agents/specialized-document-generator.md +55 -0
- package/.claude/agents/specialized-fedramp-rmf-compliance.md +378 -0
- package/.claude/agents/specialized-focus-music-architect.md +175 -0
- package/.claude/agents/specialized-french-consulting-market.md +194 -0
- package/.claude/agents/specialized-korean-business-navigator.md +216 -0
- package/.claude/agents/specialized-master-plan-architect.md +157 -0
- package/.claude/agents/specialized-mcp-builder.md +260 -0
- package/.claude/agents/specialized-model-qa.md +528 -0
- package/.claude/agents/specialized-pricing-analyst.md +243 -0
- package/.claude/agents/specialized-salesforce-architect.md +182 -0
- package/.claude/agents/specialized-strategy-duel-agent.md +130 -0
- package/.claude/agents/specialized-workflow-architect.md +597 -0
- package/.claude/agents/study-abroad-advisor.md +282 -0
- package/.claude/agents/supply-chain-strategist.md +591 -0
- package/.claude/agents/support-analytics-reporter.md +387 -0
- package/.claude/agents/support-executive-summary-generator.md +212 -0
- package/.claude/agents/support-finance-tracker.md +480 -0
- package/.claude/agents/support-infrastructure-maintainer.md +628 -0
- package/.claude/agents/support-legal-compliance-checker.md +591 -0
- package/.claude/agents/support-support-responder.md +607 -0
- package/.claude/agents/technical-artist.md +233 -0
- package/.claude/agents/terminal-integration-specialist.md +70 -0
- package/.claude/agents/testing-accessibility-auditor.md +327 -0
- package/.claude/agents/testing-api-tester.md +334 -0
- package/.claude/agents/testing-evidence-collector.md +210 -0
- package/.claude/agents/testing-performance-benchmarker.md +283 -0
- package/.claude/agents/testing-reality-checker.md +249 -0
- package/.claude/agents/testing-test-automation-engineer.md +196 -0
- package/.claude/agents/testing-test-results-analyzer.md +330 -0
- package/.claude/agents/testing-tool-evaluator.md +416 -0
- package/.claude/agents/testing-workflow-optimizer.md +463 -0
- package/.claude/agents/unity-architect.md +271 -0
- package/.claude/agents/unity-editor-tool-developer.md +310 -0
- package/.claude/agents/unity-multiplayer-engineer.md +323 -0
- package/.claude/agents/unity-shader-graph-artist.md +269 -0
- package/.claude/agents/unreal-multiplayer-architect.md +364 -0
- package/.claude/agents/unreal-systems-engineer.md +322 -0
- package/.claude/agents/unreal-technical-artist.md +256 -0
- package/.claude/agents/unreal-world-builder.md +273 -0
- package/.claude/agents/visionos-spatial-engineer.md +54 -0
- package/.claude/agents/xr-cockpit-interaction-specialist.md +32 -0
- package/.claude/agents/xr-immersive-developer.md +32 -0
- package/.claude/agents/xr-interface-architect.md +32 -0
- package/.claude/agents/zk-steward.md +211 -0
- package/.claude-plugin/marketplace.json +30 -0
- package/.commitlintrc.json +26 -0
- package/.devcontainer/Dockerfile +24 -0
- package/.devcontainer/devcontainer.json +70 -0
- package/.devcontainer/docker-compose.memory.yml +42 -0
- package/.devcontainer/memory-stack/devcontainer.json +84 -0
- package/.devcontainer/post-create.sh +83 -0
- package/.dockerignore +23 -0
- package/.env.act.example +15 -0
- package/.env.example +171 -0
- package/.eslintrc.json +16 -0
- package/.git-blame-ignore-revs +10 -0
- package/.gitattributes +2 -0
- package/.gitguardian.yaml +50 -0
- package/.githooks/pre-commit +6 -0
- package/.pre-commit-config.yaml +30 -0
- package/.release-please-config-xithead.json +22 -0
- package/.release-please-config.json +44 -0
- package/.release-please-manifest-xithead.json +3 -0
- package/.release-please-manifest.json +3 -0
- package/CODE_OF_CONDUCT.md +133 -0
- package/CONTRIBUTING.md +133 -0
- package/Cargo.lock +5557 -0
- package/Cargo.toml +121 -0
- package/Dockerfile +38 -0
- package/Dockerfile.proxy +48 -0
- package/ENTERPRISE.md +5 -0
- package/FEATURES_ADVANCED.md +311 -0
- package/Headroom-2.gif +0 -0
- package/HeadroomDemo-Fast.gif +0 -0
- package/MANIFEST.in +4 -0
- package/MODERNIZATION_GUIDE.md +358 -0
- package/Makefile +140 -0
- package/NOTICE +43 -0
- package/NPM_TOKEN_SETUP.md +81 -0
- package/PR.md +170 -0
- package/PUBLISH.md +77 -0
- package/README.md +108 -72
- package/README_FRONTEND.md +196 -0
- package/REALIGNMENT/00-overview.md +53 -0
- package/REALIGNMENT/01-bug-list.md +421 -0
- package/REALIGNMENT/02-architecture.md +322 -0
- package/REALIGNMENT/03-phase-A-lockdown.md +420 -0
- package/REALIGNMENT/04-phase-B-live-zone.md +470 -0
- package/REALIGNMENT/05-phase-C-rust-proxy.md +329 -0
- package/REALIGNMENT/06-phase-D-bedrock-vertex.md +222 -0
- package/REALIGNMENT/07-phase-E-cache-stabilization.md +338 -0
- package/REALIGNMENT/08-phase-F-auth-mode.md +254 -0
- package/REALIGNMENT/09-phase-G-rtk-observability.md +194 -0
- package/REALIGNMENT/10-phase-H-python-retirement.md +214 -0
- package/REALIGNMENT/11-phase-I-test-infra.md +385 -0
- package/REALIGNMENT/12-decisions-needed.md +196 -0
- package/REALIGNMENT/INDEX.md +82 -0
- package/REFACTORING_CAMPAIGN.md +277 -0
- package/RESTRUCTURE_PLAN.md +100 -0
- package/RUST_DEV.md +361 -0
- package/SECURITY.md +65 -0
- package/SETUP_AUTO_PUBLISH.md +164 -0
- package/TESTING-copilot-subscription.md +153 -0
- package/app/api/config/route.ts +22 -0
- package/app/api/export/route.ts +83 -0
- package/app/api/models/route.ts +12 -0
- package/app/api/stats/route.ts +46 -0
- package/app/dashboard/page.tsx +445 -0
- package/app/globals.css +35 -0
- package/app/installation/page.tsx +293 -0
- package/app/layout.tsx +35 -0
- package/app/master-design-system.css +2076 -0
- package/app/master-design-system.source.css +8 -0
- package/app/page.tsx +187 -0
- package/app/rechtliches/agb/page.tsx +165 -0
- package/app/rechtliches/datenschutz/page.tsx +128 -0
- package/app/rechtliches/impressum/page.tsx +122 -0
- package/app/rechtliches/widerruf/page.tsx +185 -0
- package/bin/xithead.js +264 -0
- package/codecov.yml +34 -0
- package/components/layout/AppShell.tsx +25 -0
- package/components/layout/Footer.tsx +120 -0
- package/components/layout/Header.tsx +145 -0
- package/components/marketing/LegalHighlights.tsx +45 -0
- package/components/marketing/LegalPageShell.tsx +49 -0
- package/components/marketing/LegalPanel.tsx +41 -0
- package/components/marketing/index.ts +3 -0
- package/crates/headroom-core/Cargo.toml +165 -0
- package/crates/headroom-core/benches/auth_mode.rs +74 -0
- package/crates/headroom-core/benches/ccr_store.rs +224 -0
- package/crates/headroom-core/benches/tokenizer.rs +52 -0
- package/crates/headroom-core/config/pipeline.toml +151 -0
- package/crates/headroom-core/proptest-regressions/transforms/tag_protector.txt +9 -0
- package/crates/headroom-core/src/auth_mode.rs +250 -0
- package/crates/headroom-core/src/cache_control.rs +414 -0
- package/crates/headroom-core/src/ccr/backends/in_memory.rs +317 -0
- package/crates/headroom-core/src/ccr/backends/mod.rs +152 -0
- package/crates/headroom-core/src/ccr/backends/redis.rs +146 -0
- package/crates/headroom-core/src/ccr/backends/sqlite.rs +205 -0
- package/crates/headroom-core/src/ccr/mod.rs +119 -0
- package/crates/headroom-core/src/compression_policy.rs +505 -0
- package/crates/headroom-core/src/lib.rs +33 -0
- package/crates/headroom-core/src/relevance/base.rs +139 -0
- package/crates/headroom-core/src/relevance/bm25.rs +385 -0
- package/crates/headroom-core/src/relevance/embedding.rs +354 -0
- package/crates/headroom-core/src/relevance/hybrid.rs +364 -0
- package/crates/headroom-core/src/relevance/mod.rs +64 -0
- package/crates/headroom-core/src/signals/keyword_detector.rs +433 -0
- package/crates/headroom-core/src/signals/line_importance.rs +84 -0
- package/crates/headroom-core/src/signals/mod.rs +61 -0
- package/crates/headroom-core/src/signals/tiered.rs +141 -0
- package/crates/headroom-core/src/tokenizer/estimator.rs +152 -0
- package/crates/headroom-core/src/tokenizer/hf_impl.rs +314 -0
- package/crates/headroom-core/src/tokenizer/mod.rs +56 -0
- package/crates/headroom-core/src/tokenizer/registry.rs +342 -0
- package/crates/headroom-core/src/tokenizer/tiktoken_impl.rs +265 -0
- package/crates/headroom-core/src/transforms/adaptive_sizer.rs +610 -0
- package/crates/headroom-core/src/transforms/anchor_selector.rs +1189 -0
- package/crates/headroom-core/src/transforms/content_detector.rs +769 -0
- package/crates/headroom-core/src/transforms/detection.rs +222 -0
- package/crates/headroom-core/src/transforms/diff_compressor.rs +1685 -0
- package/crates/headroom-core/src/transforms/live_zone.rs +2967 -0
- package/crates/headroom-core/src/transforms/log_compressor.rs +1295 -0
- package/crates/headroom-core/src/transforms/magika_detector.rs +395 -0
- package/crates/headroom-core/src/transforms/mod.rs +64 -0
- package/crates/headroom-core/src/transforms/pipeline/config.rs +331 -0
- package/crates/headroom-core/src/transforms/pipeline/mod.rs +103 -0
- package/crates/headroom-core/src/transforms/pipeline/offloads/diff_noise.rs +524 -0
- package/crates/headroom-core/src/transforms/pipeline/offloads/diff_offload.rs +279 -0
- package/crates/headroom-core/src/transforms/pipeline/offloads/json_offload.rs +400 -0
- package/crates/headroom-core/src/transforms/pipeline/offloads/log_offload.rs +284 -0
- package/crates/headroom-core/src/transforms/pipeline/offloads/mod.rs +34 -0
- package/crates/headroom-core/src/transforms/pipeline/offloads/search_offload.rs +331 -0
- package/crates/headroom-core/src/transforms/pipeline/orchestrator.rs +848 -0
- package/crates/headroom-core/src/transforms/pipeline/reformats/json_minifier.rs +175 -0
- package/crates/headroom-core/src/transforms/pipeline/reformats/log_template.rs +545 -0
- package/crates/headroom-core/src/transforms/pipeline/reformats/mod.rs +12 -0
- package/crates/headroom-core/src/transforms/pipeline/traits.rs +338 -0
- package/crates/headroom-core/src/transforms/recommendations.rs +329 -0
- package/crates/headroom-core/src/transforms/safety.rs +215 -0
- package/crates/headroom-core/src/transforms/search_compressor.rs +902 -0
- package/crates/headroom-core/src/transforms/smart_crusher/analyzer.rs +1262 -0
- package/crates/headroom-core/src/transforms/smart_crusher/anchors.rs +407 -0
- package/crates/headroom-core/src/transforms/smart_crusher/builder.rs +263 -0
- package/crates/headroom-core/src/transforms/smart_crusher/classifier.rs +214 -0
- package/crates/headroom-core/src/transforms/smart_crusher/compaction/classifier.rs +283 -0
- package/crates/headroom-core/src/transforms/smart_crusher/compaction/compactor.rs +733 -0
- package/crates/headroom-core/src/transforms/smart_crusher/compaction/formatter.rs +961 -0
- package/crates/headroom-core/src/transforms/smart_crusher/compaction/ir.rs +252 -0
- package/crates/headroom-core/src/transforms/smart_crusher/compaction/mod.rs +127 -0
- package/crates/headroom-core/src/transforms/smart_crusher/compaction/walker.rs +397 -0
- package/crates/headroom-core/src/transforms/smart_crusher/config.rs +173 -0
- package/crates/headroom-core/src/transforms/smart_crusher/constraints.rs +159 -0
- package/crates/headroom-core/src/transforms/smart_crusher/crusher.rs +1665 -0
- package/crates/headroom-core/src/transforms/smart_crusher/crushers.rs +865 -0
- package/crates/headroom-core/src/transforms/smart_crusher/error_keywords.rs +77 -0
- package/crates/headroom-core/src/transforms/smart_crusher/field_detect.rs +393 -0
- package/crates/headroom-core/src/transforms/smart_crusher/hashing.rs +72 -0
- package/crates/headroom-core/src/transforms/smart_crusher/mod.rs +81 -0
- package/crates/headroom-core/src/transforms/smart_crusher/observer.rs +66 -0
- package/crates/headroom-core/src/transforms/smart_crusher/orchestration.rs +459 -0
- package/crates/headroom-core/src/transforms/smart_crusher/outliers.rs +507 -0
- package/crates/headroom-core/src/transforms/smart_crusher/planning.rs +904 -0
- package/crates/headroom-core/src/transforms/smart_crusher/statistics.rs +510 -0
- package/crates/headroom-core/src/transforms/smart_crusher/stats_math.rs +287 -0
- package/crates/headroom-core/src/transforms/smart_crusher/traits.rs +203 -0
- package/crates/headroom-core/src/transforms/smart_crusher/types.rs +263 -0
- package/crates/headroom-core/src/transforms/tag_protector.rs +1272 -0
- package/crates/headroom-core/src/transforms/unidiff_detector.rs +232 -0
- package/crates/headroom-parity/Cargo.toml +26 -0
- package/crates/headroom-parity/examples/diff_fixture.rs +66 -0
- package/crates/headroom-parity/src/bin/parity_run.rs +78 -0
- package/crates/headroom-parity/src/lib.rs +613 -0
- package/crates/headroom-proxy/Cargo.toml +119 -0
- package/crates/headroom-proxy/data/model_prices_and_context_window.json +39767 -0
- package/crates/headroom-proxy/src/bedrock/auth_mode_layer.rs +192 -0
- package/crates/headroom-proxy/src/bedrock/envelope.rs +239 -0
- package/crates/headroom-proxy/src/bedrock/eventstream.rs +769 -0
- package/crates/headroom-proxy/src/bedrock/eventstream_to_sse.rs +459 -0
- package/crates/headroom-proxy/src/bedrock/invoke.rs +735 -0
- package/crates/headroom-proxy/src/bedrock/invoke_streaming.rs +1098 -0
- package/crates/headroom-proxy/src/bedrock/mod.rs +66 -0
- package/crates/headroom-proxy/src/bedrock/sigv4.rs +324 -0
- package/crates/headroom-proxy/src/bedrock/vendor.rs +82 -0
- package/crates/headroom-proxy/src/cache_stabilization/anthropic_cache_control.rs +698 -0
- package/crates/headroom-proxy/src/cache_stabilization/drift_detector.rs +683 -0
- package/crates/headroom-proxy/src/cache_stabilization/mod.rs +61 -0
- package/crates/headroom-proxy/src/cache_stabilization/openai_cache_key.rs +600 -0
- package/crates/headroom-proxy/src/cache_stabilization/tool_def_normalize.rs +514 -0
- package/crates/headroom-proxy/src/cache_stabilization/volatile_detector.rs +720 -0
- package/crates/headroom-proxy/src/compression/anthropic.rs +92 -0
- package/crates/headroom-proxy/src/compression/live_zone_anthropic.rs +1311 -0
- package/crates/headroom-proxy/src/compression/live_zone_openai.rs +660 -0
- package/crates/headroom-proxy/src/compression/live_zone_responses.rs +678 -0
- package/crates/headroom-proxy/src/compression/mod.rs +127 -0
- package/crates/headroom-proxy/src/compression/model_limits.rs +211 -0
- package/crates/headroom-proxy/src/config.rs +646 -0
- package/crates/headroom-proxy/src/error.rs +69 -0
- package/crates/headroom-proxy/src/handlers/chat_completions.rs +100 -0
- package/crates/headroom-proxy/src/handlers/conversations.rs +241 -0
- package/crates/headroom-proxy/src/handlers/mod.rs +13 -0
- package/crates/headroom-proxy/src/handlers/responses.rs +256 -0
- package/crates/headroom-proxy/src/headers.rs +288 -0
- package/crates/headroom-proxy/src/health.rs +41 -0
- package/crates/headroom-proxy/src/lib.rs +21 -0
- package/crates/headroom-proxy/src/main.rs +141 -0
- package/crates/headroom-proxy/src/observability/cache_hit_rate.rs +340 -0
- package/crates/headroom-proxy/src/observability/compression_ratio.rs +158 -0
- package/crates/headroom-proxy/src/observability/metric_names.rs +174 -0
- package/crates/headroom-proxy/src/observability/mod.rs +68 -0
- package/crates/headroom-proxy/src/observability/prometheus.rs +394 -0
- package/crates/headroom-proxy/src/observability/proxy_metrics.rs +368 -0
- package/crates/headroom-proxy/src/proxy.rs +1619 -0
- package/crates/headroom-proxy/src/responses_items.rs +565 -0
- package/crates/headroom-proxy/src/sse/anthropic.rs +415 -0
- package/crates/headroom-proxy/src/sse/framing.rs +366 -0
- package/crates/headroom-proxy/src/sse/mod.rs +40 -0
- package/crates/headroom-proxy/src/sse/openai_chat.rs +231 -0
- package/crates/headroom-proxy/src/sse/openai_responses.rs +458 -0
- package/crates/headroom-proxy/src/vertex/adc.rs +315 -0
- package/crates/headroom-proxy/src/vertex/envelope.rs +167 -0
- package/crates/headroom-proxy/src/vertex/mod.rs +277 -0
- package/crates/headroom-proxy/src/vertex/raw_predict.rs +490 -0
- package/crates/headroom-proxy/src/vertex/stream_raw_predict.rs +49 -0
- package/crates/headroom-proxy/src/websocket.rs +246 -0
- package/crates/headroom-py/Cargo.toml +37 -0
- package/crates/headroom-py/build.rs +77 -0
- package/crates/headroom-py/glibc_compat.c +170 -0
- package/crates/headroom-py/src/lib.rs +1655 -0
- package/deny.toml +32 -0
- package/design-system/base.css +127 -0
- package/design-system/components.css +1943 -0
- package/design-system/fonts.css +17 -0
- package/design-system/tailwind-preset.js +95 -0
- package/design-system/tokens.css +48 -0
- package/design-system/utilities.css +53 -0
- package/docker/differential-network-capture/Dockerfile.runner +14 -0
- package/docker/differential-network-capture/docker-compose.yml +142 -0
- package/docker/differential-network-capture/run-claude-lane.sh +24 -0
- package/docker/docker-compose.native.yml +44 -0
- package/docker-bake.hcl +88 -0
- package/docker-compose.yml +80 -0
- package/e2e/_lib/make_shim.ps1 +24 -0
- package/e2e/_lib/make_shim.sh +28 -0
- package/e2e/docker-native-install.sh +120 -0
- package/e2e/init/Dockerfile +79 -0
- package/e2e/wrap/Dockerfile +115 -0
- package/examples/07-context-compression.ipynb +279 -0
- package/examples/deployment/macos-launchagent/com.headroom.proxy.plist.template +65 -0
- package/examples/deployment/macos-launchagent/install.sh +227 -0
- package/examples/deployment/macos-launchagent/shell-integration.sh +74 -0
- package/examples/deployment/macos-launchagent/uninstall.sh +145 -0
- package/headroom-savings.png +0 -0
- package/headroom_learn.gif +0 -0
- package/lib/config/index.ts +12 -0
- package/lib/hooks/index.ts +4 -0
- package/lib/hooks/use-mounted.ts +13 -0
- package/lib/hooks/use-session.ts +34 -0
- package/lib/hooks/use-settings.ts +49 -0
- package/lib/utils/index.ts +1 -0
- package/lib/utils/settings.ts +162 -0
- package/lib/utils/utils.ts +6 -0
- package/llms.txt +67 -0
- package/middleware.ts +26 -0
- package/mkdocs.yml +136 -0
- package/next-env.d.ts +7 -0
- package/next.config.ts +12 -0
- package/npm/bin/xithead.js +366 -366
- package/npm/bin/xtream-head.js +366 -0
- package/npm/index.d.ts +57 -57
- package/npm/index.js +139 -139
- package/npm/package.json +55 -54
- package/npm/postinstall.js +43 -43
- package/package.json +58 -36
- package/plugins/headroom-agent-hooks/.claude-plugin/plugin.json +17 -0
- package/plugins/headroom-agent-hooks/hooks/hooks.json +29 -0
- package/plugins/headroom-oauth2/LICENSE +3 -0
- package/plugins/headroom-oauth2/SPEC.md +115 -0
- package/plugins/headroom-oauth2/pyproject.toml +48 -0
- package/plugins/hermes/headroom_retrieve/plugin.yaml +6 -0
- package/plugins/openclaw/hook-shim/HOOK.md +21 -0
- package/plugins/openclaw/hook-shim/handler.js +3 -0
- package/plugins/openclaw/openclaw.plugin.json +98 -0
- package/plugins/openclaw/package-lock.json +2692 -0
- package/plugins/openclaw/package.json +54 -0
- package/plugins/openclaw/prepare-dist.mjs +56 -0
- package/plugins/openclaw/src/convert.ts +418 -0
- package/plugins/openclaw/src/engine.ts +284 -0
- package/plugins/openclaw/src/gateway-config.ts +143 -0
- package/plugins/openclaw/src/index.ts +11 -0
- package/plugins/openclaw/src/plugin/index.ts +98 -0
- package/plugins/openclaw/src/proxy-manager.ts +477 -0
- package/plugins/openclaw/src/tools/headroom-retrieve.ts +76 -0
- package/plugins/openclaw/test/convert.test.ts +96 -0
- package/plugins/openclaw/test/engine-normalization.test.ts +21 -0
- package/plugins/openclaw/test/engine.test.ts +101 -0
- package/plugins/openclaw/test/gateway-config.test.ts +278 -0
- package/plugins/openclaw/test/plugin-runtime-routing.test.ts +141 -0
- package/plugins/openclaw/test/proxy-manager.test.ts +343 -0
- package/plugins/openclaw/tsup.config.ts +9 -0
- package/postcss.config.mjs +7 -0
- package/pyproject.toml +438 -0
- package/rust-toolchain.toml +16 -0
- package/sdk/typescript/examples/basic-compress.ts +64 -0
- package/sdk/typescript/examples/ccr-retrieve.ts +80 -0
- package/sdk/typescript/examples/hooks-custom-compression.ts +117 -0
- package/sdk/typescript/examples/middleware-composition.ts +59 -0
- package/sdk/typescript/examples/multi-provider.ts +53 -0
- package/sdk/typescript/examples/openai-anthropic-adapters.ts +73 -0
- package/sdk/typescript/examples/shared-context-multi-agent.ts +74 -0
- package/sdk/typescript/examples/simulation-dry-run.ts +80 -0
- package/sdk/typescript/examples/streaming-chat.ts +71 -0
- package/sdk/typescript/examples/structured-output.ts +99 -0
- package/sdk/typescript/examples/tool-calling-agent.ts +86 -0
- package/sdk/typescript/examples/with-headroom-vercel.ts +57 -0
- package/sdk/typescript/package-lock.json +3437 -0
- package/sdk/typescript/package.json +108 -0
- package/sdk/typescript/src/adapters/anthropic.ts +218 -0
- package/sdk/typescript/src/adapters/gemini.ts +83 -0
- package/sdk/typescript/src/adapters/openai.ts +77 -0
- package/sdk/typescript/src/adapters/vercel-ai.ts +131 -0
- package/sdk/typescript/src/client.ts +632 -0
- package/sdk/typescript/src/compress.ts +87 -0
- package/sdk/typescript/src/errors.ts +114 -0
- package/sdk/typescript/src/hooks.ts +113 -0
- package/sdk/typescript/src/index.ts +140 -0
- package/sdk/typescript/src/paths.ts +272 -0
- package/sdk/typescript/src/shared-context.ts +188 -0
- package/sdk/typescript/src/simulate.ts +52 -0
- package/sdk/typescript/src/types/config.ts +183 -0
- package/sdk/typescript/src/types/models.ts +314 -0
- package/sdk/typescript/src/types.ts +139 -0
- package/sdk/typescript/src/utils/case.ts +34 -0
- package/sdk/typescript/src/utils/format.ts +480 -0
- package/sdk/typescript/src/utils/stream.ts +50 -0
- package/sdk/typescript/test/adapters/anthropic.test.ts +217 -0
- package/sdk/typescript/test/adapters/gemini.test.ts +131 -0
- package/sdk/typescript/test/adapters/openai.test.ts +174 -0
- package/sdk/typescript/test/adapters/vercel-ai.test.ts +306 -0
- package/sdk/typescript/test/client-expanded.test.ts +333 -0
- package/sdk/typescript/test/client.test.ts +266 -0
- package/sdk/typescript/test/compress.test.ts +118 -0
- package/sdk/typescript/test/config.test.ts +275 -0
- package/sdk/typescript/test/errors.test.ts +169 -0
- package/sdk/typescript/test/format-integration.test.ts +252 -0
- package/sdk/typescript/test/hooks.test.ts +265 -0
- package/sdk/typescript/test/integration.test.ts +249 -0
- package/sdk/typescript/test/mdx-examples.test.ts +253 -0
- package/sdk/typescript/test/models.test.ts +318 -0
- package/sdk/typescript/test/parity.test.ts +337 -0
- package/sdk/typescript/test/paths.test.ts +447 -0
- package/sdk/typescript/test/shared-context.test.ts +245 -0
- package/sdk/typescript/test/simulate.test.ts +84 -0
- package/sdk/typescript/test/types.test.ts +244 -0
- package/sdk/typescript/test/utils/case.test.ts +129 -0
- package/sdk/typescript/test/utils/detect-format.test.ts +133 -0
- package/sdk/typescript/test/utils/format.test.ts +434 -0
- package/sdk/typescript/test/vercel-ai-e2e.test.ts +179 -0
- package/sdk/typescript/tsup.config.ts +17 -0
- package/tailwind.master.config.cjs +47 -0
- package/types/api.ts +12 -0
- package/types/config.ts +9 -0
- package/types/index.ts +2 -0
- package/uv.lock +6951 -0
- package/xithead.egg-info/PKG-INFO +22 -0
- package/xithead.egg-info/SOURCES.txt +16 -0
- package/xithead.egg-info/dependency_links.txt +1 -0
- package/xithead.egg-info/entry_points.txt +2 -0
- package/xithead.egg-info/requires.txt +10 -0
- package/xithead.egg-info/top_level.txt +2 -0
- package/xithead.ps1 +136 -0
- package/xithead.sh +129 -0
- package/xithead_dist/pyproject.toml +39 -0
- package/xithead_dist/xithead.egg-info/PKG-INFO +22 -0
- package/xithead_dist/xithead.egg-info/SOURCES.txt +16 -0
- package/xithead_dist/xithead.egg-info/dependency_links.txt +1 -0
- package/xithead_dist/xithead.egg-info/entry_points.txt +3 -0
- package/xithead_dist/xithead.egg-info/requires.txt +10 -0
- package/xithead_dist/xithead.egg-info/top_level.txt +2 -0
package/RUST_DEV.md
ADDED
|
@@ -0,0 +1,361 @@
|
|
|
1
|
+
# Headroom Rust Rewrite — Developer Guide
|
|
2
|
+
|
|
3
|
+
This document covers the Rust port of Headroom. It is the only new top-level
|
|
4
|
+
doc created in Phase 0; longer-form design/plan writeups live elsewhere and
|
|
5
|
+
are not versioned in this repo.
|
|
6
|
+
|
|
7
|
+
## Workspace layout
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
Cargo.toml # workspace root
|
|
11
|
+
rust-toolchain.toml # pins stable rustc with rustfmt+clippy
|
|
12
|
+
crates/
|
|
13
|
+
headroom-core/ # library: shared types + transform trait surface
|
|
14
|
+
headroom-proxy/ # binary: axum /healthz (Phase 2 grows this)
|
|
15
|
+
headroom-py/ # PyO3 cdylib exposing `headroom._core`
|
|
16
|
+
headroom-parity/ # lib + `parity-run` CLI for Python parity tests
|
|
17
|
+
tests/parity/
|
|
18
|
+
fixtures/<transform>/*.json # recorded Python outputs (Phase 1 ports match)
|
|
19
|
+
recorder.py # Python-side fixture recorder
|
|
20
|
+
scripts/record_fixtures.py # entry point for running the recorder
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
`cargo build --workspace` builds every crate. `default-members` drops
|
|
24
|
+
`headroom-py` from `cargo run`/bare-`cargo test` flows so that `cargo test
|
|
25
|
+
--workspace` does not try to execute the PyO3 cdylib standalone (it can't
|
|
26
|
+
find `libpython` without a Python interpreter hosting it).
|
|
27
|
+
|
|
28
|
+
## Common commands
|
|
29
|
+
|
|
30
|
+
`just` is not installed on dev boxes here; a `Makefile` at the repo root
|
|
31
|
+
exposes the same targets:
|
|
32
|
+
|
|
33
|
+
| Target | What it does |
|
|
34
|
+
| --- | --- |
|
|
35
|
+
| `make test` | `cargo test --workspace` |
|
|
36
|
+
| `make test-parity` | Builds `headroom-py` via maturin, runs `parity-run run` |
|
|
37
|
+
| `make bench` | `cargo bench --workspace` |
|
|
38
|
+
| `make build-proxy` | Release-builds `headroom-proxy`, strips, prints size |
|
|
39
|
+
| `make build-wheel` | `maturin build --release -m crates/headroom-py/pyproject.toml` |
|
|
40
|
+
| `make fmt` | `cargo fmt --all` |
|
|
41
|
+
| `make lint` | `cargo fmt --check` + `cargo clippy --workspace -- -D warnings` |
|
|
42
|
+
|
|
43
|
+
## Running the proxy
|
|
44
|
+
|
|
45
|
+
`headroom-proxy` is a transparent reverse proxy. Phase 1 forwards HTTP/1.1,
|
|
46
|
+
HTTP/2, SSE, and WebSocket traffic verbatim to a configured upstream — no
|
|
47
|
+
provider logic yet. The intent is that operators run the existing Python
|
|
48
|
+
proxy on a private port and put `headroom-proxy` on the public port pointed
|
|
49
|
+
at it; end users notice nothing.
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
# Build
|
|
53
|
+
make build-proxy
|
|
54
|
+
./target/release/headroom-proxy --help
|
|
55
|
+
|
|
56
|
+
# Run against a local upstream
|
|
57
|
+
./target/release/headroom-proxy \
|
|
58
|
+
--listen 0.0.0.0:8787 \
|
|
59
|
+
--upstream http://127.0.0.1:8788
|
|
60
|
+
|
|
61
|
+
# Health checks
|
|
62
|
+
curl -s http://127.0.0.1:8787/healthz # => {"ok":true,...}
|
|
63
|
+
curl -s http://127.0.0.1:8787/healthz/upstream # => 200 if upstream reachable
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
### Operator runbook (Phase 1 cutover)
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
# 1. Move the Python proxy to a private port (e.g. 8788)
|
|
70
|
+
HEADROOM_HOST=127.0.0.1 HEADROOM_PORT=8788 python -m headroom.proxy & # or your existing launcher
|
|
71
|
+
|
|
72
|
+
# 2. Run the Rust proxy on the previously-public port (8787) pointing at it
|
|
73
|
+
./target/release/headroom-proxy --listen 0.0.0.0:8787 --upstream http://127.0.0.1:8788 &
|
|
74
|
+
|
|
75
|
+
# 3. End users keep hitting :8787 unchanged.
|
|
76
|
+
# 4. Confirm passthrough:
|
|
77
|
+
curl -si http://127.0.0.1:8787/v1/models
|
|
78
|
+
# 5. Rollback = stop the Rust proxy and rebind Python back to 8787.
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### Configuration flags
|
|
82
|
+
|
|
83
|
+
| Flag | Env var | Default | Notes |
|
|
84
|
+
| --- | --- | --- | --- |
|
|
85
|
+
| `--listen` | `HEADROOM_PROXY_LISTEN` | `0.0.0.0:8787` | bind address |
|
|
86
|
+
| `--upstream` | `HEADROOM_PROXY_UPSTREAM` | (required) | base URL the proxy forwards to |
|
|
87
|
+
| `--upstream-timeout` | | `600s` | end-to-end request timeout (long for streams) |
|
|
88
|
+
| `--upstream-connect-timeout` | | `10s` | TCP/TLS connect timeout |
|
|
89
|
+
| `--max-body-bytes` | | `100MB` | for buffered cases; streams bypass |
|
|
90
|
+
| `--log-level` | | `info` | `RUST_LOG`-style filter |
|
|
91
|
+
| `--rewrite-host` / `--no-rewrite-host` | | rewrite | rewrite Host to upstream (default) |
|
|
92
|
+
| `--graceful-shutdown-timeout` | | `30s` | wait for in-flight on SIGTERM/SIGINT |
|
|
93
|
+
|
|
94
|
+
### Picking the next port: invocation telemetry
|
|
95
|
+
|
|
96
|
+
Before porting another Python compressor to Rust, check what's actually
|
|
97
|
+
running. The Python proxy already exposes per-transform telemetry on
|
|
98
|
+
`/stats` (`headroom.proxy.prometheus_metrics`):
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
# Top compressors by invocation count (last process lifetime)
|
|
102
|
+
curl -s http://127.0.0.1:8788/stats | jq '.compressions_by_strategy'
|
|
103
|
+
# {
|
|
104
|
+
# "intelligent_context": 12453,
|
|
105
|
+
# "smart_crusher": 487,
|
|
106
|
+
# "search": 312,
|
|
107
|
+
# "diff": 28,
|
|
108
|
+
# "code": 0, # ← never fires; safe to defer porting
|
|
109
|
+
# ...
|
|
110
|
+
# }
|
|
111
|
+
|
|
112
|
+
# Per-transform timing (avg/max/count by transform name)
|
|
113
|
+
curl -s http://127.0.0.1:8788/stats | jq '.pipeline_timing'
|
|
114
|
+
|
|
115
|
+
# Token savings attributable to each strategy
|
|
116
|
+
curl -s http://127.0.0.1:8788/stats | jq '.tokens_saved_by_strategy'
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
This is the data the audit-cleanup PR (2026-04-30) recommended for
|
|
120
|
+
prioritizing the next Python → Rust port. Strategies with zero or
|
|
121
|
+
near-zero invocations are deferral candidates; strategies on the hot
|
|
122
|
+
path are porting candidates regardless of LOC count.
|
|
123
|
+
|
|
124
|
+
### Reserved paths
|
|
125
|
+
|
|
126
|
+
`/healthz` and `/healthz/upstream` are intercepted by the Rust proxy and
|
|
127
|
+
**not** forwarded. Operators must not name a real upstream route either of
|
|
128
|
+
these. Everything else is a catch-all forward.
|
|
129
|
+
|
|
130
|
+
## Maturin + Python wiring
|
|
131
|
+
|
|
132
|
+
`headroom-py` is a PyO3 cdylib that exposes `headroom._core` in Python. The
|
|
133
|
+
`extension-module` feature is opt-in so plain `cargo build --workspace` does
|
|
134
|
+
not try to link against `libpython` on systems that don't have it.
|
|
135
|
+
|
|
136
|
+
### First-time setup (clean venv recommended)
|
|
137
|
+
|
|
138
|
+
```bash
|
|
139
|
+
python3.11 -m venv /tmp/hr-rust-venv
|
|
140
|
+
source /tmp/hr-rust-venv/bin/activate
|
|
141
|
+
pip install maturin
|
|
142
|
+
cd crates/headroom-py
|
|
143
|
+
maturin develop # editable dev build, installs headroom._core
|
|
144
|
+
cd /tmp # IMPORTANT: step out of the repo root first
|
|
145
|
+
python -c "from headroom._core import hello; print(hello())"
|
|
146
|
+
# => headroom-core
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
> Why `cd /tmp`? The repo root also contains the Python `headroom/` package.
|
|
150
|
+
> Running the smoke import from the repo root makes Python resolve `headroom`
|
|
151
|
+
> to `./headroom/__init__.py` (the full SDK, which pulls in heavy deps) instead
|
|
152
|
+
> of the lightweight namespace package installed by maturin. Tests should
|
|
153
|
+
> either run outside the repo root, or ensure `headroom` is installed into
|
|
154
|
+
> the same venv (then the maturin-installed `_core.so` lands alongside it and
|
|
155
|
+
> both imports resolve).
|
|
156
|
+
|
|
157
|
+
### Release wheels
|
|
158
|
+
|
|
159
|
+
```bash
|
|
160
|
+
make build-wheel
|
|
161
|
+
# wheels land under target/wheels/
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
CI (`.github/workflows/rust.yml`) builds linux-x86_64, macos-arm64, and
|
|
165
|
+
macos-x86_64 wheels via `PyO3/maturin-action` and uploads them as artifacts.
|
|
166
|
+
|
|
167
|
+
## Parity harness
|
|
168
|
+
|
|
169
|
+
`crates/headroom-parity` owns the Rust-vs-Python oracle:
|
|
170
|
+
|
|
171
|
+
- JSON fixtures under `tests/parity/fixtures/<transform>/` (schema:
|
|
172
|
+
`{ transform, input, config, output, recorded_at, input_sha256 }`).
|
|
173
|
+
- `TransformComparator` trait — one impl per transform. Phase 0 stubs return
|
|
174
|
+
`Err(...)`; the harness flags those as `Skipped`, not panics.
|
|
175
|
+
- `parity-run` CLI: `cargo run -p headroom-parity -- run [--only TRANSFORM]`.
|
|
176
|
+
- Unit tests in `crates/headroom-parity/src/lib.rs` include a **negative
|
|
177
|
+
test** (`harness_reports_diff_for_divergent_comparator`) proving the
|
|
178
|
+
harness detects mismatched output before any real port lands.
|
|
179
|
+
|
|
180
|
+
### Recording fresh fixtures
|
|
181
|
+
|
|
182
|
+
```bash
|
|
183
|
+
source .venv/bin/activate # the main Python SDK venv
|
|
184
|
+
python scripts/record_fixtures.py # uses tests/parity/recorder.py
|
|
185
|
+
ls tests/parity/fixtures/*/ | sort | uniq -c
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
The recorder monkey-patches the in-process transform classes (see
|
|
189
|
+
`record_all()` in `tests/parity/recorder.py`). It does **not** modify any
|
|
190
|
+
file under `headroom/`.
|
|
191
|
+
|
|
192
|
+
## Known regressions in retired-Python components
|
|
193
|
+
|
|
194
|
+
The Stage 3b/3c.1b retirements deleted Python source for `DiffCompressor`
|
|
195
|
+
and `SmartCrusher` and replaced them with PyO3-delegating shims. The
|
|
196
|
+
2026-04-28 audit found that the retirements shipped with subsystems
|
|
197
|
+
silently disconnected. This section tracks each gap and its disposition
|
|
198
|
+
so they don't regress further or get forgotten.
|
|
199
|
+
|
|
200
|
+
### SmartCrusher
|
|
201
|
+
|
|
202
|
+
| Subsystem | State | Tracked by |
|
|
203
|
+
|---|---|---|
|
|
204
|
+
| TOIN learning loop | **Re-attached 2026-04-28.** Shim's `crush()` and `_smart_crush_content()` now call `toin.record_compression()` after a real compression. Filtered on `strategy != "passthrough"` to ignore JSON re-canonicalization. Best-effort: TOIN failures are logged at debug level and don't break compression. | `tests/test_smart_crusher_toin_attachment.py` |
|
|
205
|
+
| CCR marker emission knob | **Honored end-to-end 2026-04-29.** New `enable_ccr_marker: bool` field on Rust `SmartCrusherConfig`; `crush_array` checks it before emitting the `<<ccr:HASH>>` marker text and the CCR store write. Python shim flips it from `ccr_config.enabled and ccr_config.inject_retrieval_marker` — both flags collapse to the same Rust gate, since storing payloads under either off-switch makes no sense. Scope: gates only the row-drop sentinel path; Stage-3c.2 opaque-string CCR substitutions still emit always (no Python equivalent, no production caller asks for suppression). | `tests/test_smart_crusher_toin_attachment.py` + `crates/headroom-core/.../crusher.rs::tests::enable_ccr_marker_*` |
|
|
206
|
+
| Custom relevance scorer | **Closed (fail-loud) 2026-04-29.** `relevance_config` and `scorer` constructor args remain in the signature for source compat, but the shim raises `NotImplementedError` when either is non-None — silently dropping a user-supplied scorer is a textbook silent-fallback bug. Full plumbing waits on Stage-3c.2's relevance-crate Python bridge. | `tests/test_smart_crusher_toin_attachment.py::test_custom_*_arg_raises_not_implemented` |
|
|
207
|
+
| Per-tool TOIN learning hook | **Re-attached partially.** `_smart_crush_content` accepts `tool_name` and now threads it into the TOIN record. The hook is best-effort — it improves `query_context` aggregation but doesn't drive per-tool overrides yet. | `tests/test_smart_crusher_toin_attachment.py::test_smart_crush_content_records_to_toin` |
|
|
208
|
+
|
|
209
|
+
### DiffCompressor
|
|
210
|
+
|
|
211
|
+
| Subsystem | State |
|
|
212
|
+
|---|---|
|
|
213
|
+
| Adaptive context windows | Honored byte-for-byte (parity fixture-locked). |
|
|
214
|
+
| TOIN integration | Never had one — DiffCompressor records via `_record_to_toin` in ContentRouter, which already runs for non-SmartCrusher strategies. No regression. |
|
|
215
|
+
|
|
216
|
+
### Phase 3e.1 — `signals/` trait module + KeywordDetector (2026-04-29)
|
|
217
|
+
|
|
218
|
+
The Python `error_detection.py` regex registry was retired and reborn as a
|
|
219
|
+
trait + tier system in `crates/headroom-core/src/signals/`. See
|
|
220
|
+
`signals/README.md` for the full architecture; the highlights:
|
|
221
|
+
|
|
222
|
+
- **Per-granularity traits.** `LineImportanceDetector` ships today; future
|
|
223
|
+
`ContentTypeDetector` and `ItemImportanceDetector<I>` will follow as their
|
|
224
|
+
consumers get touched.
|
|
225
|
+
- **`Tiered<T>` combinator.** Composition, not inheritance. Future ML
|
|
226
|
+
detectors slot in as new tiers without changes to `KeywordDetector` or
|
|
227
|
+
any caller.
|
|
228
|
+
- **One concrete impl.** `KeywordDetector` (aho-corasick) is the only tier
|
|
229
|
+
registered today. **No NoOp/stub impls** — per project no-silent-fallbacks
|
|
230
|
+
rule, future tiers land with their real implementations.
|
|
231
|
+
- **Bug fixes baked in.** `ERROR_KEYWORDS` regex now includes
|
|
232
|
+
`timeout|abort|denied|rejected` (previously drifted from the keyword set);
|
|
233
|
+
`token` dropped from `SECURITY_KEYWORDS` (false-positived on every LLM
|
|
234
|
+
metric reference). Both fixed in the Python regex too via the shim that
|
|
235
|
+
recompiles patterns from the Rust-exposed keyword tables.
|
|
236
|
+
- **Companion canonical extension path.** `signals/README.md` documents
|
|
237
|
+
the BGE classifier head — a 384-dim → 4-class softmax on top of the
|
|
238
|
+
already-loaded `bge-small-en-v1.5` embedder — as the natural ML tier.
|
|
239
|
+
Two alternatives kept open: distilled tinyBERT in ONNX, logistic
|
|
240
|
+
regression on lexical features.
|
|
241
|
+
|
|
242
|
+
### Phase 3g (queued) — Compression Pipeline Formalization (issue #315)
|
|
243
|
+
|
|
244
|
+
Strategic decision 2026-04-29: after Phase 3e (compressor ports) and
|
|
245
|
+
Phase 3f (Rust MCP scaffold) wrap, formalize the lossless-then-lossy-
|
|
246
|
+
then-CCR ordering as a cross-cutting `CompressionPipeline` orchestrator
|
|
247
|
+
+ `LosslessTransform` / `LossyTransform` traits in
|
|
248
|
+
`crates/headroom-core/src/pipeline/`. Existing compressors get
|
|
249
|
+
refactored as compositions of pluggable transforms. The crucial design
|
|
250
|
+
choice — **parsers for structure, models at the prose/structure
|
|
251
|
+
boundary** — is captured in issue #315 and
|
|
252
|
+
`memory/project_lossless_first_pipeline.md`. Do NOT start coding before
|
|
253
|
+
3e/3f finish.
|
|
254
|
+
|
|
255
|
+
### Watch list (potential regressions, not yet audited)
|
|
256
|
+
|
|
257
|
+
- `CCRConfig.enabled=False` end-to-end — **closed 2026-04-29**. Both `enabled=False` and `inject_retrieval_marker=False` collapse to the same Rust `enable_ccr_marker=False` gate (no marker, no store write). See the SmartCrusher table above.
|
|
258
|
+
- `SmartCrusherConfig.use_feedback_hints=False` — config field is forwarded to Rust but its honoring inside the Rust crusher hasn't been verified against a parity fixture for the disabled path.
|
|
259
|
+
|
|
260
|
+
When any item above changes, update both this section and the test file. The shim's docstring also references this section — keep them aligned.
|
|
261
|
+
|
|
262
|
+
## Phase 0 Blockers
|
|
263
|
+
|
|
264
|
+
These are known limitations for Phase 0. They are tracked here so Phase 1
|
|
265
|
+
doesn't rediscover them.
|
|
266
|
+
|
|
267
|
+
- **`cache_aligner` fixtures**: `CacheAligner.apply()` takes
|
|
268
|
+
`(messages, tokenizer, **kwargs)` — a `Tokenizer` is provider-specific and
|
|
269
|
+
its cheapest `NoopTokenCounter` / `TiktokenTokenCounter` construction still
|
|
270
|
+
requires pulling `headroom.providers.*` which imports the full observability
|
|
271
|
+
stack (opentelemetry, etc). The recorder records `cache_aligner` only if a
|
|
272
|
+
usable tokenizer is cheaply available; otherwise it logs a blocker and
|
|
273
|
+
skips. See `recorder.py::_build_cache_aligner_tokenizer`.
|
|
274
|
+
- **`ccr` is not a single class**: The repo has `CCRToolInjector`,
|
|
275
|
+
`CCRResponseHandler`, `CCRToolCall`, `CCRToolResult` etc. rather than a
|
|
276
|
+
single `CCR` class. The recorder targets the encoder-style entry point
|
|
277
|
+
most analogous to the Rust port (`CCRToolInjector.inject_tool` and
|
|
278
|
+
`CCRResponseHandler.parse_response`). If Phase 1 wants a different split
|
|
279
|
+
it should update `recorder.py::record_all` accordingly.
|
|
280
|
+
- **Pre-commit hook noise**: `scripts/sync-plugin-versions.py` mutates
|
|
281
|
+
`.claude-plugin/marketplace.json`, `.github/plugin/marketplace.json`, and
|
|
282
|
+
`plugins/headroom-agent-hooks/**/plugin.json` on every commit. Those
|
|
283
|
+
changes are harmless but each commit in Phase 0 picks them up. Phase 1
|
|
284
|
+
does not need to do anything special — just let the hook run.
|
|
285
|
+
- **`rust-toolchain.toml`** pins `channel = "stable"` rather than a specific
|
|
286
|
+
version so CI picks up the same toolchain the local box uses. Tighten to a
|
|
287
|
+
pinned version (e.g. `1.78`) once the port stabilizes.
|
|
288
|
+
|
|
289
|
+
## Multi-worker deployment — CCR fragmentation
|
|
290
|
+
|
|
291
|
+
**Status:** PR-B7 (`REALIGNMENT/04-phase-B-live-zone.md`) introduced two
|
|
292
|
+
persistent CCR backends. The single-`--workers` recommendation no longer
|
|
293
|
+
applies once you select a persistent backend.
|
|
294
|
+
|
|
295
|
+
### Backend selection
|
|
296
|
+
|
|
297
|
+
`crates/headroom-core/src/ccr/backends/` ships three implementations of
|
|
298
|
+
the `CcrStore` trait:
|
|
299
|
+
|
|
300
|
+
| Backend | When to use | Persistence | Multi-worker safe |
|
|
301
|
+
| ---------------------- | ------------------------------------------- | ----------- | -------------------------- |
|
|
302
|
+
| `InMemoryCcrStore` | Tests, single-worker prototyping | No | No |
|
|
303
|
+
| `SqliteCcrStore` (default) | Single-instance prod / single-host fleet | Yes (file) | Yes (sticky session) |
|
|
304
|
+
| `RedisCcrStore` (opt-in) | Multi-host / horizontally-scaled prod | Yes (Redis) | Yes (no stickiness needed) |
|
|
305
|
+
|
|
306
|
+
`backends::from_config` picks one at startup from the operator's
|
|
307
|
+
`CcrBackendConfig`. **Init failures surface to the caller**
|
|
308
|
+
(`feedback_no_silent_fallbacks.md`) — a misconfigured DB path or
|
|
309
|
+
unreachable Redis URL aborts startup rather than silently degrading to
|
|
310
|
+
in-memory.
|
|
311
|
+
|
|
312
|
+
### When does what work?
|
|
313
|
+
|
|
314
|
+
- **`SqliteCcrStore`** is the default for new deploys. The DB file lives
|
|
315
|
+
on the local disk; multiple workers on the **same host** share it via
|
|
316
|
+
SQLite's WAL-mode locking, so `--workers N` works as long as a sticky
|
|
317
|
+
load balancer routes each session to the same host. Survives proxy
|
|
318
|
+
restarts: a new worker that opens the same DB file recovers every
|
|
319
|
+
in-flight `<<ccr:HASH>>` marker.
|
|
320
|
+
- **`RedisCcrStore`** (cfg-gated behind the `redis` feature) is the
|
|
321
|
+
drop-in for **horizontally-scaled** deployments. Every worker on
|
|
322
|
+
every host hits the same Redis instance; no sticky session is
|
|
323
|
+
required at any layer of the LB. Enable with `--features redis` in
|
|
324
|
+
the proxy crate's Cargo build.
|
|
325
|
+
- **`InMemoryCcrStore`** is fine for tests and single-worker
|
|
326
|
+
development. Production deployments using it lose every
|
|
327
|
+
`<<ccr:HASH>>` marker on restart and fragment across workers — keep
|
|
328
|
+
it confined to local boxes.
|
|
329
|
+
|
|
330
|
+
### What goes wrong with the in-memory backend on `--workers N > 1`
|
|
331
|
+
|
|
332
|
+
Each uvicorn worker is a separate Python process. The following state is
|
|
333
|
+
fragmented across workers:
|
|
334
|
+
|
|
335
|
+
1. **Python `CompressionStore`** — defaults to `InMemoryBackend` (per-process)
|
|
336
|
+
when `HEADROOM_CCR_BACKEND` is unset. Each worker has its own singleton; CCR
|
|
337
|
+
markers written on worker A are invisible to worker B. Set
|
|
338
|
+
`HEADROOM_CCR_BACKEND=sqlite` to use a shared cross-worker store.
|
|
339
|
+
2. **`HeadroomProxy._compression_caches`** (`headroom/proxy/server.py`)
|
|
340
|
+
— per-session `CompressionCache` dict (instance var, always per-worker).
|
|
341
|
+
3. **`HeadroomProxy.session_tracker_store`** — per-session prefix-tracker
|
|
342
|
+
state derived from Anthropic's `cache_read_input_tokens` responses
|
|
343
|
+
(instance var, always per-worker).
|
|
344
|
+
4. **TOIN learner state** — writes snapshots to `~/.headroom/toin.json` but
|
|
345
|
+
keeps per-process in-memory state; pattern statistics on one worker are not
|
|
346
|
+
visible to others until the next disk flush.
|
|
347
|
+
|
|
348
|
+
When uvicorn round-robins requests across workers, a session whose
|
|
349
|
+
turn-1 landed on worker A may have turn-2 land on worker B. Worker B has
|
|
350
|
+
zero knowledge of what worker A did, the `<<ccr:HASH>>` marker resolves
|
|
351
|
+
to `None`, and the model sees an opaque directive it can't act on.
|
|
352
|
+
Switching to `SqliteCcrStore` (default) or `RedisCcrStore` resolves the
|
|
353
|
+
CCR fragmentation; a sticky-session load balancer resolves all of them.
|
|
354
|
+
|
|
355
|
+
### Detecting it in the wild
|
|
356
|
+
|
|
357
|
+
The proxy emits a `WARNING`-level log line on startup when `--workers N > 1`.
|
|
358
|
+
When `HEADROOM_CCR_BACKEND` is unset (default InMemoryBackend), the warning
|
|
359
|
+
includes CCR retrieval failures and suggests setting `HEADROOM_CCR_BACKEND=sqlite`.
|
|
360
|
+
When a cross-worker backend is already configured, the warning covers only the
|
|
361
|
+
remaining per-worker stores (compression cache, prefix tracker, TOIN, CostTracker).
|
package/SECURITY.md
ADDED
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
# Security Policy
|
|
2
|
+
|
|
3
|
+
## Supported Versions
|
|
4
|
+
|
|
5
|
+
| Version | Supported |
|
|
6
|
+
| ------- | ------------------ |
|
|
7
|
+
| 0.2.x | :white_check_mark: |
|
|
8
|
+
| 0.1.x | :x: |
|
|
9
|
+
|
|
10
|
+
## Reporting a Vulnerability
|
|
11
|
+
|
|
12
|
+
We take security vulnerabilities seriously. If you discover a security issue, please report it responsibly.
|
|
13
|
+
|
|
14
|
+
### How to Report
|
|
15
|
+
|
|
16
|
+
**Please DO NOT open a public GitHub issue for security vulnerabilities.**
|
|
17
|
+
|
|
18
|
+
Instead, please email us at: **security@headroom.dev**
|
|
19
|
+
|
|
20
|
+
Include the following information:
|
|
21
|
+
- Type of vulnerability (e.g., injection, data exposure, authentication bypass)
|
|
22
|
+
- Full path of the affected source file(s)
|
|
23
|
+
- Step-by-step instructions to reproduce the issue
|
|
24
|
+
- Proof-of-concept or exploit code (if possible)
|
|
25
|
+
- Impact assessment
|
|
26
|
+
|
|
27
|
+
### What to Expect
|
|
28
|
+
|
|
29
|
+
1. **Acknowledgment**: We will acknowledge receipt within 48 hours
|
|
30
|
+
2. **Assessment**: We will assess the vulnerability and determine its severity
|
|
31
|
+
3. **Updates**: We will keep you informed of our progress
|
|
32
|
+
4. **Resolution**: We aim to resolve critical issues within 7 days
|
|
33
|
+
5. **Credit**: With your permission, we will credit you in the security advisory
|
|
34
|
+
|
|
35
|
+
### Security Best Practices for Users
|
|
36
|
+
|
|
37
|
+
When using Headroom:
|
|
38
|
+
|
|
39
|
+
1. **API Keys**: Never commit API keys. Use environment variables.
|
|
40
|
+
2. **Proxy Exposure**: Don't expose the proxy server to the public internet without authentication
|
|
41
|
+
3. **Log Files**: Be aware that request logs may contain sensitive information
|
|
42
|
+
4. **Budget Limits**: Set budget limits to prevent unexpected costs
|
|
43
|
+
|
|
44
|
+
### Scope
|
|
45
|
+
|
|
46
|
+
The following are in scope for security reports:
|
|
47
|
+
- Headroom Python package (`pip install xtream-head`)
|
|
48
|
+
- Xtream Head proxy server
|
|
49
|
+
- Official integrations (LangChain, MCP)
|
|
50
|
+
|
|
51
|
+
The following are out of scope:
|
|
52
|
+
- Third-party integrations not maintained by us
|
|
53
|
+
- Issues in dependencies (report these to the upstream project)
|
|
54
|
+
- Social engineering attacks
|
|
55
|
+
|
|
56
|
+
## Security Features
|
|
57
|
+
|
|
58
|
+
Headroom includes several security features:
|
|
59
|
+
|
|
60
|
+
- **No credential storage**: We never store or log API keys
|
|
61
|
+
- **Passthrough mode**: Sensitive content passes through unchanged by default
|
|
62
|
+
- **Input validation**: All inputs are validated before processing
|
|
63
|
+
- **Safe defaults**: Security-conscious defaults out of the box
|
|
64
|
+
|
|
65
|
+
Thank you for helping keep Headroom and its users safe!
|
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
# Automatic Publishing Setup
|
|
2
|
+
|
|
3
|
+
This project uses GitHub Actions to automatically publish to npm when the version in `package.json` changes.
|
|
4
|
+
|
|
5
|
+
## 🔐 Setup Instructions
|
|
6
|
+
|
|
7
|
+
### 1. Get npm Token
|
|
8
|
+
|
|
9
|
+
1. Go to https://www.npmjs.com
|
|
10
|
+
2. Click your profile → "Access Tokens"
|
|
11
|
+
3. Create new token (type: "Automation")
|
|
12
|
+
4. Copy the token
|
|
13
|
+
|
|
14
|
+
### 2. Add GitHub Secret
|
|
15
|
+
|
|
16
|
+
1. Go to GitHub repo → Settings → Secrets and variables → Actions
|
|
17
|
+
2. Click "New repository secret"
|
|
18
|
+
3. **Name**: `NPM_TOKEN`
|
|
19
|
+
4. **Value**: Paste the npm token
|
|
20
|
+
5. Click "Add secret"
|
|
21
|
+
|
|
22
|
+
## 🚀 How It Works
|
|
23
|
+
|
|
24
|
+
```
|
|
25
|
+
┌─────────────────────────────────────────┐
|
|
26
|
+
│ Edit package.json version │
|
|
27
|
+
│ git push to main │
|
|
28
|
+
└──────────────┬──────────────────────────┘
|
|
29
|
+
│
|
|
30
|
+
▼
|
|
31
|
+
┌─────────────────────────────────────────┐
|
|
32
|
+
│ GitHub Actions triggers (on version) │
|
|
33
|
+
│ ✓ Installs dependencies │
|
|
34
|
+
│ ✓ Builds project │
|
|
35
|
+
│ ✓ Publishes to npm │
|
|
36
|
+
│ ✓ Creates Git tag (v1.5.0) │
|
|
37
|
+
│ ✓ Creates GitHub Release │
|
|
38
|
+
└─────────────────────────────────────────┘
|
|
39
|
+
│
|
|
40
|
+
▼
|
|
41
|
+
┌─────────────────────────────────────────┐
|
|
42
|
+
│ npm Published! 🎉 │
|
|
43
|
+
│ Users can: npm install -g xithead │
|
|
44
|
+
└─────────────────────────────────────────┘
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## 📝 Publishing Steps
|
|
48
|
+
|
|
49
|
+
When you want to release a new version:
|
|
50
|
+
|
|
51
|
+
### 1. Update Version
|
|
52
|
+
```bash
|
|
53
|
+
# Automatic semantic versioning
|
|
54
|
+
npm version patch # 1.5.0 → 1.5.1
|
|
55
|
+
npm version minor # 1.5.0 → 1.6.0
|
|
56
|
+
npm version major # 1.5.0 → 2.0.0
|
|
57
|
+
|
|
58
|
+
# This automatically commits and creates a git tag
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
### 2. Push to main
|
|
62
|
+
```bash
|
|
63
|
+
git push origin main
|
|
64
|
+
git push origin v1.5.0 # Push the tag
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
### 3. Automatic Actions ✨
|
|
68
|
+
- ✅ GitHub Actions detects version change
|
|
69
|
+
- ✅ Builds the project
|
|
70
|
+
- ✅ Publishes to npm registry
|
|
71
|
+
- ✅ Creates GitHub Release
|
|
72
|
+
- ✅ Sends notification to Discord (optional, can be added)
|
|
73
|
+
|
|
74
|
+
## 🔄 Alternative: Manual version bump
|
|
75
|
+
|
|
76
|
+
If you just edit `package.json` directly:
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
# Edit package.json manually
|
|
80
|
+
vi package.json # Change "version": "1.5.0" → "1.6.0"
|
|
81
|
+
|
|
82
|
+
# Commit and push
|
|
83
|
+
git add package.json
|
|
84
|
+
git commit -m "chore: bump version to 1.6.0"
|
|
85
|
+
git push origin main
|
|
86
|
+
|
|
87
|
+
# GitHub Actions will automatically publish!
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
## 📊 Status & Logs
|
|
91
|
+
|
|
92
|
+
Monitor the publishing process:
|
|
93
|
+
|
|
94
|
+
1. Go to GitHub repo → "Actions"
|
|
95
|
+
2. Find the workflow run matching your commit
|
|
96
|
+
3. Click to see detailed logs
|
|
97
|
+
4. Check if npm publish was successful
|
|
98
|
+
|
|
99
|
+
## 🐛 Troubleshooting
|
|
100
|
+
|
|
101
|
+
### "NPM_TOKEN not found"
|
|
102
|
+
- Check that secret is added to GitHub
|
|
103
|
+
- Make sure name is exactly `NPM_TOKEN`
|
|
104
|
+
- Secret must be in the same repository
|
|
105
|
+
|
|
106
|
+
### "Version already published"
|
|
107
|
+
- Workflow checks if version exists on npm
|
|
108
|
+
- To re-publish: delete version on npm or bump version number
|
|
109
|
+
- New version = automatic publish
|
|
110
|
+
|
|
111
|
+
### Build fails
|
|
112
|
+
- Check logs in GitHub Actions
|
|
113
|
+
- Run `npm run build` locally to debug
|
|
114
|
+
- Fix issues and push again
|
|
115
|
+
|
|
116
|
+
## 📦 Verify Publication
|
|
117
|
+
|
|
118
|
+
After publishing, verify on npm:
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
# Check if version is published
|
|
122
|
+
npm view xithead@1.6.0
|
|
123
|
+
|
|
124
|
+
# Install latest
|
|
125
|
+
npm install -g xithead
|
|
126
|
+
|
|
127
|
+
# Check version
|
|
128
|
+
xithead --version
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
## 🎯 Current Workflow
|
|
132
|
+
|
|
133
|
+
File: `.github/workflows/publish.yml`
|
|
134
|
+
|
|
135
|
+
Triggers on:
|
|
136
|
+
- Push to `main` branch
|
|
137
|
+
- When `package.json` or code changes
|
|
138
|
+
|
|
139
|
+
Publishes:
|
|
140
|
+
- To npm registry: https://www.npmjs.com/package/xithead
|
|
141
|
+
- Creates GitHub Release with changelog
|
|
142
|
+
- Creates git tag (v1.6.0)
|
|
143
|
+
|
|
144
|
+
## 📌 Important Notes
|
|
145
|
+
|
|
146
|
+
- **Never commit `package-lock.json`** changes from npm version
|
|
147
|
+
- **Always use `npm version` command** for automatic git tagging
|
|
148
|
+
- **Token expires**: Check npm token settings periodically
|
|
149
|
+
- **PyPI**: No longer needed (this is Node.js CLI, not Python)
|
|
150
|
+
|
|
151
|
+
## ✅ Verification Checklist
|
|
152
|
+
|
|
153
|
+
After setup:
|
|
154
|
+
|
|
155
|
+
- [ ] NPM_TOKEN secret added to GitHub
|
|
156
|
+
- [ ] Token is from "Automation" type
|
|
157
|
+
- [ ] Workflow file exists: `.github/workflows/publish.yml`
|
|
158
|
+
- [ ] Test with dummy version bump
|
|
159
|
+
- [ ] Check npm registry for successful publish
|
|
160
|
+
- [ ] GitHub Release created automatically
|
|
161
|
+
|
|
162
|
+
---
|
|
163
|
+
|
|
164
|
+
**Questions?** See PUBLISH.md for more details.
|