@axinom/mosaic-agent-skills 0.4.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axinom/mosaic-agent-skills",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "MCP server bundled with Mosaic development skills and tools for AI agents",
   "bin": "./dist/index.js",
   "files": [
@@ -36,5 +36,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "7f614a26d23fbd7e917653b42f234f9ba51f6580"
+  "gitHead": "8e28563eaafe8791244c3eebdb9da64b8e400c0c"
 }

package/skills/deploy-service/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: deploy-service
+description: |
+  Deploys a custom service from a Mosaic monorepo to the Axinom Mosaic
+  Hosting Service. Covers the full lifecycle: authenticating, discovering
+  deployable services, verifying one-time prerequisites (container registry,
+  service definition), building and pushing a Docker image, optionally
+  building and registering a microfrontend pilet, uploading a deployment
+  manifest, initiating a rolling deployment, and monitoring status with
+  log-based error diagnosis.
+
+  Use this skill whenever the user wants to deploy, redeploy, or release a
+  service to the Mosaic Hosting Service — including first-time deployments,
+  updating a running service, or recovering from a failed deployment.
+allowed-tools:
+  - list_skills
+  - get_skill
+  - get_skill_references
+  - execute_skill
+---
+
+# Deploy Service to Mosaic Hosting
+
+## Input
+
+Service name or ID (e.g. "media", "media-service"). If omitted, discover
+and ask.
+
+## Overview
+
+Each deployment is a tuple of: container image + deployment manifest +
+optional pilet (only for services with a `workflows/` folder). Deployments
+are additive — each supersedes the previous; reusing an existing image,
+pilet, or manifest in a new deployment is always valid.
+
+### API vs CLI
+
+| Action | Use |
+|--------|-----|
+| Auth token, registry/service-definition check & create | API |
+| Docker build & push | shell |
+| Pilet build, pack & register | CLI (file upload) |
+| Manifest upload | CLI — preserves `${__ax_hosted__.dynamic.%}` secret injection |
+| Deployment initiation | CLI — name-based, no UUID lookups |
+| Status polling, log fetching, DNS endpoints | API |
+
+Retrieve all reference files with `get_skill_references` before starting.
+For API calls, use Node.js with `--input-type=commonjs` to avoid ESM/CJS
+conflicts. Pattern:
+
+```bash
+node --input-type=commonjs <<'EOF'
+const https = require('https');
+const fs = require('fs');
+// ... make request, write result to file
+EOF
+```
+
+Save the token to `.jwt` and reuse it.
+
+## Steps
+
+### 0. Authenticate → `refs/credentials-and-setup.md`
+
+Read credentials from root `.env`, obtain a token, save to `.jwt`.
+
+### 1. Discover & Select Service
+
+Scan `services/*/service/mosaic-hosting-deployment-manifest.yaml`. For each,
+read `serviceId` from the YAML and note whether a sibling `workflows/` folder
+exists (`hasWorkflows`).
+
+Ask the user to choose if not already specified.
+
+### 2. Prerequisites → `refs/credentials-and-setup.md`
+
+Check (and create if missing) the container registry connection and service
+definition via API. Both are one-time per environment/service.
+
+### 3. Backend Image → `refs/build-and-push-image.md`
+
+*Does the backend need updating?* Yes → build & push, get `imageTag`.
+No → ask for the existing tag to reuse.
+
+### 4. Pilet (skip if `hasWorkflows` is false) → `refs/build-and-register-pilet.md`
+
+*Does the frontend need updating?* Yes → build, pack & register via CLI.
+No → confirm the existing `piletRef` to reuse.
+
+### 5. Manifest → `refs/manifest-review-and-upload.md`
+
+Ask if any manifest changes are needed. If changes are required, review and
+upload a new named manifest. If the manifest is unchanged, the user may select
+an existing one and skip the upload — each deployment just needs a valid
+`manifestName`, whether new or reused.
+
+### 6. Deploy & Monitor → `refs/deploy-and-monitor.md`
+
+Initiate via CLI, parse `serviceDeploymentId` from the output, poll status
+via API. On `READY` show DNS endpoints. On `CREATE_ERROR` fetch logs,
+diagnose, and either fix the manifest and redeploy, or hand off to the user.
+
+Once the deployment resolves (success or terminal error), delete `.jwt`.

