TimetableKit is a local-first TypeScript workspace. Contributions are welcome for parsing, normalization, validation, exports, provider boundaries, user interfaces, examples, tests, and documentation.
Read the Code of Conduct, security policy, support guide, and roadmap before you start.
Use the repository toolchain:
- Node.js 24, declared in .node-version and .nvmrc.
- pnpm 11.10.0, declared in package.json.
From the repository root, install the locked dependency graph:
node --version
pnpm --version
pnpm install --frozen-lockfileThe commands in this guide assume that the selected Node version is 24. If you use mise, prefix a command with mise exec node@24 --.
Keep each change at the narrowest valid boundary.
| Area | Directory | Owns |
|---|---|---|
| Core | packages/core | Schemas, parsing, normalization, validation, conflicts, corrections, and exports |
| Agent | packages/agent | JSON request and response contracts, capabilities, and JSONL transport |
| CLI | packages/cli | Local file and stdin input, process output, and CLI argument handling |
| React | packages/react | Reusable correction and preview views |
| Web | apps/web | The playground, browser input boundaries, documentation routes, and web tests |
| Providers | packages/provider-* | PDF, OCR, and optional remote recovery adapters |
| Fixtures | fixtures and scripts | Synthetic inputs, expected results, manifests, and deterministic generation |
| Examples | examples | Small consumer integrations that use public package APIs |
Keep browser, filesystem, OCR, PDF, and remote provider code outside the core package. Do not import another package through its src directory. Build the core package before you typecheck a provider package.
- Find or open an issue that describes the smallest useful change.
- Read the relevant package and its tests before editing.
- Keep input handling local and bounded. Treat imported timetable content as untrusted data.
- Add a deterministic test for each changed behavior.
- Update the relevant documentation and changelog entry when the public behavior changes.
- Run the focused checks from the table below.
- Run pnpm validate for a cross-package change or before you open a pull request.
- Review git diff, run git diff --check, and remove generated output that does not belong in the change.
Do not add real schedules, personal data, credentials, private URLs, or copied institution documents. Use synthetic or explicitly redistributable fixtures. See Adding a fixture.
Run the smallest command that covers the files you changed.
| Change | Commands |
|---|---|
| Core parser, schemas, validation, conflicts, corrections, or exports | pnpm --filter @ndycode/timetablekit typecheck and pnpm --filter @ndycode/timetablekit test |
| Agent contract or JSONL transport | pnpm --filter @ndycode/timetablekit-agent typecheck and pnpm --filter @ndycode/timetablekit-agent test |
| CLI | pnpm --filter @ndycode/timetablekit-cli typecheck and pnpm --filter @ndycode/timetablekit-cli test |
| React components | pnpm --filter @ndycode/timetablekit-react typecheck and pnpm --filter @ndycode/timetablekit-react test |
| Web app or schema routes | pnpm --filter web typecheck and pnpm --filter web test:unit |
| Web accessibility or keyboard behavior | pnpm --filter web test:a11y |
| PDF or OCR provider | Build core first, then run the provider typecheck and test commands |
| Fixture or parser dialect | pnpm fixtures:validate and the core focused checks |
| Package metadata or package order | pnpm packages:check, pnpm packages:test, and pnpm packages:pack |
After building, run pnpm packages:verify to check that the package file lists include declared runtime, type, schema, and executable entry points.
pnpm packages:pack only lists the package archive commands. It does not publish a package. Maintainers use the release process for package archives and publication.
Describe the result that a user can observe. Include:
- the issue or problem that the change addresses.
- the files or package boundary that changed.
- the exact verification commands and their results.
- any new warning, error, limit, schema, or export behavior.
- the privacy impact and any provider data flow.
- known limitations or follow-up work.
Use synthetic data in screenshots and examples. Keep unrelated cleanup out of the pull request. A maintainer can ask for a smaller change when separate concerns make review difficult.
Before you submit, check:
[ ] The change has a focused scope.
[ ] Tests cover the changed behavior.
[ ] Public behavior has matching documentation.
[ ] No real schedule or private data is present.
[ ] Remote processing remains explicit, bounded, and consented.
[ ] pnpm validate passed, or the failed or unavailable command is recorded.
[ ] git diff --check passed.
Keep the normalized result schema versioned. If you add a public field, warning, error, option, export behavior, or package entry point:
- update the runtime and static schemas together;
- add a focused test and a fixture when the behavior is parser-facing;
- update the API reference;
- update CHANGELOG.md;
- explain compatibility and migration impact in the pull request.
Consumers that enumerate warning codes must handle a new warning code. Do not silently change the meaning of an existing field.
Do not publish packages, deploy the web app, or change provider credentials as part of an ordinary contribution. The release checklist defines the maintainer release process.
Report suspected vulnerabilities through the private route in SECURITY.md. Do not include exploit details, credentials, or private timetable content in a public issue or pull request.
Contributions are subject to the repository MIT License.