portta 0.8.0

package/dist/runtime/templates/project/PORTTA.md

@@ -0,0 +1,107 @@
+# Running this project on Portta
+
+> Copy this file into the project and adjust the names. It covers only what
+> someone working on *this* project needs. The rules themselves live in the Dev
+> Gateway repository, which stays the single source of truth.
+
+## Prerequisites
+
+Portta must be running on this machine:
+
+```bash
+portta status      # if this fails: portta bootstrap && portta up local
+```
+
+## Starting
+
+```bash
+docker compose -f compose.yaml -f compose.portta.yaml up -d
+```
+
+Set `COMPOSE_FILE=compose.yaml:compose.portta.yaml` in `.env` to drop the
+`-f` flags.
+
+## Namespace
+
+`COMPOSE_PROJECT_NAME` is what keeps this environment separate from every other
+one on the host: containers, network, volumes and hostnames all derive from it.
+
+```env
+# .env
+COMPOSE_PROJECT_NAME=<project>
+```
+
+## URLs
+
+```bash
+portta urls --project <project>
+```
+
+| Service | URL |
+|---|---|
+| web | `http://<project>-web.localhost` |
+| api | `http://<project>-api.localhost` |
+
+No port numbers, and no host port is published for either.
+
+## Database and cache
+
+Not published on the host. Two ways in:
+
+**From inside the project**, with nothing to open and nothing to close:
+
+```bash
+docker compose exec postgres psql -U <user> -d <db>
+docker compose exec redis redis-cli
+```
+
+**From a GUI on the host**, through a temporary loopback bridge on a free port:
+
+```bash
+portta access open --project <project> --service postgres
+# -> 127.0.0.1:55431
+
+portta access list
+portta access close --project <project>
+```
+
+Point TablePlus, DBeaver or DataGrip at `127.0.0.1` and the port it printed.
+Credentials are this project's, from its own `.env`.
+
+## Working on two branches at once
+
+```bash
+git worktree add ../<project>-issue59 issue59
+cd ../<project>-issue59
+echo "COMPOSE_PROJECT_NAME=<project>-issue59" >> .env
+docker compose -f compose.yaml -f compose.portta.yaml up -d
+# -> http://<project>-issue59-web.localhost
+```
+
+Both run at once, each with its own database. The first environment is not
+affected.
+
+## Troubleshooting
+
+```bash
+portta doctor
+portta urls --project <project>
+docker compose logs -f
+```
+
+**404**: the service did not opt in, or Traefik has not discovered it yet.
+**502**: the route matched but the backend did not answer, usually the wrong
+port in the overlay, or the service is not on the `portta` network.
+
+More: Portta's `docs/product/guides/troubleshooting.md`.
+
+## Without the gateway
+
+The overlay only adds networks and labels, so the project still runs on its own:
+
+```bash
+docker compose up -d
+```
+
+You lose hostname routing, so you will need published ports. Put those in your
+personal `compose.override.yaml`, not in the shared files.

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "portta",
+  "version": "0.8.0",
+  "description": "Machine-first CLI for a shared Docker development gateway",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "portta": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "node --import tsx scripts/build.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run typecheck && npm test",
+    "preversion": "node scripts/git-version.mjs check",
+    "version": "node scripts/git-version.mjs sync",
+    "postversion": "node scripts/git-version.mjs verify"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fabioassuncao/portta.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/fabioassuncao/portta#readme",
+  "bugs": "https://github.com/fabioassuncao/portta/issues",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "commander": "14.0.2",
+    "execa": "9.6.1",
+    "systeminformation": "^5.33.8",
+    "zod": "4.5.4"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "esbuild": "0.28.2",
+    "portta-contracts": "0.1.0",
+    "portta-core": "0.1.0",
+    "typescript": "7.0.2",
+    "vitest": "4.1.11",
+    "tsx": "4.23.13"
+  }
+}