docs(workspace): index gitea runner rollout
This commit is contained in:
root
parent
1bb8b38547
commit
af46e24ab3
194
REPO_CONTEXT.md
Normal file
194
REPO_CONTEXT.md
Normal file
@ -0,0 +1,194 @@
|
||||
# ByteLyst Common Platform - Repository Context
|
||||
|
||||
> **Purpose**: This file provides quick context for AI coding agents about what this repository contains and how to use it effectively.
|
||||
|
||||
## What This Repository Provides
|
||||
|
||||
This is the **shared platform repository** for the ByteLyst ecosystem. It contains:
|
||||
|
||||
- **36 shared libraries** (`@bytelyst/*` packages) used across all products
|
||||
- **Platform services** (platform-service, extraction-service, mcp-server)
|
||||
- **Internal dashboards** (admin-web, tracker-web, ux-lab)
|
||||
- **MCP/A2A tooling** and orchestration infrastructure
|
||||
- **Design tokens** and cross-platform SDKs
|
||||
|
||||
## Key Locations
|
||||
|
||||
### Packages (Shared Libraries)
|
||||
|
||||
- **Location**: `packages/`
|
||||
- **Pattern**: All packages are scoped as `@bytelyst/{package-name}`
|
||||
- **Count**: 36 packages covering auth, config, storage, telemetry, diagnostics, etc.
|
||||
- **Build**: Individual packages via `pnpm --filter @bytelyst/{package} build`
|
||||
- **Key Packages**:
|
||||
- `@bytelyst/config` - Environment configuration and product identity
|
||||
- `@bytelyst/cosmos` - Azure Cosmos DB client singleton
|
||||
- `@bytelyst/auth` - JWT utilities and auth middleware
|
||||
- `@bytelyst/api-client` - Configurable fetch wrapper with auth
|
||||
- `@bytelyst/telemetry-client` - Client diagnostics and event batching
|
||||
- `@bytelyst/llm` - LLM client utilities
|
||||
- `@bytelyst/devops` - Build metadata and deployment utilities
|
||||
|
||||
### Services
|
||||
|
||||
- **Location**: `services/`
|
||||
- **platform-service**: Product-agnostic platform API (port 4003)
|
||||
- **extraction-service**: LangExtract text extraction + Python sidecar (port 4005)
|
||||
- **mcp-server**: MCP tool server + A2A orchestration
|
||||
|
||||
### Scripts
|
||||
|
||||
- **Location**: `scripts/`
|
||||
- **docker-prep.sh**: Build all packages before Docker builds
|
||||
- **quick-check.sh**: Quick quality check (5 min) - run before pushing
|
||||
- **sync-npmrc.sh**: Sync .npmrc template to all product repos
|
||||
- **prototype-self-test.sh**: Prototype health check script
|
||||
|
||||
### Documentation
|
||||
|
||||
- **Location**: `docs/`
|
||||
- **ecosystem/**: Cross-product strategy and shared-contract documentation
|
||||
- **devops/gitea-runner/**: Canonical Hostinger Gitea Actions runner rollout docs and delegation prompt
|
||||
- **PROTOTYPE_DEPLOYMENT.md**: Prototype deployment guide
|
||||
|
||||
## Common Usage Patterns
|
||||
|
||||
### Building Packages
|
||||
|
||||
```bash
|
||||
# Build all packages
|
||||
pnpm build
|
||||
|
||||
# Build specific package
|
||||
pnpm --filter @bytelyst/config build
|
||||
|
||||
# Build all packages + services
|
||||
pnpm build
|
||||
```
|
||||
|
||||
### Quality Checks
|
||||
|
||||
```bash
|
||||
# Quick check (before pushing)
|
||||
./quick-check.sh
|
||||
|
||||
# Full test suite
|
||||
pnpm test
|
||||
|
||||
# Type-check all packages
|
||||
pnpm typecheck
|
||||
```
|
||||
|
||||
### Docker Preparation
|
||||
|
||||
```bash
|
||||
# Build all packages before Docker builds (critical!)
|
||||
./scripts/docker-prep.sh
|
||||
```
|
||||
|
||||
## Package Dependencies
|
||||
|
||||
### Workspace Protocol
|
||||
|
||||
- Uses `pnpm` workspace with `workspace:*` protocol
|
||||
- Dependencies between packages use: `"@bytelyst/config": "workspace:*"`
|
||||
- External dependencies use standard semver ranges
|
||||
|
||||
### Build Order
|
||||
|
||||
- **Always build common-plat packages before product repos**
|
||||
- Docker builds depend on packages being pre-built via `docker-prep.sh`
|
||||
- Product repos import from `learning_ai_common_plat/packages/{package}/dist/`
|
||||
|
||||
### Package Scope Rules
|
||||
|
||||
- **@bytelyst/\*** = shared libraries (packages/)
|
||||
- **@lysnrai/\*** = platform services (services/)
|
||||
- Products consume `@bytelyst/*` packages
|
||||
|
||||
## Integration with Product Repos
|
||||
|
||||
### When Working in Product Repos
|
||||
|
||||
1. If you need to modify a shared package, do it here first
|
||||
2. Build the package: `pnpm --filter @bytelyst/{package} build`
|
||||
3. Then rebuild the product that consumes it
|
||||
4. For Docker builds in products, always run `./scripts/docker-prep.sh` first
|
||||
|
||||
### Common Issues
|
||||
|
||||
- **"Cannot find module @bytelyst/..."**: Package needs to be built
|
||||
- **Docker build fails**: Run `docker-prep.sh` to build all packages first
|
||||
- **Version conflicts**: Check workspace protocol in package.json files
|
||||
|
||||
## NPM Registry Configuration
|
||||
|
||||
### Gitea Registry
|
||||
|
||||
- **Registry**: `http://localhost:3300/api/packages/bytelyst/npm/`
|
||||
- **Token**: Managed via `.npmrc` template
|
||||
- **Template**: `scripts/npmrc.template`
|
||||
- **Sync Script**: `scripts/sync-npmrc.sh` (syncs to all product repos)
|
||||
|
||||
### .npmrc Management
|
||||
|
||||
- **NEVER edit .npmrc files directly in product repos**
|
||||
- Use the canonical template in this repo
|
||||
- Sync changes to all repos via `sync-npmrc.sh`
|
||||
|
||||
## TypeScript Configuration
|
||||
|
||||
### Base Configuration
|
||||
|
||||
- **File**: `tsconfig.base.json`
|
||||
- **Target**: ES2022, NodeNext module resolution
|
||||
- **Strict mode**: Enabled
|
||||
- All packages/services extend this base config
|
||||
|
||||
## Testing
|
||||
|
||||
### Test Runner
|
||||
|
||||
- **Framework**: Vitest
|
||||
- **Command**: `pnpm test` (runs all package tests)
|
||||
- **Pass with no tests**: Configured at root level
|
||||
- **Individual packages**: `pnpm --filter @bytelyst/{package} test`
|
||||
|
||||
## Important Notes
|
||||
|
||||
### Before Making Changes
|
||||
|
||||
1. Read the specific package's documentation
|
||||
2. Check if changes affect consuming products
|
||||
3. Run `quick-check.sh` before committing
|
||||
4. Consider impact on all ecosystem products
|
||||
|
||||
### Package Publishing
|
||||
|
||||
- Packages are published to internal Gitea registry
|
||||
- Not published to public npm registry
|
||||
- Version management follows semantic versioning
|
||||
|
||||
### Design Tokens
|
||||
|
||||
- **Canonical source**: `packages/design-tokens/tokens/bytelyst.tokens.json`
|
||||
- **Generator**: `packages/design-tokens/scripts/generate.ts`
|
||||
- **Outputs**: CSS, TypeScript, Kotlin, Swift, React Native
|
||||
- **NEVER hardcode colors** - always use design tokens
|
||||
|
||||
## Quick Reference for Common Tasks
|
||||
|
||||
| Task | Command |
|
||||
| ------------------------- | ----------------------------------------- |
|
||||
| Build all packages | `pnpm build` |
|
||||
| Build specific package | `pnpm --filter @bytelyst/{package} build` |
|
||||
| Quick quality check | `./quick-check.sh` |
|
||||
| Prepare for Docker builds | `./scripts/docker-prep.sh` |
|
||||
| Run tests | `pnpm test` |
|
||||
| Type-check | `pnpm typecheck` |
|
||||
| Sync .npmrc to all repos | `./scripts/sync-npmrc.sh` |
|
||||
|
||||
## Related Repositories
|
||||
|
||||
- **bytelyst-devops-tools**: Deployment scripts and operational automation
|
||||
- **Product repos**: learning_ai_invt_trdg, learning_ai_notes, etc. (consume these packages)
|
||||
@ -131,6 +131,7 @@ _(All under the `@bytelyst/` scope — consumed via `file:` or `workspace:_` ref
|
||||
| Canonical active repo list | `.windsurf/workflows/repos.txt` |
|
||||
| MCP/A2A orchestration | `docs/MCP+A2A/README.md` |
|
||||
| Azure resource inventory | `docs/devops/AZURE_RESOURCE_INVENTORY.md` |
|
||||
| Gitea runner rollout | `docs/devops/gitea-runner/README.md` |
|
||||
|
||||
---
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user