retold-facto 0.2.0 → 1.0.0

package/.github/workflows/publish-image.yml

@@ -0,0 +1,66 @@
+# Publish a container image to GitHub Container Registry on every
+# version tag push (e.g. `v1.2.3`). Generated by `quack docker-init`.
+#
+# Image lands at:
+#   ghcr.io/stevenvelozo/retold-facto:<version>
+#   ghcr.io/stevenvelozo/retold-facto:latest   (only on stable tags)
+
+name: Publish container image
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Tag to apply (e.g. dev or 1.2.3-test). `latest` is reserved for stable tag pushes.'
+        required: true
+        default: 'dev'
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up QEMU (multi-arch support)
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Compute image tags
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository_owner }}/retold-facto
+          tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+            type=raw,value=${{ github.event.inputs.tag }},enable=${{ github.event_name == 'workflow_dispatch' }}
+
+      - name: Build and push
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: ./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

package/BUILDING-AND-PUBLISHING.md

@@ -0,0 +1,140 @@
+# Building and Publishing
+
+How to ship `retold-facto` to npm and to GitHub Container Registry
+(GHCR). Generated by `quack docker-init`; the structure matches the
+shared template across all dockerized retold tools.
+
+`retold-facto` is a **long-running service**. Restart policy in compose / k8s should be `unless-stopped` (or equivalent). The Dockerfile should declare a HEALTHCHECK against the service's health endpoint.
+
+---
+
+## TL;DR
+
+```bash
+# npm-only release (the default — most common case)
+npm run release:patch
+
+# npm release that ALSO rebuilds the GHCR image
+npm run release:patch:image
+```
+
+The default release is npm-only. Docker images are deliberate, opt-in
+artifacts because each multi-arch build burns several minutes of CI
+time. Use `:image` (or set `BUILD_DOCKER=1`) when runtime code,
+dependencies, env-var contract, or the Dockerfile changed.
+
+---
+
+## Prerequisites (one-time setup)
+
+- **npm login** — `npm whoami` should print your username.
+- **Git remote configured** — `git remote get-url origin` should print
+  `git@github.com:stevenvelozo/retold-facto.git` (or the
+  HTTPS equivalent).
+- **Push access to the repo** — required so `postversion` /
+  `postpublish` hooks can push commits and tags.
+- **Docker** (only if you want to test the image locally before tag).
+
+---
+
+## Ecosystem convention: lockfiles are gitignored
+
+`package-lock.json` is in this repo's `.gitignore` (Quackage convention
+shared across the retold ecosystem). The Dockerfile must use `npm install`,
+not `npm ci` — `npm ci` requires the lockfile to be in the build context
+and CI runners only check out what's in git. If you see EUSAGE errors in
+GHCR build logs, change `RUN npm ci` to `RUN npm install` in the
+Dockerfile.
+
+---
+
+## Releasing
+
+| Command                              | npm registry | GHCR image rebuild |
+|--------------------------------------|--------------|--------------------|
+| `npm run release:patch`              | yes          | no                 |
+| `npm run release:patch:image`        | yes          | yes                |
+| `npm run release:minor`              | yes          | no                 |
+| `npm run release:minor:image`        | yes          | yes                |
+| `npm run release:major`              | yes          | no                 |
+| `npm run release:major:image`        | yes          | yes                |
+
+The non-`:image` variants are the default because most patch releases
+don't change runtime behavior. The `:image` variants tell the pipeline
+"this release does change runtime — build me a new image."
+
+### Direct CLI (also works)
+
+```bash
+npm publish                              # npm only
+npm run publish:docker                   # npm + docker (sets BUILD_DOCKER=1)
+```
+
+### From `retold-manager` TUI
+
+- `[!]` Publish — npm only
+- `[D]` Publish with docker image — npm + GHCR build
+
+### Promoting a previous npm release to docker later
+
+If you released `v<x>` to npm only, then later decide you do want a
+docker image:
+
+```bash
+git push origin v<x>    # pushes the local tag → GHCR fires
+```
+
+The local tag is still sitting there from the original `npm version`
+step. Pushing it triggers the workflow without touching npm.
+
+---
+
+## The chain
+
+The lifecycle hooks all live in `package.json` and delegate to
+`npx quack release …`. Default path (`BUILD_DOCKER` unset):
+
+```
+npm publish
+  → prepublishOnly: npm test                     ← test gate
+  → publish to npm
+  → postpublish: BUILD_DOCKER unset → no-op      ← image NOT triggered
+```
+
+Docker-included path (`BUILD_DOCKER=1`):
+
+```
+BUILD_DOCKER=1 npm publish    (or: npm run publish:docker)
+  → prepublishOnly: npm test
+  → publish to npm
+  → postpublish: BUILD_DOCKER=1 → tag + push     ← image trigger
+  → .github/workflows/publish-image.yml fires
+  → docker buildx build linux/amd64,linux/arm64
+  → docker push ghcr.io/stevenvelozo/retold-facto:<version>
+```
+
+---
+
+## Verifying a release
+
+1. **npm**: `npm view retold-facto version`
+2. **Workflow**: `https://github.com/stevenvelozo/retold-facto/actions`
+3. **Image**: `docker pull ghcr.io/stevenvelozo/retold-facto:latest`
+
+If the first `docker pull` returns `denied`, the package is private by
+default — flip visibility to public via Package Settings → Danger Zone
+on the package page.
+
+---
+
+## Image consumption
+
+```bash
+docker pull ghcr.io/stevenvelozo/retold-facto:latest
+docker run --rm ghcr.io/stevenvelozo/retold-facto:latest
+```
+
+Configuration via env vars: see this module's README for the supported
+`<MODULE>_*` variables. Any secret-bearing var also accepts `<NAME>_FILE`
+pointing at a file whose contents become the value (mysql/postgres
+convention; works with docker secrets and k8s Secrets).