package/skills/deploy-service/refs/build-and-push-image.md

@@ -0,0 +1,55 @@
+---
+name: build-and-push-image
+input:
+  - registryHost, repositoryName (from service definition)
+  - servicePath (e.g. services/media/service)
+  - buildScript (e.g. build:media-service:prod)
+output:
+  - imageTag (YYYYMMDD.N — passed as -t to the deploy command)
+---
+
+# Build & Push Container Image
+
+## Existing Images
+
+`repositoryTags` on the service definition lists all pushed images, sorted
+newest first (tags are `YYYYMMDD.N`, so alpha order = chronological):
+
+```graphql
+# POST {HOSTING_SERVICE_BASE_URL}/graphql
+query {
+  serviceDefinitions(condition: { serviceId: "{serviceId}" }) {
+    nodes {
+      repositoryTags { fullyQualifiedImageName containerImageVersion }
+    }
+  }
+}
+```
+
+Present as a numbered list (newest first) with `[0] Build & push a new image` as the last option. Wait for the user to pick by number — never ask them to type a tag manually.
+
+## Build & Push
+
+Check Docker login: `docker info` (look for `Username:`). If not logged in:
+```bash
+docker login {registryHost}
+```
+Fallback: check `~/.docker/config.json` or `~/snap/docker/current/.docker/config.json`.
+
+Dockerfile is typically at the repo root. If not, search and confirm with the user.
+
+Tag pattern: `YYYYMMDD.N` (e.g. `20260423.1`, increment `.N` for same-day builds).
+The Hosting Service appends this to `{registryHost}/{repositoryName}:` — pass only
+the date+index as `-t` to the deploy command, not the full reference.
+
+Run from **repo root**:
+```bash
+docker build \
+  -t {registryHost}/{repositoryName}:{imageTag} \
+  --build-arg PACKAGE_ROOT={servicePath} \
+  --build-arg PACKAGE_BUILD_COMMAND={buildScript} \
+  --platform linux/amd64 \
+  .
+
+docker push {registryHost}/{repositoryName}:{imageTag}
+```

package/skills/deploy-service/refs/build-and-register-pilet.md

@@ -0,0 +1,54 @@
+---
+name: build-and-register-pilet
+input:
+  - serviceId
+  - workflowsPath (e.g. services/media/workflows)
+output:
+  - piletRef = {piletName}@{piletVersion} (passed as -p to the deploy command)
+---
+
+# Build & Register Pilet
+
+## Existing Pilets
+
+```graphql
+# POST {HOSTING_SERVICE_BASE_URL}/graphql
+query {
+  servicePiletArtifacts(
+    filter: { serviceId: { equalTo: "{serviceId}" } }
+    orderBy: CREATED_DATE_DESC
+    first: 5
+  ) {
+    nodes { name packageVersion createdDate }
+  }
+}
+```
+
+Present results as a numbered list (`{name}@{packageVersion}`, newest first) with `[0] Build & register a new pilet` as the last option. Wait for the user to pick by number. The chosen value is passed as `-p` to the deploy command.
+
+## Build & Register
+
+Read `name` and `version` from `{workflowsPath}/package.json` — these form
+the pilet reference `{piletName}@{piletVersion}` used in the deploy command.
+
+```bash
+cd {workflowsPath} && yarn build && yarn pilet pack
+```
+
+Locate the produced `.tgz`:
+```bash
+find {workflowsPath} -maxdepth 1 -name "*.tgz"
+```
+
+Use the path returned by `find` directly as `{tgzPath}`.
+
+If `{piletName}@{piletVersion}` already appears in the existing pilets list,
+warn the user that it will be overwritten and ask for confirmation before proceeding.
+
+Register (requires `MICRO_FRONTEND_SERVICE_BASE_URL` in root `.env`):
+```bash
+yarn util:load-vars mosaic hosting pilet register \
+  -i {serviceId} \
+  -p {tgzPath} \
+  --overrideRegistration
+```

package/skills/deploy-service/refs/credentials-and-setup.md

