{"id":50937869,"url":"https://github.com/bcorfman/zorkdemo","last_synced_at":"2026-06-17T11:03:05.908Z","repository":{"id":54073584,"uuid":"338102781","full_name":"bcorfman/zorkdemo","owner":"bcorfman","description":"Can you code a Zork adventure game demo in Python and have fun too? Why yes.","archived":false,"fork":false,"pushed_at":"2026-06-01T23:52:53.000Z","size":1697,"stargazers_count":3,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-06-02T01:20:57.032Z","etag":null,"topics":["adventure-game-engine","devops","fastapi","github-actions","postgres","python","react","rich","typescript","uv","vite","webapp","zork"],"latest_commit_sha":null,"homepage":"https://bcorfman.github.io/zorkdemo/","language":"Python","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/bcorfman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2021-02-11T17:37:28.000Z","updated_at":"2026-06-01T23:52:54.000Z","dependencies_parsed_at":"2023-02-01T02:30:33.565Z","dependency_job_id":null,"html_url":"https://github.com/bcorfman/zorkdemo","commit_stats":null,"previous_names":[],"tags_count":98,"template":false,"template_full_name":null,"purl":"pkg:github/bcorfman/zorkdemo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcorfman%2Fzorkdemo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcorfman%2Fzorkdemo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcorfman%2Fzorkdemo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcorfman%2Fzorkdemo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bcorfman","download_url":"https://codeload.github.com/bcorfman/zorkdemo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bcorfman%2Fzorkdemo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34445186,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["adventure-game-engine","devops","fastapi","github-actions","postgres","python","react","rich","typescript","uv","vite","webapp","zork"],"created_at":"2026-06-17T11:03:00.986Z","updated_at":"2026-06-17T11:03:05.900Z","avatar_url":"https://github.com/bcorfman.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# zorkdemo\n\n[![Python build and test](https://github.com/bcorfman/zorkdemo/actions/workflows/build-test.yml/badge.svg)](https://github.com/bcorfman/zorkdemo/actions/workflows/build-test.yml)\n\n#### 🌏  Open in the Cloud \n\nClick any of the buttons below to start a new development environment to demo or contribute to the codebase without having to install anything on your machine:\n\n[![Open in VS Code](https://img.shields.io/badge/Open%20in-VS%20Code-blue?logo=visualstudiocode)](https://vscode.dev/github/bcorfman/zorkdemo)\n[![Open in Glitch](https://img.shields.io/badge/Open%20in-Glitch-blue?logo=glitch)](https://glitch.com/edit/#!/import/github/bcorfman/zorkdemo)\n[![Open in Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true\u0026ref=main\u0026repo=338102781\u0026machine=standardLinux32gb\u0026devcontainer_path=.devcontainer%2Fdevcontainer.json\u0026location=EastUs)\n[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/bcorfman/zorkdemo)\n[![Edit in Codesandbox](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/github/bcorfman/zorkdemo)\n[![Open in Repl.it](https://replit.com/badge/github/withastro/astro)](https://replit.com/github/bcorfman/zorkdemo)\n[![Open in Codeanywhere](https://codeanywhere.com/img/open-in-codeanywhere-btn.svg)](https://app.codeanywhere.com/#https://github.com/bcorfman/zorkdemo)\n[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/bcorfman/zorkdemo)\n\nRuns on Linux, Windows or Mac.\n\nA (much simplified) port of a famous adventure game to help teach my daughter how to program in Python.\n\nTwo easy ways to launch the console project:\n\n1. Click on the Open with GitHub Codespaces badge above to launch the project in a browser or on your desktop inside Visual Studio Code, then type `uv run python zorkdemo.py` in the terminal window.\n2. Download one of the binary releases and run the file on your system.\n\nNOTE: the MacOS version does not have code signing built into it yet (that's next on my list!). To run it, you will need to set the binary as executable with `chmod 755` or similar, and after trying to run it once, go through System Preferences: Security and Privacy: General and \"Allow the program to run anyway\".\n\n## Monorepo Layout (Phase 0)\n\n- `adventure/`: shared game engine logic\n- `backend/`: FastAPI service (SQLAlchemy + Alembic, target Railway deploy)\n- `frontend/`: TypeScript frontend app (target GitHub Pages deploy)\n- `docs/architecture.md`: migration architecture notes\n\n## Local Development Quickstart\n\nInstall tooling and Python dependencies:\n\n- Install [Python](https://www.python.org) 3.10+\n- Install [uv](https://docs.astral.sh/uv/)\n- Run `uv sync --all-groups` from repo root\n\nStandardized environment variables:\n\n- Backend: `DATABASE_URL`, `CORS_ALLOW_ORIGINS` (see `backend/.env.example`)\n- Frontend: `VITE_API_BASE_URL` (see `frontend/.env.example`)\n\n## Makefile Workflow\n\nKey targets:\n\n- `make setup`: install project tooling (`uv`, and Node/npm if missing)\n- `make install`: install runtime dependencies only\n- `make devinstall`: install full dev/test dependencies\n- `make lint`: run `ruff check`\n- `make format`: run `ruff format`\n- `make test`: run Python + frontend tests\n- `make run`: ensure local backend is up, launch frontend dev server, and open browser (Linux/macOS/Windows)\n\n`make run` uses `uv run python -m backend.app.dev_runner` for cross-platform process startup, health checks, and browser opening.\n\nOptional `make run` variables:\n\n- `BACKEND_HOST`, `BACKEND_PORT`, `FRONTEND_HOST`, `FRONTEND_PORT`\n- `DATABASE_URL`, `CORS_ALLOW_ORIGINS`\n- `BACKEND_LOG` (default: `.tmp/zorkdemo-backend.log`)\n\n## Deployment (Phase 4)\n\n### Frontend (GitHub Pages)\n\n- Workflow: [.github/workflows/deploy-frontend-pages.yml](/home/bcorfman/dev/zorkdemo/.github/workflows/deploy-frontend-pages.yml)\n- Set repository variable `VITE_API_BASE_URL` to your Railway backend URL (example: `https://\u003cservice\u003e.up.railway.app`).\n- Push to `main` to build and publish `frontend/dist`.\n\n### Backend (Railway)\n\n- Deployment config: [railway.toml](/home/bcorfman/dev/zorkdemo/railway.toml)\n- Health endpoint used by deployment config: `/api/v1/health`\n- Required Railway env vars:\n  - `DATABASE_URL` (from Railway Postgres plugin)\n  - `CORS_ALLOW_ORIGINS` (must include your GitHub Pages URL)\n- Optional GitHub Actions deploy workflow: [.github/workflows/deploy-backend-railway.yml](/home/bcorfman/dev/zorkdemo/.github/workflows/deploy-backend-railway.yml)\n  - Requires secret `RAILWAY_TOKEN`\n  - Requires repo variable `RAILWAY_SERVICE`\n  - Optional repo variable `BACKEND_HEALTHCHECK_URL`\n\n## Extending The Game\n\nFor adding new locations, items, and commands, see:\n\n- [docs/extending-game.md](/home/bcorfman/dev/zorkdemo/docs/extending-game.md)\n\n### Run Backend (FastAPI v1 API)\n\n```sh\nuv run alembic -c backend/alembic.ini upgrade head\nuv run uvicorn backend.app.main:app --host 0.0.0.0 --port 8000 --reload\n```\n\nAPI endpoints:\n\n- `GET /api/v1/health`\n- `POST /api/v1/session`\n- `POST /api/v1/command`\n- `POST /api/v1/session/reset`\n\n### Run Frontend (TypeScript App)\n\n```sh\ncd frontend\nnpm install\nnpm run dev\n```\n\nNavigate to [http://localhost:5173/](http://localhost:5173/)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbcorfman%2Fzorkdemo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbcorfman%2Fzorkdemo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbcorfman%2Fzorkdemo/lists"}