{"id":33547936,"url":"https://github.com/joudbitar/dsa-teacher","last_synced_at":"2026-03-07T04:31:51.954Z","repository":{"id":323263059,"uuid":"1092099536","full_name":"joudbitar/dsa-teacher","owner":"joudbitar","description":null,"archived":false,"fork":false,"pushed_at":"2025-11-27T21:44:34.000Z","size":56574,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-29T22:39:45.051Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://hackathon-lime-beta.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joudbitar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-08T02:00:06.000Z","updated_at":"2025-11-27T21:44:38.000Z","dependencies_parsed_at":null,"dependency_job_id":"cd1415ac-7912-4220-b1d9-880295b113ab","html_url":"https://github.com/joudbitar/dsa-teacher","commit_stats":null,"previous_names":["joudbitar/dsa-teacher"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/joudbitar/dsa-teacher","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joudbitar%2Fdsa-teacher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joudbitar%2Fdsa-teacher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joudbitar%2Fdsa-teacher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joudbitar%2Fdsa-teacher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joudbitar","download_url":"https://codeload.github.com/joudbitar/dsa-teacher/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joudbitar%2Fdsa-teacher/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30208020,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T03:24:23.086Z","status":"ssl_error","status_checked_at":"2026-03-07T03:23:11.444Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-11-27T07:04:05.008Z","updated_at":"2026-03-07T04:31:51.912Z","avatar_url":"https://github.com/joudbitar.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Shelly\n\nShelly is a toolkit for learning data structures with hands-on projects.  \nThe monorepo bundles a React dashboard, Node.js CLI, and Supabase Edge Functions that\nwork together to provision challenge repositories, run local tests, and report progress.\n\n## Packages\n\n- `cli/` – `dsa` command-line interface (test, submit, hints)\n- `web/` – Vite + React dashboard\n- `supabase/` – Edge Functions, migrations, and database schema\n- `docs/` – Reference material for contributors\n\n## Getting Started\n\n```bash\n# Clone (replace \u003corg\u003e with your GitHub org or account)\ngit clone https://github.com/\u003corg\u003e/shelly.git\ncd shelly\n\n# Install workspace dependencies\npnpm install\n\n# Build the CLI\npnpm --filter ./cli build\n\n# Start the web dashboard\npnpm --filter ./web dev\n```\n\nSupabase and GitHub credentials are not bundled.  \nCreate your own Supabase project, configure the secrets listed in\n`supabase/functions/README.md`, and register a GitHub App with access to your template\nrepositories before deploying the Edge Functions.\n\n## Install the CLI\n\nInstall the CLI with a single command:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/joudbitar/dsa-teacher/main/scripts/install-cli.sh | bash\n```\n\nAfter installation, verify with `dsa --version`. If the command is not found, add `~/.local/bin` to your PATH:\n\n```bash\necho 'export PATH=\"$HOME/.local/bin:$PATH\"' \u003e\u003e ~/.zshrc\nsource ~/.zshrc    # or restart your terminal\n```\n\n### For Contributors\n\nIf you're working on the CLI itself, you can install from the local workspace:\n\n```bash\nmake install-cli         # builds cli/ locally and links dsa into ~/.local/bin\ndsa --version            # verify the binary resolves\n```\n\n## Environment\n\n- Node.js ≥ 18 (includes npm)\n- pnpm ≥ 8\n- Supabase CLI (for deploying Edge Functions)\n- GitHub App private key + credentials (for provisioning repositories)\n\nCopy any environment variables into `.env.local` (not committed) and load them before\nrunning `supabase functions serve` or deploying to production.\n\n## Repository Layout\n\n```\n.\n├─ cli/            # Node.js CLI (TypeScript)\n├─ docs/           # Additional contributor guides\n├─ infra/          # API definitions \u0026 support files\n├─ supabase/       # Edge Functions, migrations, seed data\n├─ web/            # React dashboard\n└─ scripts/        # Utility scripts\n```\n\n## Documentation\n\nThis section is the canonical reference for onboarding to the Shelly platform and its CLI. Share it with learners, instructors, and administrators to ensure everyone follows the same workflow.\n\n### Platform Overview\n\n- The dashboard provisions challenge repositories and tracks learner progress via Supabase Edge Functions.\n- Each challenge repo ships with `dsa.config.json`, template tests, and optional `HINTS.md` that the CLI can surface.\n- The CLI (`dsa`) is the primary touchpoint for running tests locally, requesting hints, and submitting progress back to the platform.\n\n### Install the CLI\n\n| Scenario                       | Command                                                      | Notes                                                                                             |\n| ------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |\n| **Quick install (recommended)** | `curl -fsSL https://raw.githubusercontent.com/joudbitar/dsa-teacher/main/scripts/install-cli.sh \\| bash` | One-liner that downloads, builds, and installs. No configuration needed.                           |\n| Local workspace (contributors)  | `make install-cli`                                           | Builds from your checkout and links `dsa` into `~/.local/bin`.                                    |\n| Remote fetch helper            | `make install-cli-remote`                                    | Downloads sources via `scripts/install-cli.sh` before building/linking.                           |\n| Script with custom locations   | `DSA_CLI_HOME=$HOME/dsa-cli ./scripts/install-cli.sh`        | Overrides artifact cache path; pair with `DSA_CLI_BIN` to control the symlink directory.          |\n| Manual fallback                | `cd cli \u0026\u0026 pnpm install \u0026\u0026 pnpm build \u0026\u0026 pnpm link --global` | Use when automation is blocked. Re-run after pulling CLI changes.                                 |\n\nVerify the install:\n\n```bash\ndsa --version\nwhich dsa   # confirm the command resolves\n```\n\n\u003e Note: On macOS and Linux the installer links to `~/.local/bin`. Append the directory to your shell profile: `echo 'export PATH=\"$HOME/.local/bin:$PATH\"' \u003e\u003e ~/.zshrc`.\n\n### Daily Workflow\n\n1. **Sync the challenge repository** – Pull the latest template updates before you code.\n2. **Run tests locally** – Use `dsa test` to execute the `testCommand` defined in `dsa.config.json`; the CLI parses `.dsa-report.json` and highlights unlocked subchallenges.\n3. **Request hints when stuck** – Run `dsa hint` to render context-aware tips pulled from `HINTS.md`.\n4. **Submit progress** – After passing tests, run `dsa submit`. The CLI re-runs tests, attaches the current Git commit SHA (if available), and unlocks the next challenge on success.\n5. **Review the dashboard** – Follow the URL printed after submission to confirm that Supabase recorded your progress.\n\n### Command Reference\n\n| Command      | Purpose                                                                        | Key Output                                                                    |\n| ------------ | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |\n| `dsa --help` | Lists all subcommands and global flags.                                        | Usage banner, version information.                                            |\n| `dsa test`   | Runs the configured test suite, parses the report, and renders a status panel. | Module name, unlocked challenge index, pass/fail summary, next-step guidance. |\n| `dsa submit` | Re-runs tests and posts results to `{apiUrl}/submissions`.                     | Submission status, dashboard URL, unlock confirmation.                        |\n| `dsa hint`   | Prints curated hints for the active subchallenge.                              | Excerpt from `HINTS.md`, aligned with the learner’s current step.             |\n\nAll commands exit with status `0` when the CLI completes successfully. Configuration errors, network failures, or unhandled exceptions return status `1` with actionable messaging.\n\n### Troubleshooting \u0026 Diagnostics\n\n| Symptom                       | Likely Cause                                         | Resolution                                                                                                            |\n| ----------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |\n| `dsa: command not found`      | PATH does not include the CLI bin directory.         | Re-run the installer or `pnpm link --global`, then restart the shell after exporting `PATH=\"$HOME/.local/bin:$PATH\"`. |\n| `Not a DSA project`           | CLI cannot locate `dsa.config.json`.                 | Change into the repository root or copy the config from the dashboard-generated repo.                                 |\n| `Failed to parse test report` | The `testCommand` crashed or wrote malformed JSON.   | Run the raw command (e.g., `node tests/run.js`) and delete stale `.dsa-report.json` before retrying `dsa test`.       |\n| Submission returns `401`      | Project token rotated or is missing.                 | Refresh the project from the dashboard, update `projectToken`, and try again.                                         |\n| Submission returns `404`      | Repository is not linked to the expected project ID. | Confirm you cloned the correct challenge repo and that `projectId` matches the dashboard.                             |\n| Timeout or ECONNREFUSED       | Supabase Edge Function unreachable.                  | Check network connectivity, VPN, or staging URLs; retry after service is healthy.                                     |\n\nCapture the full CLI output when asking for support. Many errors include remediation hints inline.\n\n### How the CLI Works\n\n- `cli/src/index.ts` bootstraps the `commander` program and delegates to subcommand handlers.\n- `cli/src/lib/loadConfig.ts` walks up from the current directory to locate and validate `dsa.config.json`.\n- `cli/src/lib/runCommand.ts` executes the project’s `testCommand`, streaming logs and surfacing non-zero exit codes.\n- `cli/src/lib/parseReport.ts` reads the JSON report and normalizes results for display and submission payloads.\n- `cli/src/lib/http.ts` signs API requests with `projectId` and `projectToken` to communicate with Supabase Edge Functions.\n- `cli/src/lib/git.ts` captures the latest commit SHA when available, enabling auditing on the dashboard.\n\nFor a deeper dive, review `docs/cli-reference.md` and `docs/guides/QUICK_START.md`. Keep these documents updated when the workflow changes.\n\n## Contributing\n\n1. Fork and clone the repository.\n2. Run `pnpm install` at the workspace root.\n3. Use `pnpm --filter ./cli build` or `pnpm --filter ./web dev` when working on a package.\n4. Keep secrets in environment variables—never commit real keys.\n5. Submit a pull request with tests or manual verification notes.\n\n## License\n\nThis project is released under the MIT License. See `LICENSE` for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoudbitar%2Fdsa-teacher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoudbitar%2Fdsa-teacher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoudbitar%2Fdsa-teacher/lists"}