Migration/step 05

[surchs]

Title: chore(migration): step 05 query-tool
Branch: migration/step-05

Merge with a merge commit, not squash. This PR imports history.

Summary

• Import: query-tool imported with full history into tools/query-tool (upstream b3366bb, rewritten head 0615d95).
  • Its two gitlink pins are appended to migration/submodule-pins.txt.
  • .github/ and .gitmodules deleted.
  • neurobagel_examples and recipes are now symlinks to ../../examples and ../../stack.
• .github/workflows/test-node.yml: new reusable workflow with inputs tool, node-version, run-unit, run-component, run-e2e, component-env and e2e-env.
  • Lint, format check, typecheck and codespell always run.
  • The component and e2e jobs are ported from query-tool's component-test.yaml and e2e-test.yaml: same .env contents, build commands and Cypress action. e2e still targets https://federate.neurobagel.org/.
• .github/actions/docker-build: new composite action. It runs scripts/materialize-context.sh, then docker/build-push-action on that context, with inputs tool, tags, push (default false), load and platforms.
• CI:
  • query-tool job calling test-node.yml with component and e2e enabled.
  • query-tool-image job that builds the image through the composite action and checks that it serves HTTP 200 on port 5173.
  • The filter covers tools/query-tool/**, examples/**, test-node.yml, the composite action and materialize-context.sh.
• just: just test query-tool (npm ci, lint, format, typecheck, component tests).
• Baseline: migration/baseline.md records an already-failing upstream check (see Checks).
• Docs:
  • query-tool README: new section "Development in the Neurobagel monorepo".
  • Stale content updated:
    • the old-repository Actions badges
    • the .env location
    • npx husky init, which does nothing in a subfolder and would modify package.json
    • the git submodule steps
  • The compose test environment is marked as a known issue.
  • Root README: a Step 5 row.

Checks run

Check	Result
scripts/check-unchanged.sh	OK: protected paths unchanged (all four tools)
git rev-list --count <rewritten-head> / query-tool-v* tags	640 / 36 (upstream 640 / 36)
npm ci	OK; husky prints .git can't be found and exits 0 (constraint 6, fixed in Step 8)
lint:check, format:check, typecheck, codespell	all pass
NB_API_QUERY_URL=https://federate.neurobagel.org/ NB_ENABLE_AUTH=false npm run build	OK
Component tests (local, Cypress 15.21.1 image)	89 passed (baseline 89)
E2E tests (local, against npm run preview)	40 passed (baseline 40)
cd tools/query-tool && docker compose --profile test config --quiet	fails with service "api" depends on undefined service "init_data", the same as upstream (b3366bb, recipes v0.9.1). Recorded in migration/baseline.md as already failing upstream; fixed in Step 7a (maintainer decision).
Image built from the materialized context (what the composite action does)	runs and serves HTTP 200 on port 5173
docker build tools/query-tool	fails as expected: tsc reports TS2307: Cannot find module '../../neurobagel_examples/api-responses/...' because Docker does not follow the symlink. This confirms the materialize step is needed.
api / federation-api / bagel-cli tests	188 / 111 / 215 passed (baseline)
just lint	passes
CI on this PR (component, e2e, query-tool-image)	to be confirmed on GitHub

Documentation check: every command in the new README section was run verbatim, from the directory it names, in a fresh clone of this branch.

• Static checks: npm ci, the three static checks, and both .env/npm run build sequences pass.
• Cypress commands: npm run test:component and npm run test:e2e cannot start natively in the local container, which lacks libgtk-3. The same Cypress run passed in the cypress/included image (89 and 40).
• Preview server: npm run preview serves on 5173. Stopping it with Ctrl+C (SIGINT to the process group) stops it fully.
• just test query-tool: runs lint, format and typecheck, then stops at the native Cypress run, for the same container reason.
• Docker: the build command from the root succeeds.
• README fix found by this check: the first version of the README used npm run preview & … kill %1. kill %1 stops npm but leaves vite preview running, so the README now uses a second terminal and Ctrl+C.
• Clone: git clone was replaced by a local clone of this branch.

Deviations from the plan

• Compose test-profile check: fails as it does upstream (see above). Maintainer decision: record it in the baseline now, fix it in Step 7a. The plan is updated.
• Prettier job: upstream ran npm install --save-dev prettier && npx prettier --check .. The port runs npm ci && npm run format:check, which is the same prettier --check . with the locked prettier version.
• Codespell: runs pipx run codespell in the tool folder, so the tool's .codespellrc applies, instead of codespell-project/actions-codespell at the repository root.
• query-tool-image CI job: added to exercise the composite action on every query-tool PR. The plan's test "the image built through the composite action runs and serves HTTP 200" needs a workflow that calls the action.

Upstream workflows not re-created by an import step

Maintainer decisions, recorded in the plan:

• Kept: linkspector.yml (api) and cff_validation.yml (api, bagel-cli), as verbatim copies in migration/upstream-workflows/<repo>/, taken from each imported head. GitHub does not run them there.
  • linkspector is ported to a root workflow in the new Step 7d.
  • cff_validation becomes the validation of a single root CITATION.cff in the new Step 19, after cutover.
• Not migrated: query-tool's example-diff workflows. They are replaced by a CI check that the committed examples/query-tool-results/ are current, so a change and its regenerated examples land in one PR. This is the new Step 18, after cutover; it also points the docs at examples/.
• Not carried over:
  • handle_external_pr.yml and add_iss2project.yml: no longer needed.
  • stale.yml: set up again manually.
  • scorecard.yml: one Scorecard for the monorepo at cutover.

🤖 Generated with Claude Code