From af46e24ab32a1985ce951aad92f7324739978f0b Mon Sep 17 00:00:00 2001 From: root Date: Mon, 25 May 2026 02:32:00 +0000 Subject: [PATCH] docs(workspace): index gitea runner rollout --- REPO_CONTEXT.md | 194 ++++++++++++++++++++++++++++++++++++ docs/WORKSPACE_INVENTORY.md | 1 + 2 files changed, 195 insertions(+) create mode 100644 REPO_CONTEXT.md diff --git a/REPO_CONTEXT.md b/REPO_CONTEXT.md new file mode 100644 index 00000000..4acd7648 --- /dev/null +++ b/REPO_CONTEXT.md @@ -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) diff --git a/docs/WORKSPACE_INVENTORY.md b/docs/WORKSPACE_INVENTORY.md index 4ff90967..0b5b00c6 100644 --- a/docs/WORKSPACE_INVENTORY.md +++ b/docs/WORKSPACE_INVENTORY.md @@ -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` | ---