@@ -0,0 +1,88 @@
+---
+name: credentials-and-setup
+input:
+  - serviceId
+  - root .env (MOSAIC_HOSTING_CLIENT_ID, MOSAIC_HOSTING_CLIENT_SECRET, ID_SERVICE_AUTH_BASE_URL, HOSTING_SERVICE_BASE_URL)
+output:
+  - access token in .jwt
+  - registryHost, registryUsername confirmed
+  - serviceDefinitionId, repositoryName confirmed
+---
+
+# Credentials & Prerequisites
+
+## Token
+
+If `MOSAIC_HOSTING_CLIENT_ID` or `MOSAIC_HOSTING_CLIENT_SECRET` are missing
+from root `.env`, check whether a setup script exists:
+
+```bash
+# Check for a hosting setup script (name may vary per repo)
+grep -r "setup.*hosting\|hosting.*setup" package.json scripts/ 2>/dev/null | head -5
+```
+
+If a setup script is found (e.g. `yarn setup:hosting`), run it. It typically
+requires `DEV_SERVICE_ACCOUNT_CLIENT_ID` and `DEV_SERVICE_ACCOUNT_CLIENT_SECRET`
+to already be in `.env` — if those are also missing, stop and ask the user.
+
+If no setup script exists, ask the user to provide `MOSAIC_HOSTING_CLIENT_ID`
+and `MOSAIC_HOSTING_CLIENT_SECRET` directly and add them to `.env`.
+
+```graphql
+# POST {ID_SERVICE_AUTH_BASE_URL}/graphql  (no auth required)
+mutation {
+  authenticateServiceAccount(input: {
+    clientId: "{MOSAIC_HOSTING_CLIENT_ID}"
+    clientSecret: "{MOSAIC_HOSTING_CLIENT_SECRET}"
+  }) { accessToken }
+}
+```
+
+Save `accessToken` to `.jwt`. All subsequent calls use
+`Authorization: Bearer {token}`. On 401, re-fetch and overwrite.
+
+## Container Registry
+
+The Hosting Service constructs image references as
+`{registryHost}/{repositoryName}:{imageTag}`.
+
+```graphql
+# POST {HOSTING_SERVICE_BASE_URL}/graphql
+{ containerRegistryConnections { nodes { id host username } } }
+```
+
+If connections exist, confirm which one with the user. If none, ask for
+host/username/password then:
+
+```graphql
+mutation {
+  createContainerRegistryConnection(input: {
+    containerRegistryConnection: { host: "...", username: "...", password: "..." }
+  }) { containerRegistryConnection { id host username } }
+}
+```
+
+## Service Definition
+
+```graphql
+{ serviceDefinitions(condition: { serviceId: "{serviceId}" }) {
+    nodes { id serviceId repositoryName activeDeploymentStatus }
+} }
+```
+
+If found, proceed. If not, suggest `{registryUsername}/{serviceId}` as
+`repositoryName`, confirm with user, then:
+
+```graphql
+mutation {
+  createServiceDefinition(input: {
+    serviceDefinition: {
+      serviceId: "{serviceId}"
+      name: "{serviceId}"
+      repositoryName: "{registryUsername}/{serviceId}"
+    }
+  }) { serviceDefinition { id repositoryName } }
+}
+```
+
+> Avoid `ax-` or `axinom-` prefixes in serviceId — reserved for Axinom Owned services.

package/skills/deploy-service/refs/deploy-and-monitor.md