package/Dockerfile

@@ -2,7 +2,10 @@
 FROM node:20-slim AS builder
 WORKDIR /app
 COPY package*.json ./
-RUN npm ci
+# `npm install`, not `npm ci` — package-lock.json is gitignored per
+# the Quackage convention shared across the retold ecosystem, so the
+# build context never has it. See BUILDING-AND-PUBLISHING.md.
+RUN npm install
 COPY .quackage.json ./
 COPY source/ source/
 COPY bin/ bin/
@@ -16,7 +19,7 @@ RUN cp node_modules/pict/dist/pict.min.js source/services/web-app/web/pict.min.j
 FROM node:20-slim
 WORKDIR /app
 COPY package*.json ./
-RUN npm ci --omit=dev
+RUN npm install --omit=dev
 COPY --from=builder /app/source/ source/
 COPY --from=builder /app/bin/ bin/
 COPY --from=builder /app/test/model/ test/model/

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "retold-facto",
-	"version": "0.2.0",
+	"version": "1.0.0",
 	"description": "Data warehouse and knowledge graph storage for the Retold ecosystem.",
 	"main": "source/Retold-Facto.js",
 	"bin": {
@@ -15,7 +15,17 @@
 		"build-codemirror": "npx esbuild source/services/web-app/codemirror-entry.js --bundle --outfile=source/services/web-app/web/codemirror-bundle.js --format=iife --global-name=CodeMirrorModules --platform=browser --target=es2018",
 		"build-test-model": "cd test && npx stricture -i model/ddl/Facto.ddl",
 		"docker-build": "docker build -t retold-facto .",
-		"docker-run": "docker run -p 8386:8386 retold-facto"
+		"docker-run": "docker run -p 8386:8386 retold-facto",
+		"prepublishOnly": "npm test",
+		"postversion": "npx quack release postversion",
+		"postpublish": "npx quack release postpublish",
+		"publish:docker": "npx quack release publish --image",
+		"release:patch": "npx quack release patch",
+		"release:minor": "npx quack release minor",
+		"release:major": "npx quack release major",
+		"release:patch:image": "npx quack release patch --image",
+		"release:minor:image": "npx quack release minor --image",
+		"release:major:image": "npx quack release major --image"
 	},
 	"mocha": {
 		"spec": "test/RetoldFacto_tests.js",
@@ -96,7 +106,7 @@
 		"chai": "^6.2.2",
 		"pict-docuserve": "^0.1.5",
 		"puppeteer": "^24.40.0",
-		"quackage": "^1.1.3",
+		"quackage": "^1.2.0",
 		"stricture": "^4.0.2",
 		"supertest": "^7.2.2"
 	},
@@ -115,12 +125,12 @@
 		"meadow-connection-mysql": "^1.0.18",
 		"meadow-endpoints": "^4.0.17",
 		"meadow-integration": "^1.0.38",
-		"orator": "^6.1.0",
+		"orator": "^6.1.1",
 		"orator-serviceserver-restify": "^2.0.10",
 		"orator-static-server": "^2.1.3",
 		"pict": "^1.0.365",
 		"pict-router": "^1.0.9",
-		"pict-section-connection-form": "^0.0.1",
+		"pict-section-connection-form": "^0.0.2",
 		"pict-section-flow": "^0.0.17",
 		"pict-section-histogram": "^1.0.0",
 		"pict-section-markdowneditor": "^1.0.10",