@abgov/nx-adsp 12.25.2 → 12.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abgov/nx-adsp",
-  "version": "12.25.2",
+  "version": "12.26.0",
   "license": "Apache-2.0",
   "main": "src/index.js",
   "description": "Government of Alberta - Nx plugin for ADSP apps.",

package/src/generators/angular-app/files/AGENTS.md__tmpl__

@@ -128,8 +128,8 @@ describe('MyFeatureComponent', () => {
 ## OpenShift targets
 
 ```bash
-nx run <%= projectName %>:sandbox           # build + push to OC internal registry + deploy
-nx run <%= projectName %>:sandbox-teardown  # remove sandbox resources
+nx run <%= projectName %>:sandbox           # build locally (podman) + push to GHCR + deploy
+nx run <%= projectName %>:sandbox-teardown  # remove sandbox resources + delete the GHCR image
 nx run <%= projectName %>:apply-envs        # apply manifests to all environments
 nx run <%= projectName %>:teardown-dev      # remove from dev environment
 ```
@@ -142,3 +142,29 @@ nx run <%= projectName %>:teardown-dev      # remove from dev environment
   silent SSO check on page load
 - `environments/environment.ts` — access URL and realm are pre-configured for
   the ADSP tenant; override at runtime via environment variables
+
+## Sandbox deployment (local build)
+
+The `sandbox` targets are added by the nx-oc sandbox generator — run it once per app first:
+
+```bash
+nx g @abgov/nx-oc:sandbox <%= projectName %> --sandboxProject <your-namespace>
+```
+
+Then `nx run <%= projectName %>:sandbox` builds the image **locally with podman**, pushes it to GHCR, and imports it into your sandbox namespace — no git push or CI wait. Prerequisites (one-time):
+
+- `podman` installed and running (`podman machine start` on macOS).
+- `oc` logged in, targeting your (per-user) sandbox namespace.
+- `gh auth login` as an account with **`write:packages`** on the registry org. That account must be the **active** `gh` account when you run the target — the sandbox reads `gh auth token` for both the image push and the pull secret (no PAT is stored). Check with `gh auth status`; switch with `gh auth switch -u <account>`.
+
+The registry (`ghcr.io/<org>`) is derived from the git remote on first run and saved in `nx.json`. The image is `<registry>/<sandboxProject>-<app>:sandbox` (namespace-prefixed to avoid collisions). If a push or import fails, it's almost always the active `gh` account lacking `write:packages` or access to the org — re-run after `gh auth switch`.
+
+### Verify & troubleshoot a sandbox deploy
+
+The target ends with `oc rollout status`. To confirm and diagnose:
+
+- **Health:** `oc get pods -n <namespace> -l name=<%= projectName %>` and `curl https://$(oc get route <%= projectName %> -n <namespace> -o jsonpath='{.spec.host}')/health`.
+- **Push or import failed:** almost always the active `gh` account lacks `write:packages` or access to the org — check `gh auth status`, then `gh auth switch -u <account>` and re-run.
+- **Pod CrashLoopBackOff / not ready:** `oc logs -n <namespace> <pod> -c <%= projectName %>`. For a service with a database, also check the migration init container: `oc logs -n <namespace> <pod> -c <%= projectName %>-migrate`.
+- **`podman` errors:** ensure the machine is running — `podman machine start` (macOS).
+- **Namespace missing:** create it with `oc new-project <namespace>`.

package/src/generators/express-service/files/AGENTS.md__tmpl__

@@ -318,8 +318,8 @@ nginx in production. All API routes live under `/<%= projectName %>/v1/`.
 ## OpenShift targets
 
 ```bash
-nx run <%= projectName %>:sandbox           # build + push to OC internal registry + deploy
-nx run <%= projectName %>:sandbox-teardown  # remove sandbox resources
+nx run <%= projectName %>:sandbox           # build locally (podman) + push to GHCR + deploy
+nx run <%= projectName %>:sandbox-teardown  # remove sandbox resources + delete the GHCR image
 nx run <%= projectName %>:apply-envs        # apply manifests to all environments
 nx run <%= projectName %>:teardown-dev      # remove from dev environment
 ```
@@ -332,3 +332,29 @@ nx run <%= projectName %>:teardown-dev      # remove from dev environment
 - `configurationHandler` on the API path — provides configuration service
   integration; keep it applied before route handlers
 - `createErrorHandler(logger)` — must remain the last `app.use()` call
+
+## Sandbox deployment (local build)
+
+The `sandbox` targets are added by the nx-oc sandbox generator — run it once per app first:
+
+```bash
+nx g @abgov/nx-oc:sandbox <%= projectName %> --sandboxProject <your-namespace>
+```
+
+Then `nx run <%= projectName %>:sandbox` builds the image **locally with podman**, pushes it to GHCR, and imports it into your sandbox namespace — no git push or CI wait. Prerequisites (one-time):
+
+- `podman` installed and running (`podman machine start` on macOS).
+- `oc` logged in, targeting your (per-user) sandbox namespace.
+- `gh auth login` as an account with **`write:packages`** on the registry org. That account must be the **active** `gh` account when you run the target — the sandbox reads `gh auth token` for both the image push and the pull secret (no PAT is stored). Check with `gh auth status`; switch with `gh auth switch -u <account>`.
+
+The registry (`ghcr.io/<org>`) is derived from the git remote on first run and saved in `nx.json`. The image is `<registry>/<sandboxProject>-<app>:sandbox` (namespace-prefixed to avoid collisions). If a push or import fails, it's almost always the active `gh` account lacking `write:packages` or access to the org — re-run after `gh auth switch`.
+
+### Verify & troubleshoot a sandbox deploy
+
+The target ends with `oc rollout status`. To confirm and diagnose:
+
+- **Health:** `oc get pods -n <namespace> -l name=<%= projectName %>` and `curl https://$(oc get route <%= projectName %> -n <namespace> -o jsonpath='{.spec.host}')/health`.
+- **Push or import failed:** almost always the active `gh` account lacks `write:packages` or access to the org — check `gh auth status`, then `gh auth switch -u <account>` and re-run.
+- **Pod CrashLoopBackOff / not ready:** `oc logs -n <namespace> <pod> -c <%= projectName %>`. For a service with a database, also check the migration init container: `oc logs -n <namespace> <pod> -c <%= projectName %>-migrate`.
+- **`podman` errors:** ensure the machine is running — `podman machine start` (macOS).
+- **Namespace missing:** create it with `oc new-project <namespace>`.

package/src/generators/react-app/files/AGENTS.md__tmpl__

@@ -117,8 +117,8 @@ describe('MyFeature', () => {
 ## OpenShift targets
 
 ```bash
-nx run <%= projectName %>:sandbox           # build + push to OC internal registry + deploy
-nx run <%= projectName %>:sandbox-teardown  # remove sandbox resources
+nx run <%= projectName %>:sandbox           # build locally (podman) + push to GHCR + deploy
+nx run <%= projectName %>:sandbox-teardown  # remove sandbox resources + delete the GHCR image
 nx run <%= projectName %>:apply-envs        # apply manifests to all environments
 nx run <%= projectName %>:teardown-dev      # remove from dev environment
 ```
@@ -131,3 +131,29 @@ nx run <%= projectName %>:teardown-dev      # remove from dev environment
   the ADSP tenant; override at runtime via deployment config
 - `silent-check-sso.html` — required for keycloak-js silent SSO; must be served
   from the app root
+
+## Sandbox deployment (local build)
+
+The `sandbox` targets are added by the nx-oc sandbox generator — run it once per app first:
+
+```bash
+nx g @abgov/nx-oc:sandbox <%= projectName %> --sandboxProject <your-namespace>
+```
+
+Then `nx run <%= projectName %>:sandbox` builds the image **locally with podman**, pushes it to GHCR, and imports it into your sandbox namespace — no git push or CI wait. Prerequisites (one-time):
+
+- `podman` installed and running (`podman machine start` on macOS).
+- `oc` logged in, targeting your (per-user) sandbox namespace.
+- `gh auth login` as an account with **`write:packages`** on the registry org. That account must be the **active** `gh` account when you run the target — the sandbox reads `gh auth token` for both the image push and the pull secret (no PAT is stored). Check with `gh auth status`; switch with `gh auth switch -u <account>`.
+
+The registry (`ghcr.io/<org>`) is derived from the git remote on first run and saved in `nx.json`. The image is `<registry>/<sandboxProject>-<app>:sandbox` (namespace-prefixed to avoid collisions). If a push or import fails, it's almost always the active `gh` account lacking `write:packages` or access to the org — re-run after `gh auth switch`.
+
+### Verify & troubleshoot a sandbox deploy
+
+The target ends with `oc rollout status`. To confirm and diagnose:
+
+- **Health:** `oc get pods -n <namespace> -l name=<%= projectName %>` and `curl https://$(oc get route <%= projectName %> -n <namespace> -o jsonpath='{.spec.host}')/health`.
+- **Push or import failed:** almost always the active `gh` account lacks `write:packages` or access to the org — check `gh auth status`, then `gh auth switch -u <account>` and re-run.
+- **Pod CrashLoopBackOff / not ready:** `oc logs -n <namespace> <pod> -c <%= projectName %>`. For a service with a database, also check the migration init container: `oc logs -n <namespace> <pod> -c <%= projectName %>-migrate`.
+- **`podman` errors:** ensure the machine is running — `podman machine start` (macOS).
+- **Namespace missing:** create it with `oc new-project <namespace>`.

package/src/generators/vue-app/files/AGENTS.md__tmpl__

@@ -136,8 +136,8 @@ describe('MyComponent', () => {
 ## OpenShift targets
 
 ```bash
-nx run <%= projectName %>:sandbox           # build + push to OC internal registry + deploy
-nx run <%= projectName %>:sandbox-teardown  # remove sandbox resources
+nx run <%= projectName %>:sandbox           # build locally (podman) + push to GHCR + deploy
+nx run <%= projectName %>:sandbox-teardown  # remove sandbox resources + delete the GHCR image
 nx run <%= projectName %>:apply-envs        # apply manifests to all environments
 nx run <%= projectName %>:teardown-dev      # remove from dev environment
 ```
@@ -148,3 +148,29 @@ nx run <%= projectName %>:teardown-dev      # remove from dev environment
 - `environments/environment.ts` — access URL and realm are pre-configured for the ADSP tenant
 - `silent-check-sso.html` — required for keycloak-js silent SSO; must be served from the app root
 - `vite.config.ts` — the `isCustomElement` predicate must stay to suppress Vue warnings for `goa-*` elements
+
+## Sandbox deployment (local build)
+
+The `sandbox` targets are added by the nx-oc sandbox generator — run it once per app first:
+
+```bash
+nx g @abgov/nx-oc:sandbox <%= projectName %> --sandboxProject <your-namespace>
+```
+
+Then `nx run <%= projectName %>:sandbox` builds the image **locally with podman**, pushes it to GHCR, and imports it into your sandbox namespace — no git push or CI wait. Prerequisites (one-time):
+
+- `podman` installed and running (`podman machine start` on macOS).
+- `oc` logged in, targeting your (per-user) sandbox namespace.
+- `gh auth login` as an account with **`write:packages`** on the registry org. That account must be the **active** `gh` account when you run the target — the sandbox reads `gh auth token` for both the image push and the pull secret (no PAT is stored). Check with `gh auth status`; switch with `gh auth switch -u <account>`.
+
+The registry (`ghcr.io/<org>`) is derived from the git remote on first run and saved in `nx.json`. The image is `<registry>/<sandboxProject>-<app>:sandbox` (namespace-prefixed to avoid collisions). If a push or import fails, it's almost always the active `gh` account lacking `write:packages` or access to the org — re-run after `gh auth switch`.
+
+### Verify & troubleshoot a sandbox deploy
+
+The target ends with `oc rollout status`. To confirm and diagnose:
+
+- **Health:** `oc get pods -n <namespace> -l name=<%= projectName %>` and `curl https://$(oc get route <%= projectName %> -n <namespace> -o jsonpath='{.spec.host}')/health`.
+- **Push or import failed:** almost always the active `gh` account lacks `write:packages` or access to the org — check `gh auth status`, then `gh auth switch -u <account>` and re-run.
+- **Pod CrashLoopBackOff / not ready:** `oc logs -n <namespace> <pod> -c <%= projectName %>`. For a service with a database, also check the migration init container: `oc logs -n <namespace> <pod> -c <%= projectName %>-migrate`.
+- **`podman` errors:** ensure the machine is running — `podman machine start` (macOS).
+- **Namespace missing:** create it with `oc new-project <namespace>`.