Skip to content

README.md

Latest commit

 

History

History
337 lines (239 loc) · 8.53 KB

README.md

File metadata and controls

337 lines (239 loc) · 8.53 KB

Solid Cockpit Header Logo

Solid Cockpit

Version Web App Tag Vue Vite License

Solid Cockpit is a web application for interacting with Solid Pods: authentication, data upload, query execution, and privacy management.

This application was developed in the context of the CHIST-ERA TRIPLE project.

Table of Contents

Users

What Solid Cockpit Does

Main capabilities:

  • Solid Pod login and registration flow
  • File upload and pod resource operations
  • SPARQL querying over Solid Pods and endpoints
  • Query caching support
  • Privacy/ACL access management

Accessing the App

Public deployment:

If you want to run locally, see Developers.

Ways to Get a Solid Pod

Usage Guides

TRIPLE onboarding guide:

Solid Pod VoID file generation:

Example:

mvn package
java -jar target/void-generator-0.7-SNAPSHOT-uber.jar \
  --from-solid-pod [URL-to-solid-pod] \
  --void-file void.ttl \
  -i [URL-to-solid-pod]/void.ttl \
  --repository [URL-to-solid-pod]

Then upload void.ttl to the pod root using the app's Data Upload page.

Citation

If you use this tool in an academic publication, you can cite:

Crum, E. (2026). Solid Cockpit (Version 1.0.0) [Software]. GitHub. https://github.com/KNowledgeOnWebScale/solid-cockpit

BibTeX:

@misc{solidcockpit_2026,
  author       = {Crum, Elias},
  title        = {{Solid Cockpit}},
  year         = {2026},
  version      = {1.0.0},
  publisher    = {GitHub},
  howpublished = {\url{https://github.com/KNowledgeOnWebScale/solid-cockpit}},
  note         = {Software. Web app: \url{https://knowledgeonwebscale.github.io/solid-cockpit}. Accessed: 2026-03-04}
}

You can also use:

  • CITATION.cff for GitHub-style citation metadata
  • CITATION.bib for direct BibTeX import

Contact and Support

Developers

Tech Stack

  • Vue 3 + Vite 6
  • TypeScript
  • Vuetify 3
  • Pinia
  • Inrupt Solid client/auth libraries
  • Comunica SPARQL engine

Prerequisites

  • Node.js 20+
  • Yarn 1.x (repo currently uses yarn.lock)

Local Setup

Install dependencies:

yarn install

Run locally:

yarn dev

Build production assets:

yarn build

Preview production build:

yarn serve

Scripts

Script Description
yarn dev Start Vite development server
yarn build Build production assets into dist/
yarn serve Preview the production build locally
yarn test:unit Run unit tests (Node built-in runner + TS loader)
yarn test:unit:watch Run unit tests in watch mode
yarn test:unit:coverage Run unit tests with coverage report generation
yarn test:unit:compliance Enforce unit-test + coverage thresholds
yarn test:unit:compliance:quiet Enforce unit coverage with concise output
yarn test:component Run Vue component tests (.vue) via Vitest
yarn test:component:watch Run Vue component tests in watch mode
yarn test:component:coverage Run Vue component tests with coverage
yarn test:component:compliance Enforce Vue component test coverage thresholds
yarn test:component:compliance:quiet Enforce component coverage with concise output
yarn test:compliance Run full (unit + component) compliance checks
yarn test:compliance:quiet Run full compliance checks with concise output
yarn hooks:install Configure local git hooks path (.githooks)
yarn github-post-build Create route-compatible index.html copies in dist/
yarn deploy Publish dist/ to GitHub Pages

Testing and Coverage

Unit test suite:

  • Location: tests/unit/
  • Command: yarn test:unit

Component test suite:

  • Location: tests/components/
  • Command: yarn test:component
  • Includes focused ThemeSwitch + TheFooter tests and full .vue smoke mounts in tests/components/AllComponentsSmoke.test.ts

Coverage tracker:

yarn test:unit:coverage

This command:

  • runs the unit test suite with Node coverage enabled
  • writes machine-readable output to coverage/unit-coverage-summary.json
  • writes a readable summary to coverage/unit-coverage-summary.txt

Compliance thresholds (gating):

  • line coverage: 98%
  • branch coverage: 90%
  • function coverage: 100%

Tracked files:

  • src/components/fileUploadUtils.ts
  • src/components/mime_types.js
  • src/components/queryPodUtils.ts
  • src/components/z3-headers.ts

Advisory (non-gating) coverage is also reported for:

  • src/components/login.ts
  • src/components/getData.ts
  • src/components/privacyEdit.ts

Override thresholds with env vars:

  • UNIT_COVERAGE_LINES
  • UNIT_COVERAGE_BRANCHES
  • UNIT_COVERAGE_FUNCS

Git Workflow

Commit-time compliance check:

  • Hook file: .githooks/pre-commit
  • Command run by hook: node ./scripts/precommit-compliance.mjs
  • Hook output is intentionally concise on pass and detailed on failure.

Install hooks locally:

yarn hooks:install

If automatic hook setup is blocked in your environment:

git config --local core.hooksPath .githooks

CI compliance check:

  • Workflow: .github/workflows/unit-test-compliance.yml
  • Enforces unit tests, component tests, and coverage thresholds.

Web-App Version Tags

Current app version:

  • package.json version: 1.0.0
  • web-app release tag convention: web-app-v<version>
  • current computed web-app tag: web-app-v1.0.0

In-app visibility:

  • Footer displays semantic version (vX.Y.Z) and computed release tag (web-app-vX.Y.Z)
  • Values are injected at build time from package.json via Vite defines

Recommended release workflow:

  1. Update version:
yarn version --new-version X.Y.Z
  1. Build and validate:
yarn test:unit
yarn build
  1. Create and push release tags:
git tag vX.Y.Z
git tag web-app-vX.Y.Z
git push origin vX.Y.Z web-app-vX.Y.Z

Deployment

GitHub Pages deployment setup:

  • vite.config.js uses /solid-cockpit/ base path for production
  • yarn github-post-build prepares route folders in dist/
  • yarn deploy publishes dist/ via gh-pages

Dependency Versions

Direct dependency versions currently declared in package.json.

Runtime dependencies:

Package Version
@comunica/context-entries ^4.2.0
@comunica/logger-pretty ^4.2.0
@comunica/query-sparql ^4.3.0
@comunica/query-sparql-solid ^4.0.2
@inrupt/solid-client 2.1.2
@inrupt/solid-client-authn-browser 3.1.0
@inrupt/solid-client-authn-node ^3.1.0
@triply/yasqe ^4.2.28
@triply/yasr ^4.2.28
@vitejs/plugin-vue ^5.2.3
@vue/eslint-config-typescript ^9.1.0
actor-query-process-remote-cache ^0.1.0
core-js ^3.8.3
fs ^0.0.1-security
pinia ^2.3.1
query-sparql-remote-cache ^0.0.9
sparqljs ^3.7.3
vite ^6.2.3
vue ^3.2.13
vue-router ^4.5.1
vuetify ^3.5.14
z3-solver ^4.15.3

Development dependencies:

Package Version
@tsconfig/node20 ^20.1.5
@typescript-eslint/eslint-plugin ^5.4.0
@typescript-eslint/parser ^5.4.0
@vitest/coverage-v8 2.1.9
@vue/test-utils 2.4.6
eslint ^7.32.0
eslint-config-prettier ^8.3.0
eslint-plugin-prettier ^4.0.0
eslint-plugin-vue ^8.0.3
gh-pages ^5.0.0
jsdom 24.1.3
prettier ^2.4.1
typescript ^5.0.0
vitest 2.1.9

Contributing

  • Open pull requests against the main branch
  • Use GitHub Issues for bug reports
  • Use GitHub Discussions for broader questions and ideas