@codejongos/workplace-packager 0.1.2

package/README.md

@@ -0,0 +1,142 @@
+# @codejongos/workplace-packager
+
+Build and run the Moodle Workplace demo image from your own Moodle source tree.
+
+> **Status: `0.1.0`, published for testing.** Every action below is implemented and tested. The
+> version is deliberately pre-1.0: at `0.x` the CLI clones the packager repo's `main` branch rather
+> than a tag matching its own version, so what you build tracks whatever `main` holds. Tag pinning
+> starts at `1.0.0`.
+
+```
+npx @codejongos/workplace-packager
+```
+
+Requires Node 20.11 or newer, git, and Docker Desktop. No other install step: the package is one
+bundled file with no runtime dependencies.
+
+**You also need SSH access to `git.in.moodle.com` and membership of the `demo-experience` group** —
+the CLI clones the packager repo, `demo-sites-data` and the four demo plugin repos. Run `doctor`
+first; it checks all six and names the one that is missing.
+
+## Usage
+
+```
+workplace-packager [action] [options]
+```
+
+With no action on a terminal, it launches the interactive TUI. With an action, it runs headless and
+prints plain lines — the same events, a different subscriber.
+
+| Action | What it does |
+|---|---|
+| `doctor` | Check git, Docker, buildx, the build context, and GitLab read access |
+| `data` | Sync `demo-sites-data` to its branch tip |
+| `plugins` | Stage the four demo plugins |
+| `build` | Build the image from your Moodle tree |
+| `run` | Run it, ephemeral |
+| `run-persistent` | Run it with persistent volumes and the MySQL port published |
+| `logs` / `shell` / `stop` / `clean` | Container lifecycle |
+
+Action names match the bash tool's, including the `submodules-data-only` alias, so existing scripts
+keep working.
+
+| Option | |
+|---|---|
+| `-n, --dry-run` | Print every git/docker command instead of running it |
+| `--no-tui` | Plain line output, even on a terminal |
+| `-v, --verbose` | Include debug-level output |
+| `-s, --source <path>` | Path to your Moodle source tree |
+| `-y, --yes` | Answer yes to every confirmation, including `stop` and `clean` |
+| `--local` | `doctor` only: skip the GitLab round trips |
+| `-V, --version` | Print the version |
+
+`--yes` has no bash equivalent. Bash defaulted every non-interactive confirmation to no, which made
+headless `stop` and `clean` abort unconditionally; the default here is still bash's, so nothing
+destructive happens without being asked for.
+
+### Exit codes
+
+| | |
+|---|---|
+| 0 | Success |
+| 1 | The action failed |
+| 2 | Bad usage — unknown action, or no TTY and no action |
+| 130 | Interrupted (Ctrl-C) |
+
+In the TUI, Ctrl-C is scoped to the running action: it ends a `logs` follow or a build and returns
+to the menu, and the session still exits 0. Bash exited 130 there.
+
+## The TUI
+
+Arrow keys and Enter, or the number the bash menu used — both, because a partner who has typed `3`
+without looking for a year should keep being right. Main menu: build, run, manage, sync data, sync
+plugins, check requirements, help, quit.
+
+`shell` hands the terminal over to `docker exec -it` and takes it back afterwards, so the container
+shell behaves like one you started yourself.
+
+## Workspace
+
+Everything persistent lives under `~/.moodle-workplace-packager/`:
+
+```
+repo/                                shallow clone of this repo, disposable
+data/<instance>/{moodle,mysql,logs}  persistent volumes, never disposable
+config.json                          remembered answers
+secrets.json                         0600, the Fluent Bit token
+packager.lock                        one instance at a time
+```
+
+Volumes are siblings of the clone, not children of it. The bash tool kept `.data/` inside the
+repository, which was safe only because the partner owned that checkout; this tool re-clones `repo/`
+on a version bump, so a MySQL data directory in there would be destroyed.
+
+Configuration still comes from `config.env` and `config.local.env` in the cloned repo, with the real
+environment winning over both. `WORKPLACE_PACKAGER_HOME` overrides the workspace root, which is what
+makes testing possible without touching a real one.
+
+## Development
+
+```bash
+cd cli
+npm install
+npm run typecheck
+npm test
+npm run build      # -> dist/index.mjs
+npm run size       # enforces the 5 MB npx budget
+node dist/index.mjs doctor
+```
+
+245 tests, including a dry-run diff harness that asserts the emitted `docker build` and `docker run`
+lines match `./moodle-partner`'s, and pty-driven tests of the exec handoff and Ctrl-C. The pty tests
+are POSIX-only — the Windows equivalents are hand-run.
+
+### Layout
+
+```
+src/
+  index.ts          entry: TTY? -> Ink app : headless dispatch
+  cli/args.ts       commander, parity with the bash actions
+  core/             no UI, no stdout
+  ui/               Ink components only
+  headless/         the same events as plain lines
+```
+
+**The one architectural rule:** every core function takes `{ emit, dryRun, signal }` and never
+writes to stdout. The TUI and the headless reporter are two subscribers to one typed event stream.
+That is what makes `--dry-run` testable and headless mode free rather than a second code path.
+
+### Two bundling traps
+
+Both cost real time to diagnose, and neither shows up until the bundle runs:
+
+- **`react-devtools-core`** — Ink imports it statically but it is not a real dependency. `tsup.config.ts`
+  aliases it to an empty stub. Marking it `--external` instead builds fine and then throws
+  `ERR_MODULE_NOT_FOUND` at runtime.
+- **The banner** — `ink-big-text` reads its font from `node_modules/cfonts/fonts/*.json` at runtime,
+  which does not exist inside a single bundled file. The wordmark in `src/ui/wordmark.ts` is figlet
+  "Standard" output, captured once and inlined, so no font is resolved at runtime at all.
+
+## Licence
+
+GPL-3.0-or-later, same as Moodle.