mirror of
https://github.com/hypit-ai/hypit.git
synced 2026-11-17 07:09:34 +08:00
Replace the generic playground with a file-backed Caption Playground, separate source workspaces from installed package roots, and derive exact transitive Module providers in Node package locks.
64 lines
2.4 KiB
Markdown
64 lines
2.4 KiB
Markdown
---
|
||
title: Development Guide
|
||
description: Getting started with Narratage development.
|
||
---
|
||
|
||
# Development Guide
|
||
|
||
## Prerequisites
|
||
|
||
| Tool | Version | Required for |
|
||
|---|---|---|
|
||
| Node.js | 22+ | everything |
|
||
| pnpm | 10.33.x | workspace management; selected by the root `packageManager` field |
|
||
| Python | 3.10–3.13 | WhisperX and OpenCV [local services](./services.md) |
|
||
| uv | latest | Python environment management |
|
||
| ffmpeg / ffprobe | recent stable | media processing |
|
||
| Chrome / Chromium | managed by HyperFrames | local HyperFrames rendering |
|
||
|
||
Node.js and pnpm are the only hard requirements. The rest are needed only for live Builds.
|
||
|
||
## Daily workflow
|
||
|
||
```bash
|
||
corepack enable
|
||
pnpm install --frozen-lockfile # after pulling or changing dependencies
|
||
pnpm check # TypeScript type-check
|
||
pnpm test # full test suite
|
||
```
|
||
|
||
| Command | What it runs |
|
||
|---|---|
|
||
| `pnpm check` | `tsc -p tsconfig.json --noEmit` |
|
||
| `pnpm test` | package, service-adapter and repository-boundary tests through Node's test runner |
|
||
|
||
See [Testing](./testing.md) for environment-gated tests and test patterns.
|
||
|
||
## Repository layout
|
||
|
||
```text
|
||
narratage/
|
||
├── packages/ 86 workspace packages
|
||
├── spec/ 16 normative specification documents
|
||
├── docs/ VitePress documentation site
|
||
├── examples/ runnable example sources
|
||
├── services/ Python services (whisperx, image-opencv)
|
||
├── tools/ boundary tests and build scripts
|
||
├── package.json root workspace manifest
|
||
├── pnpm-workspace.yaml workspace: [packages/*]
|
||
└── tsconfig.json TypeScript config
|
||
```
|
||
|
||
## Guide contents
|
||
|
||
| Guide | Topic |
|
||
|---|---|
|
||
| [Package architecture](./packages.md) | The five layers, dependency rules, package anatomy, facets |
|
||
| [Adding an author package](./author-packages.md) | Step-by-step: new component, Surface, activation |
|
||
| [Adding a Provider](./providers.md) | Step-by-step: new Endpoint adapter |
|
||
| [Runtime Profile](./runtime-profile.md) | JSON and TypeScript configuration, diagnostics, Build archive |
|
||
| [Caption Playground](./caption-playground.md) | Edit real Caption SVML/SVS with live feedback |
|
||
| [Local services](./services.md) | WhisperX and OpenCV setup |
|
||
| [Testing](./testing.md) | Test runner, patterns, examples, boundary tests |
|
||
| [Conventions](./conventions.md) | Naming, module boundaries, wire data, TypeScript config |
|