@@ -0,0 +1,76 @@
+---
+name: deploy-and-monitor
+input:
+  - serviceId, imageTag, manifestName, piletRef = {piletName}@{piletVersion} (optional)
+  - HOSTING_SERVICE_BASE_URL + token from .jwt
+output:
+  - serviceDeploymentId, status, DNS endpoints
+---
+
+# Deploy & Monitor
+
+## Initiate via CLI
+
+```bash
+# with pilet
+yarn util:load-vars mosaic hosting service deploy \
+  -i {serviceId} -t {imageTag} -p {piletRef} \
+  -m {manifestName} -n {serviceId}-deployment-{YYYYMMDD}.N
+
+# without pilet
+yarn util:load-vars mosaic hosting service deploy \
+  -i {serviceId} -t {imageTag} \
+  -m {manifestName} -n {serviceId}-deployment-{YYYYMMDD}.N
+```
+
+Use today's date for the deployment name. Increment `.N` if multiple deployments are made on the same day.
+
+The CLI prints human-readable status lines followed by a JSON object. Extract the
+JSON by finding the line that starts with `{` and parse `serviceDeploymentId` from it:
+```json
+{"serviceDeploymentId":"<uuid>","name":"...","status":"CREATE_PENDING"}
+```
+
+Use this ID for all subsequent queries. Do not query by `last: 1` ordering —
+stale failed deployments from prior runs can appear ahead of the new one.
+
+## Poll Status
+
+Poll every ~15s until status is no longer `CREATE_PENDING`:
+
+```graphql
+# POST {HOSTING_SERVICE_BASE_URL}/graphql
+query($id: UUID!) {
+  serviceDeployment(id: $id) {
+    status
+    errorMessage
+    dnsRecords { nodes { configRefName fqdn } }
+  }
+}
+# variables: {"id": "{serviceDeploymentId}"}
+```
+
+**`READY`** — show DNS endpoints (each `configRefName` maps to a port in
+`dnsMappedPorts` in the manifest):
+```
+API: https://{fqdn}   (configRefName = "api")
+```
+
+**`CREATE_ERROR`** — fetch logs (`SERVICE_DEPLOYMENTS_VIEW` permission required):
+
+```graphql
+# POST {HOSTING_SERVICE_BASE_URL}/graphql
+query($c: ServiceDeploymentLogCondition) {
+  serviceDeploymentLogs(condition: $c, orderBy: TIMESTAMP_ASC) {
+    nodes { messageType message timestamp }
+  }
+}
+# variables: {"c": {"serviceDeploymentId": "{serviceDeploymentId}"}}
+```
+
+- **Config/manifest error** → fix the YAML, re-upload with an incremented
+  tag (e.g. `20260423.2`), re-deploy reusing the same `imageTag` and `piletRef`
+- **Code/runtime error** → tell the user; do not retry until they push a fix,
+  then restart from the image build step
+
+Always use a new deployment name — never modify an existing deployment.

package/skills/deploy-service/refs/manifest-review-and-upload.md

@@ -0,0 +1,63 @@
+---
+name: manifest-review-and-upload
+input:
+  - serviceId
+  - manifestPath (absolute path to mosaic-hosting-deployment-manifest.yaml)
+  - servicePath (for .env.template comparison)
+  - imageTag (used as uniqueTag for the manifest name)
+output:
+  - manifestName (e.g. media-service-manifest-20260423.1 — passed as -m to
+    deploy)
+---
+
+# Manifest Review & Upload
+
+## Existing Manifests
+
+```graphql
+# POST {HOSTING_SERVICE_BASE_URL}/graphql
+query {
+  serviceDeploymentManifests(
+    filter: { serviceId: { equalTo: "{serviceId}" } }
+    orderBy: CREATED_DATE_DESC
+    first: 5
+  ) {
+    nodes {
+      name
+      createdDate
+    }
+  }
+}
+```
+
+Present as a numbered list (newest first) with `[0] Upload a new manifest` as the last option. Wait for the user to pick by number — never ask them to type a name manually. If the user picks an existing manifest, skip the upload step and use that name directly.
+
+## Review
+
+**Unresolved placeholders:** search for `REPLACE_WITH_VALID_` — stop and ask the
+user to fill these in before uploading.
+
+**Missing variables:** compare variable names in `{servicePath}/.env.template`
+against `regularVariables` + `secureVariables` in the manifest. Surface any gaps
+to the user (skip obviously dev-only vars like `GRAPHQL_GUI_ENABLED`).
+
+**Secrets:** sensitive values can be injected at upload time without being
+hardcoded in the YAML:
+
+```yaml
+secureVariables:
+  MY_SECRET: ${__ax_hosted__.dynamic.MY_SECRET}
+```
+
+`yarn util:load-vars` feeds root `.env` into the environment before the CLI
+runs, making those values available for substitution. This is why manifest
+upload must use the CLI and not the API directly.
+
+## Upload
+
+```bash
+yarn util:load-vars mosaic hosting manifest upload \
+  -i {serviceId} \
+  -p {manifestPath} \
+  -n {serviceId}-manifest-{imageTag}
+```