Merge pull request #90 from edgehero/feat/github-app-manifest-setup

setup overhaul: up/doctor --fix, service, npm publish, compose receiver, App-manifest setup, polling (#80 #81 #82)

Author: edgehero

.dockerignore

@@ -0,0 +1,58 @@
+# Every image here builds with the REPO ROOT as context (image/Dockerfile, image/Dockerfile.azure,
+# receiver/Dockerfile), so without this file each build ships the whole working tree to the daemon --
+# node_modules alone is ~350 MB of upload before the first layer runs.
+#
+# Patterns are ANCHORED to the context root (dockerignore is filepath.Match, not gitignore): `docs`
+# matches only ./docs, and matching node_modules at any depth needs the explicit `**/`.
+#
+# What must STAY in the context is defined by the Dockerfiles' COPY lines:
+#   image/Dockerfile:    package.json, package-lock.json, image/runner, image/entrypoint.sh, guardrails/
+#   receiver/Dockerfile: package.json, package-lock.json, .npmrc, worker/{package.json,src},
+#                        receiver/{package.json,src}
+# image/ is therefore NOT excluded wholesale -- the pi-job build copies image/runner verbatim (its test/
+# included; excluding it would silently change that image's contents), and guardrails/ is the baked
+# safety floor. Anything below is copied by no Dockerfile and never may be.
+
+# Installed deps -- each image runs its own `npm ci` from the lockfile; a host node_modules in the
+# context is pure upload weight and a platform mismatch waiting to be COPY'd by accident.
+**/node_modules
+
+# History and CI config: builds consume the working tree, never the repo.
+.git
+.github
+
+# Docs, specs, planning, editor/agent tooling -- prose and provenance, not runtime.
+docs
+specs
+examples
+.plan-artifacts
+.pi
+.claude
+README.md
+SECURITY.md
+LICENSE
+
+# The admin workspace: a pi extension in the operator's session (DES-ADMIN-VIA-PI-EXTENSION);
+# no image runs it.
+admin
+
+# Deploy templates (systemd/launchd/nssm/compose) configure the HOST, not a container.
+deploy
+
+# Tests for the workspaces whose src is copied. image/runner/test is deliberately NOT listed:
+# image/Dockerfile copies image/runner as a whole, and the ignore file must not edit that image.
+worker/test
+receiver/test
+
+# Secrets and operator-local state. The .env never enters an image -- compose hands it to the
+# CONTAINER via env_file; a real secret in a LAYER is published with the image.
+.env
+.env.*
+triggers.json
+pause-windows.json
+pi-packages.json
+subscriptions.json
+logs
+jobs
+sessions
+**/*.log

.env.example

@@ -97,6 +97,7 @@ GITHUB_AUTH_SOURCE=gh
 # For GITHUB_AUTH_SOURCE=pat: a repo-scoped, short-expiry fine-grained PAT
 GITHUB_PAT=
 # For GITHUB_AUTH_SOURCE=app (optional; required for multi-tenant)
+# `pi-dispatch setup github` fills all three in one browser click (App Manifest flow) and writes the PEM 0600
 GITHUB_APP_ID=
 GITHUB_APP_INSTALLATION_ID=
 GITHUB_APP_PRIVATE_KEY_PATH=

.github/workflows/receiver-image.yml

@@ -0,0 +1,73 @@
+# Build and publish the receiver image to GHCR so operators `docker compose --profile receiver up` a
+# prebuilt multi-arch image instead of building locally. main is branch-protected (PR + 1 approving
+# review), so a push here is an already-approved merge — nothing in this workflow merges anything
+# (CONST-MERGE-NEVER-AUTOMATIC).
+#
+# The pushed image is a snapshot of the receiver AND the worker sources it imports (`@edgehero/pi-dispatch`
+# is a workspace dependency) at the built commit — hence the worker paths in the trigger: a change to a
+# shared module the receiver imports must rebuild this image even when receiver/ itself is untouched.
+#
+# No secret required: GHCR auth uses the built-in GITHUB_TOKEN (packages: write). One-time after the first
+# successful run: make the ghcr.io/edgehero/pi-dispatch-receiver package Public in the org's package
+# settings, otherwise `docker pull` needs auth.
+
+name: receiver-image
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "receiver/**"
+      - "worker/src/**"
+      - "worker/package.json"
+      - "package-lock.json"
+      - ".github/workflows/receiver-image.yml"
+  # Manual re-run (available once this file is on the default branch).
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+  packages: write # push to ghcr.io/edgehero/*
+
+concurrency:
+  group: receiver-image
+  cancel-in-progress: false
+
+env:
+  IMAGE: ghcr.io/edgehero/pi-dispatch-receiver
+
+jobs:
+  build-push:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: docker/setup-qemu-action@v3 # arm64 emulation for the multi-arch build
+      - uses: docker/setup-buildx-action@v3
+
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Tags + labels
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.IMAGE }}
+          tags: |
+            type=raw,value=latest
+            type=sha
+
+      - name: Build + push (amd64 + arm64)
+        uses: docker/build-push-action@v6
+        with:
+          context: . # repo root — the Dockerfile copies worker/ and receiver/ workspace sources from here
+          file: receiver/Dockerfile
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max