0 Fork 0

Files

T

james.maesandClaude Fable 5.1 ac86860422 chore(repo): add contributing, security, conduct and GitHub templates

The repository had no contributor or security guidance and no .github
directory, so a 1.0.0 public release would give reporters no private
channel and contributors no statement of the checks, the signed-commit
rule on main or the license their work falls under.

Modeled on QRun-IO/qqq but adapted: npm workspaces plus Bun for the TUI,
the qqq-orb cli profile, Apache-2.0 (no AGPL text copied), conventional
signed commits. CODEOWNERS requests @KofTwentyTwo on every change.
Dependabot groups weekly minor and patch updates for the npm workspaces
and, through its bun ecosystem, for packages/tui's bun.lock; the
throwaway tui-spike is left out on purpose. Issue templates ask for the
qqq doctor build line, and route server and security problems elsewhere.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

2026-11-01 04:18:03 -06:00

4.4 KiB

Raw Permalink Blame History

Contributing to qqq-cli

Thanks for helping. This repository holds qqq (the CLI and the terminal UI) and the TypeScript packages it is built on. Bugs and ideas go in issues; problems in the QQQ server or the UI API itself belong in QRun-IO/qqq. Security problems: see SECURITY.md, never a public issue.

Layout

Path	What	Toolchain
`packages/ui-api-client`	the typed client, generated from `openapi/qqq-v1.json`	npm workspace, TypeScript
`packages/core`	the client kernel (no terminal code)	npm workspace, TypeScript
`packages/conformance`	the conformance suite and `qqq-dev-idp`	npm workspace, TypeScript
`packages/cli`	`qqq`	npm workspace, TypeScript, commander
`packages/tui`	`qqq ui` (OpenTUI on Bun); private, bundled into the binaries	Bun, its own `bun.lock`
`scripts/`	spec merging, code generation, lint, binaries, release, packaging, install	Node, sh
`docs/`	see docs/README.md

Setup

Node.js 20 or later (CI runs 22) and npm. The workspaces share the root package-lock.json.
Bun 1.4 or later, for the TUI and for building binaries (brew install bun, or https://bun.sh).
For trying changes against a real server: the QQQ sample server (Java 21, Maven), see TRY-IT.md. npm run mock serves the API document with Prism on http://127.0.0.1:4010 when no server is at hand.

git clone https://github.com/QRun-IO/qqq-cli && cd qqq-cli
npm ci
npm run build
node packages/cli/dist/main.js --help        # the CLI from the checkout
node packages/cli/dist/main.js ui            # the TUI from source (runs Bun)

Checks

Every pull request must pass, locally and in CI:

npm run build && npm test && npm run lint    # lint: license headers, no cross-package src imports, version consistency
npm run test:tui                             # when packages/tui or the kernel changed
npm run typecheck:tui                        # likewise

When the API document changes (npm run spec:merge or npm run spec:merge-extensions), run npm run generate and commit the regenerated packages/ui-api-client/src/schema.ts and packages/core/src/api/operations.ts; CI fails when schema.ts drifts and scripts/release.mjs checks both. Do not edit generated files by hand.

Code

TypeScript, ESM, strict. Each package imports the others by package name, never from another package's src/ (lint enforces it).
Every source file starts with the license header lint checks: Copyright 2026 QRun.IO, Inc. / Licensed under the Apache License, Version 2.0 (see LICENSE).
Nothing about an application is hard-coded: tables, processes, labels and capabilities come from the server's metadata, and unknown enum values or fields are tolerated. Every call is a spec operation.
@qrun-io/qqq-core and the CLI use no Bun-only API; the TUI uses OpenTUI and only draws what the kernel produces.
Tests sit next to the code in src/test (node --test) and packages/tui/test (bun test). New behaviour comes with a test; a bug fix with a test that failed before it.
Commands, output shapes and exit codes are a public interface. Changing one is a breaking change: say so in the pull request and the CHANGELOG.

Commits and pull requests

Signed commits are required on main (git commit -S; set up SSH or GPG signing in GitHub). Unsigned commits cannot be merged.
Conventional-commit subjects (feat(cli): ..., fix(core): ..., docs: ...), with a body that says why.
Branch from main; one topic per pull request. Fill in the pull request template, including how you tested against a server.
User-visible changes get a line in CHANGELOG.md under the next version, and new or changed commands are documented in the README, TRY-IT.md or the package README. node scripts/readiness.mjs checks that every qqq command in README.md and TRY-IT.md exists.
Do not bump package versions in a feature pull request; releases do that (docs/release-runbook.md).
CODEOWNERS requests the maintainer's review on every pull request.

License

By contributing you agree that your contribution is your own work and is licensed under the Apache License 2.0, the license of this repository.

Everyone taking part follows the Code of Conduct.

4.4 KiB Raw Permalink Blame History