The open-source agent harness - the runtime layer that turns an LLM into a working agent.
Update helm chart release workflows (#295)
Chirag Jainfd2f350cc9f5
diff --git a/.github/workflows/build-and-prepare-chart-release.yml b/.github/workflows/build-and-prepare-chart-release.ymlnew file mode 100644index 000000000..12fae118d--- /dev/null+++ b/.github/workflows/build-and-prepare-chart-release.yml@@ -0,0 +1,188 @@+name: Build and prepare chart release++# Prod lane: build the npm-install Dockerfile, push {appVersion}-{shortSha},+# then open/update the chart-release bot PR (merge of that PR tags + publishes).+#+# Triggered manually, including by release.yml through workflow_dispatch.+on:+ workflow_dispatch:+ inputs:+ app_version:+ description: npm version to install (empty = Chart.yaml appVersion)+ required: false+ type: string+ update_app_version:+ description: Also set Chart.yaml appVersion to app_version on the bot PR+ required: false+ type: boolean+ default: false++concurrency:+ group: release-image-and-chart+ cancel-in-progress: false++permissions: {}++jobs:+ resolve:+ name: Resolve versions+ runs-on: ubuntu-latest+ outputs:+ app_version: ${{ steps.resolve.outputs.app_version }}+ image_tag: ${{ steps.resolve.outputs.image_tag }}+ update_app_version: ${{ steps.resolve.outputs.update_app_version }}+ short_sha: ${{ steps.resolve.outputs.short_sha }}+ permissions:+ contents: read+ steps:+ - name: Check out+ uses: actions/checkout@v4++ - name: Install yq+ run: |+ sudo wget -q https://github.com/mikefarah/yq/releases/download/v4.53.3/yq_linux_amd64 -O /usr/bin/yq+ sudo chmod +x /usr/bin/yq++ - name: Resolve app version and image tag+ id: resolve+ env:+ INPUT_APP_VERSION: ${{ inputs.app_version }}+ INPUT_UPDATE_APP_VERSION: ${{ inputs.update_app_version }}+ run: |+ set -euo pipefail+ CHART_APP=$(yq -r '.appVersion' charts/trueforge/Chart.yaml | tr -d '"')+ if [[ -n "${INPUT_APP_VERSION}" ]]; then+ APP_VERSION="$INPUT_APP_VERSION"+ else+ APP_VERSION="$CHART_APP"+ fi+ if [[ -z "$APP_VERSION" || "$APP_VERSION" == "null" ]]; then+ echo "Could not resolve APP_VERSION" >&2+ exit 1+ fi+ if ! printf '%s' "$APP_VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+([.-][0-9A-Za-z.-]+)?$'; then+ echo "APP_VERSION '$APP_VERSION' is not a semver-like version" >&2+ exit 1+ fi+ SHORT_SHA="${GITHUB_SHA:0:7}"+ IMAGE_TAG="${APP_VERSION}-${SHORT_SHA}"+ UPDATE_APP="${INPUT_UPDATE_APP_VERSION:-false}"+ # workflow_dispatch boolean can be the string "true"/"false"+ if [[ "$UPDATE_APP" == "true" ]]; then+ UPDATE_OUT=true+ else+ UPDATE_OUT=false+ fi+ echo "app_version=$APP_VERSION" >> "$GITHUB_OUTPUT"+ echo "image_tag=$IMAGE_TAG" >> "$GITHUB_OUTPUT"+ echo "short_sha=$SHORT_SHA" >> "$GITHUB_OUTPUT"+ echo "update_app_version=$UPDATE_OUT" >> "$GITHUB_OUTPUT"+ echo "Resolved APP_VERSION=$APP_VERSION IMAGE_TAG=$IMAGE_TAG update_app_version=$UPDATE_OUT"++ build:+ name: Build and push server image+ needs: [resolve]+ uses: truefoundry/github-workflows-public/.github/workflows/build.yml@main+ permissions:+ id-token: write+ contents: read+ with:+ artifactory_registry_url: ${{ vars.TRUEFOUNDRY_ARTIFACTORY_REGISTRY_URL }}+ artifactory_repository_url: ${{ vars.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_REPOSITORY }}+ image_artifact_name: trueforge+ image_tag: ${{ needs.resolve.outputs.image_tag }}+ image_context: .+ dockerfile_path: Dockerfile+ image_build_args: |+ APP_VERSION=${{ needs.resolve.outputs.app_version }}+ platforms: linux/amd64+ enable_jfrog: true+ enable_public_ecr: false+ secrets:+ artifactory_username: ${{ secrets.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_USERNAME }}+ artifactory_password: ${{ secrets.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_PASSWORD }}++ open-chart-pr:+ name: Open chart release PR+ needs: [resolve, build]+ runs-on: ubuntu-latest+ permissions:+ contents: write+ pull-requests: write+ env:+ PR_BRANCH: release-chart/trueforge+ steps:+ - name: Check out+ uses: actions/checkout@v4++ - name: Install yq+ run: |+ sudo wget -q https://github.com/mikefarah/yq/releases/download/v4.53.3/yq_linux_amd64 -O /usr/bin/yq+ sudo chmod +x /usr/bin/yq++ - name: Update chart metadata+ id: chart+ env:+ IMAGE_TAG: ${{ needs.resolve.outputs.image_tag }}+ APP_VERSION: ${{ needs.resolve.outputs.app_version }}+ UPDATE_APP_VERSION: ${{ needs.resolve.outputs.update_app_version }}+ run: |+ set -euo pipefail+ SEMVER='^([0-9]+)\.([0-9]+)\.([0-9]+)(-[0-9A-Za-z.-]+)?$'+ CURRENT=$(yq -r '.version' charts/trueforge/Chart.yaml)+ if [[ ! "$CURRENT" =~ $SEMVER ]]; then+ echo "Chart.yaml version '$CURRENT' on $GITHUB_REF_NAME is not semver" >&2+ exit 1+ fi+ MAJOR="${BASH_REMATCH[1]}"+ MINOR="${BASH_REMATCH[2]}"+ PATCH="${BASH_REMATCH[3]}"+ VERSION="${MAJOR}.${MINOR}.$((PATCH + 1))"++ # create-pull-request rebuilds the PR branch from base plus this+ # workspace, so a reviewer's major/minor bump on the open PR is dropped+ # unless it is re-applied here. Only outrank the patch bump: a PR+ # version at or below it means base already absorbed that release.+ if git ls-remote --exit-code --heads origin "$PR_BRANCH" >/dev/null 2>&1; then+ git fetch --depth=1 origin "$PR_BRANCH"+ PR_VERSION=$(git show FETCH_HEAD:charts/trueforge/Chart.yaml | yq -r '.version')+ if [[ "$PR_VERSION" =~ $SEMVER ]] &&+ (( BASH_REMATCH[1] > MAJOR ||+ (BASH_REMATCH[1] == MAJOR && BASH_REMATCH[2] > MINOR) ||+ (BASH_REMATCH[1] == MAJOR && BASH_REMATCH[2] == MINOR && BASH_REMATCH[3] > PATCH + 1) )); then+ echo "Keeping chart version $PR_VERSION from $PR_BRANCH (over $VERSION)"+ VERSION="$PR_VERSION"+ fi+ fi+ export VERSION IMAGE_TAG APP_VERSION+ yq -i '.version = strenv(VERSION)' charts/trueforge/Chart.yaml+ yq -i '.image.tag = strenv(IMAGE_TAG)' charts/trueforge/values.yaml+ if [[ "$UPDATE_APP_VERSION" == "true" ]]; then+ yq -i '.appVersion = strenv(APP_VERSION)' charts/trueforge/Chart.yaml+ fi+ APP_VERSION=$(yq -r '.appVersion' charts/trueforge/Chart.yaml)+ echo "version=$VERSION" >> "$GITHUB_OUTPUT"+ echo "app_version=$APP_VERSION" >> "$GITHUB_OUTPUT"++ - name: Open or update chart-release PR+ uses: peter-evans/create-pull-request@v7+ with:+ token: ${{ secrets.GITHUB_TOKEN }}+ branch: ${{ env.PR_BRANCH }}+ base: main+ commit-message: 'release(chart): ${{ steps.chart.outputs.version }}'+ title: 'release(chart): ${{ steps.chart.outputs.version }} (image ${{ needs.resolve.outputs.image_tag }})'+ body: |+ ## Chart release++ | Field | Value |+ | --- | --- |+ | Chart version | `${{ steps.chart.outputs.version }}` |+ | appVersion | `${{ steps.chart.outputs.app_version }}` |+ | image.tag | `${{ needs.resolve.outputs.image_tag }}` |++ Merging this PR creates `charts/trueforge@${{ steps.chart.outputs.version }}`,+ creates a GitHub Release, and publishes the OCI Helm chart.+ add-paths: |+ charts/trueforge/Chart.yaml+ charts/trueforge/values.yamldiff --git a/.github/workflows/build-dev-image.yml b/.github/workflows/build-dev-image.ymlnew file mode 100644index 000000000..a89a5b617--- /dev/null+++ b/.github/workflows/build-dev-image.yml@@ -0,0 +1,54 @@+name: Build dev image++# From-source image for floating-main / external deploy repos.+# Builds Dockerfile.dev and pushes .../trueforge:<fullSha>. No chart publish.+on:+ workflow_dispatch:++concurrency:+ group: build-dev-image+ cancel-in-progress: false++permissions:+ contents: read++jobs:+ build:+ name: Build and push from-source image+ uses: truefoundry/github-workflows-public/.github/workflows/build.yml@main+ permissions:+ id-token: write+ contents: read+ with:+ artifactory_registry_url: ${{ vars.TRUEFOUNDRY_ARTIFACTORY_REGISTRY_URL }}+ artifactory_repository_url: ${{ vars.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_REPOSITORY }}+ image_artifact_name: trueforge+ image_tag: ${{ github.sha }}+ image_context: .+ dockerfile_path: Dockerfile.dev+ platforms: linux/amd64+ enable_jfrog: true+ enable_public_ecr: false+ secrets:+ artifactory_username: ${{ secrets.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_USERNAME }}+ artifactory_password: ${{ secrets.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_PASSWORD }}++ summary:+ name: Print image URI+ needs: [build]+ runs-on: ubuntu-latest+ permissions:+ contents: read+ steps:+ - name: Summary+ env:+ IMAGE_URI: ${{ vars.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_REPOSITORY }}/trueforge:${{ github.sha }}+ run: |+ set -euo pipefail+ echo "Pushed image URI: $IMAGE_URI"+ {+ echo "### Dev image (from-source)"+ echo "\`$IMAGE_URI\`"+ echo ""+ echo "Patch this SHA into your external \`truefoundry.yaml\` as \`image.tag\`."+ } >> "$GITHUB_STEP_SUMMARY"diff --git a/.github/workflows/release-chart.yml b/.github/workflows/release-chart.ymlnew file mode 100644index 000000000..69b347668--- /dev/null+++ b/.github/workflows/release-chart.yml@@ -0,0 +1,156 @@+name: Publish Helm chart++# A chart-release PR merge creates the tag/GitHub Release and publishes the+# chart. Human charts/trueforge@* tags use the same publish job.+on:+ pull_request:+ types: [closed]+ branches: [main]+ push:+ tags:+ - 'charts/trueforge@*'+ workflow_dispatch:+ inputs:+ tag:+ description: Existing tag to publish (e.g. charts/[email protected])+ required: true+ type: string++concurrency:+ group: publish-helm-chart+ cancel-in-progress: false++permissions: {}++jobs:+ release:+ name: Create release and publish chart+ if: >-+ github.event_name != 'pull_request' ||+ (+ github.event.pull_request.merged == true &&+ github.event.pull_request.head.ref == 'release-chart/trueforge' &&+ github.event.pull_request.head.repo.full_name == github.repository+ )+ runs-on: ubuntu-latest+ permissions:+ contents: write+ env:+ CHART_DIR: charts/trueforge+ HELM_REGISTRY_URL: ${{ vars.TRUEFOUNDRY_ARTIFACTORY_REGISTRY_URL }}+ HELM_CHART_REPOSITORY: ${{ vars.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_HELM_REPOSITORY }}+ steps:+ - name: Check out chart commit+ uses: actions/checkout@v4+ with:+ ref: ${{ github.event.pull_request.merge_commit_sha || inputs.tag || github.ref }}+ fetch-depth: 0++ - name: Install yq+ run: |+ sudo wget -q https://github.com/mikefarah/yq/releases/download/v4.53.3/yq_linux_amd64 -O /usr/bin/yq+ sudo chmod +x /usr/bin/yq++ - name: Install Helm+ uses: azure/setup-helm@v4+ with:+ version: v3.16.4++ - name: Resolve or create chart release+ env:+ EVENT_NAME: ${{ github.event_name }}+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}+ INPUT_TAG: ${{ inputs.tag }}+ MERGE_SHA: ${{ github.event.pull_request.merge_commit_sha }}+ PR_BODY: ${{ github.event.pull_request.body }}+ PR_NUMBER: ${{ github.event.pull_request.number }}+ run: |+ set -euo pipefail++ # Read the chart identity from the checked-out commit.+ VERSION=$(yq -r '.version' charts/trueforge/Chart.yaml)+ APP_VERSION=$(yq -r '.appVersion' charts/trueforge/Chart.yaml)+ IMAGE_TAG=$(yq -r '.image.tag' charts/trueforge/values.yaml)++ if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+([.-][0-9A-Za-z.-]+)?$ ]]; then+ echo "Invalid chart version: $VERSION" >&2+ exit 1+ fi++ # Path A: bot chart-release PR was merged.+ # Create the charts/trueforge@<version> tag + GitHub Release here,+ # because GITHUB_TOKEN tag pushes do not start a separate push workflow.+ if [[ "$EVENT_NAME" == "pull_request" ]]; then+ TAG="charts/trueforge@${VERSION}"++ if git rev-parse "$TAG" >/dev/null 2>&1; then+ echo "Tag $TAG already exists; refusing to move it" >&2+ exit 1+ fi++ git config user.name "github-actions[bot]"+ git config user.email "41898282+github-actions[bot]@users.noreply.github.com"+ git tag -a "$TAG" -m "Helm chart ${VERSION} (appVersion ${APP_VERSION}, image ${IMAGE_TAG})"+ git push origin "$TAG"++ # Write notes via a file so PR body cannot inject into the shell.+ NOTES_FILE="$(mktemp)"+ {+ echo "Source PR: #${PR_NUMBER}"+ echo+ printf '%s\n' "$PR_BODY"+ } >"$NOTES_FILE"+ gh release create "$TAG" \+ --target "$MERGE_SHA" \+ --title "$TAG" \+ --notes-file "$NOTES_FILE"+ rm -f "$NOTES_FILE"+ # Path B: manual retry via workflow_dispatch with an explicit tag.+ elif [[ -n "${INPUT_TAG:-}" ]]; then+ TAG="$INPUT_TAG"++ # Path C: human pushed charts/trueforge@* themselves.+ else+ TAG="${GITHUB_REF#refs/tags/}"+ fi++ # Every path must publish the same chart version the tag names.+ case "$TAG" in+ charts/trueforge@*) EXPECTED="${TAG#charts/trueforge@}" ;;+ *) echo "Invalid chart tag: $TAG" >&2; exit 1 ;;+ esac++ ACTUAL=$(yq -r '.version' "$CHART_DIR/Chart.yaml")+ if [[ "$ACTUAL" != "$EXPECTED" ]]; then+ echo "Chart.yaml version '$ACTUAL' does not match tag version '$EXPECTED'" >&2+ exit 1+ fi++ # VERSION is consumed by the package/push step below.+ echo "VERSION=$VERSION" >> "$GITHUB_ENV"+ echo "Publishing chart version=$ACTUAL appVersion=$APP_VERSION image.tag=$IMAGE_TAG"++ - name: Helm registry login+ env:+ HELM_REGISTRY_USERNAME: ${{ secrets.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_USERNAME }}+ HELM_REGISTRY_PASSWORD: ${{ secrets.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_PASSWORD }}+ run: |+ printf '%s' "$HELM_REGISTRY_PASSWORD" \+ | helm registry login -u "$HELM_REGISTRY_USERNAME" --password-stdin "$HELM_REGISTRY_URL"++ - name: Build chart dependencies+ run: helm dependency build "$CHART_DIR"++ - name: Package and push chart+ run: |+ set -euo pipefail+ CHART_NAME=$(yq -r '.name' "$CHART_DIR/Chart.yaml")+ mkdir -p dist+ helm package "$CHART_DIR" --destination dist+ PACKAGE="dist/${CHART_NAME}-${VERSION}.tgz"+ echo "Pushing $PACKAGE to oci://$HELM_CHART_REPOSITORY"+ helm push "$PACKAGE" "oci://$HELM_CHART_REPOSITORY"+ {+ echo "### Helm chart"+ echo "Pushed \`oci://${HELM_CHART_REPOSITORY}/${CHART_NAME}:${VERSION}\`"+ } >> "$GITHUB_STEP_SUMMARY"diff --git a/.github/workflows/release-image-and-chart.yml b/.github/workflows/release-image-and-chart.ymldeleted file mode 100644index 0069cf1d8..000000000--- a/.github/workflows/release-image-and-chart.yml+++ /dev/null@@ -1,126 +0,0 @@-name: Release image and Helm chart--# Manually dispatch to build and push the server image (tagged with the commit-# SHA), stamp that SHA into the Helm chart, package it, and push it to the-# JFrog public OCI Helm repo.-on:- workflow_dispatch:--# One release at a time so the chart push cannot race.-concurrency:- group: release-image-and-chart- cancel-in-progress: false--permissions:- contents: read--jobs:- # TODO: Re-enable this when we want to derive the version from the release tag.- # Derive the version from the release tag; it is the single source of truth for- # the image tag and the chart version/appVersion.- # prepare:- # name: Resolve release version- # runs-on: ubuntu-latest- # outputs:- # version: ${{ steps.version.outputs.version }}- # steps:- # - name: Resolve version- # id: version- # env:- # TAG: ${{ github.event.release.tag_name }}- # run: |- # set -euo pipefail- # VERSION="${TAG#v}"- # if ! printf '%s' "$VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$'; then- # echo "Release tag '$TAG' is not a semver vX.Y.Z tag" >&2- # exit 1- # fi- # echo "Releasing version $VERSION"- # echo "version=$VERSION" >> "$GITHUB_OUTPUT"-- # Build and push the server image (API + UI) via the shared reusable workflow.- build:- name: Build and push server image- uses: truefoundry/github-workflows-public/.github/workflows/build.yml@main- permissions:- id-token: write- contents: read- with:- artifactory_registry_url: ${{ vars.TRUEFOUNDRY_ARTIFACTORY_REGISTRY_URL }}- artifactory_repository_url: ${{ vars.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_REPOSITORY }}- image_artifact_name: trueforge- image_tag: ${{ github.sha }}- image_context: .- dockerfile_path: Dockerfile- platforms: linux/amd64- # The chart pulls the server image from JFrog (values.yaml image.repository),- # so JFrog is the only publish target; public ECR stays off.- enable_jfrog: true- enable_public_ecr: false- secrets:- artifactory_username: ${{ secrets.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_USERNAME }}- artifactory_password: ${{ secrets.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_PASSWORD }}-- # Stamp the commit SHA into the chart, then package and publish it.- release-chart:- name: Package and publish Helm chart- needs: [build]- runs-on: ubuntu-latest- env:- # Helm requires SemVer for Chart.yaml version; prerelease form keeps the- # commit SHA while remaining packageable. Image tag stays the raw SHA.- VERSION: 0.0.0-${{ github.sha }}- IMAGE_TAG: ${{ github.sha }}- CHART_DIR: charts/trueforge- HELM_REGISTRY_URL: ${{ vars.TRUEFOUNDRY_ARTIFACTORY_REGISTRY_URL }}- HELM_REGISTRY_USERNAME: ${{ secrets.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_USERNAME }}- HELM_REGISTRY_PASSWORD: ${{ secrets.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_PASSWORD }}- HELM_CHART_REPOSITORY: ${{ vars.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_HELM_REPOSITORY }}- steps:- - name: Check out release commit- uses: actions/checkout@v4-- - name: Install yq- run: |- sudo wget -q https://github.com/mikefarah/yq/releases/download/v4.53.3/yq_linux_amd64 -O /usr/bin/yq- sudo chmod +x /usr/bin/yq-- - name: Install Helm- uses: azure/setup-helm@v4- with:- version: v3.16.4-- - name: Stamp version into chart- run: |- set -euo pipefail- yq -i '.version = strenv(VERSION) | .appVersion = strenv(IMAGE_TAG)' "$CHART_DIR/Chart.yaml"- yq -i '.image.tag = strenv(IMAGE_TAG)' "$CHART_DIR/values.yaml"- echo "Stamped chart version=$VERSION image.tag=$IMAGE_TAG"-- - name: Helm registry login- run: |- helm registry login -u "$HELM_REGISTRY_USERNAME" -p "$HELM_REGISTRY_PASSWORD" "$HELM_REGISTRY_URL"-- # Fetch the postgresql/redis subcharts from the public Bitnami OCI archive,- # pinned by Chart.lock. The archive is public (no auth); the images those- # subcharts run are separately mirrored to JFrog via values.yaml.- - name: Build chart dependencies- run: helm dependency build "$CHART_DIR"-- - name: Package and push chart- run: |- set -euo pipefail- CHART_NAME=$(yq -r '.name' "$CHART_DIR/Chart.yaml")- helm package "$CHART_DIR" --destination dist- PACKAGE="dist/${CHART_NAME}-${VERSION}.tgz"- echo "Pushing $PACKAGE to oci://$HELM_CHART_REPOSITORY"- helm push "$PACKAGE" "oci://$HELM_CHART_REPOSITORY"-- - name: Print image URI- env:- IMAGE_URI: ${{ vars.TRUEFOUNDRY_ARTIFACTORY_PUBLIC_REPOSITORY }}/trueforge:${{ github.sha }}- run: |- set -euo pipefail- echo "Pushed image URI: $IMAGE_URI"- echo "### Server image" >> "$GITHUB_STEP_SUMMARY"- echo "\`$IMAGE_URI\`" >> "$GITHUB_STEP_SUMMARY"diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex bd075f76c..890bd68bb 100644--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@ -142,6 +142,7 @@ jobs:runs-on: ubuntu-latesttimeout-minutes: 20permissions:+ actions: writecontents: writeid-token: writesteps:@@ -163,6 +164,7 @@ jobs:- run: pnpm install --frozen-lockfile- name: Publish packages+ id: publishuses: changesets/action/publish@v2with:pack-dir-artifact-id: ${{ needs.pack.outputs.pack-dir-artifact-id }}@@ -170,3 +172,48 @@ jobs:# TODO(oss): set NPM_CONFIG_PROVENANCE once the repo is public. Do NOT# set it now: provenance publicly attests the source repo and commit.# publishConfig.provenance is false on every public package.++ - name: Detect @truefoundry/trueforge publish+ id: trueforge+ env:+ PUBLISHED: ${{ steps.publish.outputs.published }}+ PACKAGES_KEBAB: ${{ steps.publish.outputs['published-packages'] }}+ PACKAGES_CAMEL: ${{ steps.publish.outputs.publishedPackages }}+ run: |+ set -euo pipefail+ if [[ "${PUBLISHED:-}" != "true" ]]; then+ echo "published=false" >> "$GITHUB_OUTPUT"+ echo "version=" >> "$GITHUB_OUTPUT"+ exit 0+ fi+ PACKAGES="${PACKAGES_KEBAB:-${PACKAGES_CAMEL:-[]}}"+ VERSION=$(printf '%s' "$PACKAGES" | python3 -c '+ import json,sys+ pkgs=json.load(sys.stdin)+ for p in pkgs:+ if p.get("name")=="@truefoundry/trueforge":+ print(p["version"])+ break+ ')+ if [[ -n "$VERSION" ]]; then+ echo "published=true" >> "$GITHUB_OUTPUT"+ echo "version=$VERSION" >> "$GITHUB_OUTPUT"+ echo "Published @truefoundry/trueforge@$VERSION"+ else+ echo "published=false" >> "$GITHUB_OUTPUT"+ echo "version=" >> "$GITHUB_OUTPUT"+ echo "@truefoundry/trueforge was not in this publish set"+ fi++ - name: Start prod image release+ if: steps.trueforge.outputs.published == 'true'+ env:+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}+ VERSION: ${{ steps.trueforge.outputs.version }}+ run: |+ # Pin to this publish commit so a newer main push cannot change the+ # Dockerfile / shortSha used for the prod image tag.+ gh workflow run build-and-prepare-chart-release.yml \+ --ref "$GITHUB_SHA" \+ -f app_version="$VERSION" \+ -f update_app_version=truediff --git a/Dockerfile b/Dockerfileindex 9879b80ef..f7a541b4d 100644--- a/Dockerfile+++ b/Dockerfile@@ -1,102 +1,27 @@# syntax=docker/dockerfile:1#-# Multi-stage build for @truefoundry/trueforge, which also serves the UI: the only image the stack needs.+# Production image: installs published @truefoundry/trueforge from npm.+# The app bits match the npm package exactly (not floating monorepo source).#-# Lives at the repository root because the build needs the whole pnpm workspace-# as its context: the server depends on the workspace package @truefoundry/trueforge-core.+# Required build-arg:+# APP_VERSION — npm version to install, e.g. 0.1.0#-# Dependency install uses pnpm fetch (lockfile-only) then install --offline so-# the download layer stays cached when only package.json / scripts change.-# See https://pnpm.io/cli/fetch+# Example:+# docker build --build-arg APP_VERSION=0.1.0 -t trueforge:0.1.0 .-FROM node:24-slim AS base-ENV PNPM_HOME=/pnpm-ENV PATH="$PNPM_HOME:$PATH"-RUN corepack enable && pnpm config set store-dir /pnpm/store+FROM node:24-slim AS runnerWORKDIR /app--# Native dependencies (for example better-sqlite3) compile in build stages.-FROM base AS build-base-RUN apt-get update \- && apt-get install -y --no-install-recommends g++ make python3 \- && rm -rf /var/lib/apt/lists/*--# ----------------------------------------------------------------------------# store: the pnpm store, from the lockfile only (stable when manifests churn).-# ----------------------------------------------------------------------------FROM build-base AS store-COPY pnpm-lock.yaml pnpm-workspace.yaml ./-RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm fetch--# ----------------------------------------------------------------------------# workspace: install inputs shared by every stage below — the manifests plus the-# sources the root postinstall hook (build:gen) inlines.-# ----------------------------------------------------------------------------FROM store AS workspace-COPY package.json .npmrc tsconfig.base.json ./-COPY packages/trueforge-core/package.json packages/trueforge-core/package.json-COPY packages/trueforge/package.json packages/trueforge/package.json-COPY packages/trueforge-sdk/package.json packages/trueforge-sdk/package.json-COPY packages/frontend/package.json packages/frontend/package.json-COPY packages/trueforge-ui/package.json packages/trueforge-ui/package.json-COPY packages/trueforge-core/scripts packages/trueforge-core/scripts-COPY packages/trueforge-core/src/core/sandbox/scripts packages/trueforge-core/src/core/sandbox/scripts--# ----------------------------------------------------------------------------# builder: install all deps (incl. dev) and build trueforge-core + server.-# ----------------------------------------------------------------------------FROM workspace AS builder-RUN --mount=type=cache,id=pnpm,target=/pnpm/store \- pnpm install --frozen-lockfile --offline --filter @truefoundry/trueforge...-COPY packages/trueforge-core packages/trueforge-core-COPY packages/trueforge packages/trueforge-RUN pnpm --filter @truefoundry/trueforge-core build && pnpm --filter @truefoundry/trueforge build--# ----------------------------------------------------------------------------# frontend-builder: build the UI the server serves (parallel to builder above).-# ----------------------------------------------------------------------------FROM workspace AS frontend-builder-RUN --mount=type=cache,id=pnpm,target=/pnpm/store \- pnpm install --frozen-lockfile --offline --filter frontend...-COPY packages/trueforge-sdk packages/trueforge-sdk-RUN pnpm --filter @truefoundry/trueforge-sdk build-COPY packages/trueforge-ui packages/trueforge-ui-RUN pnpm --filter @truefoundry/trueforge-ui build-COPY packages/frontend packages/frontend-RUN pnpm --filter frontend build--# ----------------------------------------------------------------------------# prod-deps: production dependency tree (no dev tooling), resolved offline.-# ----------------------------------------------------------------------------FROM workspace AS prod-deps-RUN --mount=type=cache,id=pnpm,target=/pnpm/store \- pnpm install --frozen-lockfile --offline --prod --filter @truefoundry/trueforge...--# ----------------------------------------------------------------------------# runner: minimal image with prod node_modules + built artifacts.-# ----------------------------------------------------------------------------FROM base AS runnerENV NODE_ENV=production+ENV STANDALONE=false-# Production dependency tree (pnpm workspace symlinks preserved).-COPY --from=prod-deps /app/node_modules ./node_modules-COPY --from=prod-deps /app/packages/trueforge-core/node_modules ./packages/trueforge-core/node_modules-COPY --from=prod-deps /app/packages/trueforge/node_modules ./packages/trueforge/node_modules--# Built workspace dependency (@truefoundry/trueforge-core).-COPY --from=builder /app/packages/trueforge-core/package.json ./packages/trueforge-core/package.json-COPY --from=builder /app/packages/trueforge-core/dist ./packages/trueforge-core/dist--# Built server (JS). UI is copied below from the parallel frontend stage into-# dist/_frontend — same path as the npm tarball / `pnpm build` copy step.-COPY --from=builder /app/packages/trueforge/package.json ./packages/trueforge/package.json-COPY --from=builder /app/packages/trueforge/dist ./packages/trueforge/dist-# Frontend builds in a parallel stage; place it at the same path as the npm tarball.-COPY --from=frontend-builder /app/packages/frontend/dist ./packages/trueforge/dist/_frontend+ARG APP_VERSION+RUN test -n "$APP_VERSION" || (echo "APP_VERSION build-arg is required" >&2 && exit 1)-WORKDIR /app/packages/trueforge+# Fail closed if the version is not on the registry (no workspace fallback).+RUN npm install --omit=dev "@truefoundry/trueforge@${APP_VERSION}" \+ && npm cache clean --forceEXPOSE 8790-# Launch-only (matches root `pnpm start` / `standalone:start`). Image already contains dist.-CMD ["node", "dist/main.js"]+# Same entry as the from-source image / `pnpm start` (launch-only; dist is in the package).+CMD ["node", "node_modules/@truefoundry/trueforge/dist/main.js"]diff --git a/Dockerfile.dev b/Dockerfile.devnew file mode 100644index 000000000..12744eb8b--- /dev/null+++ b/Dockerfile.dev@@ -0,0 +1,97 @@+# syntax=docker/dockerfile:1+#+# From-source multi-stage build for local smoke / floating-main / SHA-tagged+# dev images. Production/OSS Helm images use the root Dockerfile (npm install).+#+# Lives at the repository root because the build needs the whole pnpm workspace+# as its context: the server depends on the workspace package @truefoundry/trueforge-core.+#+# Dependency install uses pnpm fetch (lockfile-only) then install --offline so+# the download layer stays cached when only package.json / scripts change.+# See https://pnpm.io/cli/fetch++FROM node:24-slim AS base+ENV PNPM_HOME=/pnpm+ENV PATH="$PNPM_HOME:$PATH"+RUN corepack enable && pnpm config set store-dir /pnpm/store+WORKDIR /app++# ---------------------------------------------------------------------------+# store: the pnpm store, from the lockfile only (stable when manifests churn).+# ---------------------------------------------------------------------------+FROM base AS store+COPY pnpm-lock.yaml pnpm-workspace.yaml ./+RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm fetch++# ---------------------------------------------------------------------------+# workspace: install inputs shared by every stage below — the manifests plus the+# sources the root postinstall hook (build:gen) inlines.+# ---------------------------------------------------------------------------+FROM store AS workspace+COPY package.json .npmrc tsconfig.base.json ./+COPY packages/trueforge-core/package.json packages/trueforge-core/package.json+COPY packages/trueforge/package.json packages/trueforge/package.json+COPY packages/trueforge-sdk/package.json packages/trueforge-sdk/package.json+COPY packages/frontend/package.json packages/frontend/package.json+COPY packages/trueforge-ui/package.json packages/trueforge-ui/package.json+COPY packages/trueforge-core/scripts packages/trueforge-core/scripts+COPY packages/trueforge-core/src/core/sandbox/scripts packages/trueforge-core/src/core/sandbox/scripts++# ---------------------------------------------------------------------------+# builder: install all deps (incl. dev) and build trueforge-core + server.+# ---------------------------------------------------------------------------+FROM workspace AS builder+RUN --mount=type=cache,id=pnpm,target=/pnpm/store \+ pnpm install --frozen-lockfile --offline --filter @truefoundry/trueforge...+COPY packages/trueforge-core packages/trueforge-core+COPY packages/trueforge packages/trueforge+RUN pnpm --filter @truefoundry/trueforge-core build && pnpm --filter @truefoundry/trueforge build++# ---------------------------------------------------------------------------+# frontend-builder: build the UI the server serves (parallel to builder above).+# ---------------------------------------------------------------------------+FROM workspace AS frontend-builder+RUN --mount=type=cache,id=pnpm,target=/pnpm/store \+ pnpm install --frozen-lockfile --offline --filter frontend...+COPY packages/trueforge-sdk packages/trueforge-sdk+RUN pnpm --filter @truefoundry/trueforge-sdk build+COPY packages/trueforge-ui packages/trueforge-ui+RUN pnpm --filter @truefoundry/trueforge-ui build+COPY packages/frontend packages/frontend+RUN pnpm --filter frontend build++# ---------------------------------------------------------------------------+# prod-deps: production dependency tree (no dev tooling), resolved offline.+# ---------------------------------------------------------------------------+FROM workspace AS prod-deps+RUN --mount=type=cache,id=pnpm,target=/pnpm/store \+ pnpm install --frozen-lockfile --offline --prod --filter @truefoundry/trueforge...++# ---------------------------------------------------------------------------+# runner: minimal image with prod node_modules + built artifacts.+# ---------------------------------------------------------------------------+FROM base AS runner+ENV NODE_ENV=production++# Production dependency tree (pnpm workspace symlinks preserved).+COPY --from=prod-deps /app/node_modules ./node_modules+COPY --from=prod-deps /app/packages/trueforge-core/node_modules ./packages/trueforge-core/node_modules+COPY --from=prod-deps /app/packages/trueforge/node_modules ./packages/trueforge/node_modules++# Built workspace dependency (@truefoundry/trueforge-core).+COPY --from=builder /app/packages/trueforge-core/package.json ./packages/trueforge-core/package.json+COPY --from=builder /app/packages/trueforge-core/dist ./packages/trueforge-core/dist++# Built server (JS). UI is copied below from the parallel frontend stage into+# dist/_frontend — same path as the npm tarball / `pnpm build` copy step.+COPY --from=builder /app/packages/trueforge/package.json ./packages/trueforge/package.json+COPY --from=builder /app/packages/trueforge/dist ./packages/trueforge/dist+# Frontend builds in a parallel stage; place it at the same path as the npm tarball.+COPY --from=frontend-builder /app/packages/frontend/dist ./packages/trueforge/dist/_frontend++WORKDIR /app/packages/trueforge++EXPOSE 8790++# Launch-only (matches root `pnpm start` / `standalone:start`). Image already contains dist.+CMD ["node", "dist/main.js"]diff --git a/README.md b/README.mdindex 8f955b9a0..6f0b3d91e 100644--- a/README.md+++ b/README.md@@ -10,38 +10,18 @@<p align="center">The open-source agent harness - the runtime layer that turns an LLM into a working agent</p><p align="center">- <a href="https://github.com/truefoundry/trueforge/blob/main/LICENSE">- <img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT">- </a>- <a href="https://nodejs.org">- <img src="https://img.shields.io/badge/Node.js-%3E%3D22.13-green.svg" alt="Node.js >= 22.13">- </a>- <a href="https://trueforge.dev">- <img src="https://img.shields.io/badge/Documentation-trueforge.dev-blue.svg" alt="Documentation">- </a>- <a href="https://trueforge.dev/quickstart">- <img src="https://img.shields.io/badge/Quickstart-trueforge.dev/quickstart-blue.svg" alt="Quickstart">- </a>- <a href="https://trueforge.dev/api/overview">- <img src="https://img.shields.io/badge/SDK-trueforge.dev/api/overview-blue.svg" alt="SDK">- </a>+ <a href="https://github.com/truefoundry/trueforge/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" alt="License: MIT"></a>+ <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node.js-%3E%3D22.13-green.svg?style=flat-square" alt="Node.js >= 22.13"></a>+ <a href="https://trueforge.dev"><img src="https://img.shields.io/badge/Documentation-trueforge.dev-blue.svg?style=flat-square" alt="Documentation"></a>+ <a href="https://trueforge.dev/quickstart"><img src="https://img.shields.io/badge/Quickstart-trueforge.dev/quickstart-blue.svg?style=flat-square" alt="Quickstart"></a>+ <a href="https://trueforge.dev/api/overview"><img src="https://img.shields.io/badge/SDK-trueforge.dev/api/overview-blue.svg?style=flat-square" alt="SDK"></a></p><p align="center">- <a href="https://www.npmjs.com/package/@truefoundry/trueforge">- <img src="https://img.shields.io/npm/v/@truefoundry/trueforge?label=trueforge" alt="npm @truefoundry/trueforge">- </a>- <a href="https://www.npmjs.com/package/@truefoundry/trueforge-sdk">- <img src="https://img.shields.io/npm/v/@truefoundry/trueforge-sdk?label=trueforge-sdk" alt="npm @truefoundry/trueforge-sdk">- </a>- <a href="https://www.npmjs.com/package/@truefoundry/trueforge-ui">- <img src="https://img.shields.io/npm/v/@truefoundry/trueforge-ui?label=trueforge-ui" alt="npm @truefoundry/trueforge-ui">- </a>- <a href="https://www.npmjs.com/package/@truefoundry/trueforge-core">- <img src="https://img.shields.io/npm/v/@truefoundry/trueforge-core?label=trueforge-core" alt="npm @truefoundry/trueforge-core">- </a>- <a href="https://deepwiki.com/truefoundry/trueforge">- <img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki">- </a>+ <a href="https://www.npmjs.com/package/@truefoundry/trueforge"><img src="https://img.shields.io/npm/v/@truefoundry/trueforge?label=trueforge&style=flat-square" alt="npm @truefoundry/trueforge"></a>+ <a href="https://www.npmjs.com/package/@truefoundry/trueforge-sdk"><img src="https://img.shields.io/npm/v/@truefoundry/trueforge-sdk?label=trueforge-sdk&style=flat-square" alt="npm @truefoundry/trueforge-sdk"></a>+ <a href="https://www.npmjs.com/package/@truefoundry/trueforge-ui"><img src="https://img.shields.io/npm/v/@truefoundry/trueforge-ui?label=trueforge-ui&style=flat-square" alt="npm @truefoundry/trueforge-ui"></a>+ <a href="https://www.npmjs.com/package/@truefoundry/trueforge-core"><img src="https://img.shields.io/npm/v/@truefoundry/trueforge-core?label=trueforge-core&style=flat-square" alt="npm @truefoundry/trueforge-core"></a>+ <a href="https://deepwiki.com/truefoundry/trueforge"><img src="https://deepwiki.com/badge.svg?style=flat-square" alt="Ask DeepWiki"></a></p># TrueForgediff --git a/RELEASING.md b/RELEASING.mdindex adad7418c..f0f013a6f 100644--- a/RELEASING.md+++ b/RELEASING.md@@ -1,152 +1,201 @@# Releasing-This repository ships two independent release pipelines:+This repo ships npm packages, a production container image, a Helm chart, and+optional from-source **dev** images.-| What | Trigger | Workflow |-| ------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------ |-| npm packages | Push to `main` (Changesets) | [`.github/workflows/release.yml`](.github/workflows/release.yml) |-| Server image + Helm chart | Manual `workflow_dispatch` | [`.github/workflows/release-image-and-chart.yml`](.github/workflows/release-image-and-chart.yml) |+| What | Trigger | Workflow |+| ----------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |+| npm packages | Push to `main` (Changesets) | [`release.yml`](.github/workflows/release.yml) |+| Prod image + chart-release PR | After `@truefoundry/trueforge` npm publish, or manual dispatch | [`build-and-prepare-chart-release.yml`](.github/workflows/build-and-prepare-chart-release.yml) |+| Chart tag, GitHub Release, OCI push | Merge of `release-chart/trueforge`, or push/dispatch of `charts/trueforge@*` | [`release-chart.yml`](.github/workflows/release-chart.yml) |+| Dev (from-source) image | Manual `workflow_dispatch` | [`build-dev-image.yml`](.github/workflows/build-dev-image.yml) |-Publishing npm does not stamp or push the chart. Publishing the image/chart does not publish npm.+## Versioning-## Published packages+| Artifact | Identity |+| ---------------------------- | ---------------------------------------------------------------------------------- |+| npm `@truefoundry/trueforge` | SemVer `X.Y.Z` — source of truth for app bits |+| Chart `appVersion` | A **published** npm version |+| Prod image | Root [`Dockerfile`](Dockerfile): `npm install @truefoundry/trueforge@$APP_VERSION` |+| Prod image tag | `{appVersion}-{shortSha}` (shortSha of the build commit) |+| Chart `version` | Independent SemVer; git tag `charts/[email protected]` must match |+| Dev image | [`Dockerfile.dev`](Dockerfile.dev); tag = full commit SHA |-| Package | Source | Notes |-| ----------------------------- | ------------------------- | --------------------------------------------------------------- |-| `@truefoundry/trueforge-core` | `packages/trueforge-core` | Library (`files: ["dist", "README.md"]`) |-| `@truefoundry/trueforge` | `packages/trueforge` | App + CLI; tarball includes embedded UI under `dist/_frontend/` |-| `@truefoundry/trueforge-sdk` | `packages/trueforge-sdk` | Fern-generated client — do not hand-edit |-| `@truefoundry/trueforge-ui` | `packages/trueforge-ui` | Embeddable chat UI |+Install a published chart:-`packages/frontend` is not published on its own. The server build copies its output into `@truefoundry/trueforge`'s `dist/_frontend/`.--Workspace dependencies use `workspace:*`. On publish, pnpm rewrites them to the exact version in each dependency's `package.json`. `changeset publish` publishes in dependency order, so a package never lands pointing at an unpublished sibling from the same run.+```bash+helm install trueforge oci://tfy.jfrog.io/tfy-helm/trueforge --version <chart-semver>+```---# npm packages-## Release flow--There is no `v*` git-tag publish. One workflow both versions and publishes, split into least-privilege jobs (`select-mode` → `version` | `pack` → `publish`):+| Package | Source | Notes |+| ----------------------------- | ------------------------- | --------------------------------------------- |+| `@truefoundry/trueforge-core` | `packages/trueforge-core` | Library |+| `@truefoundry/trueforge` | `packages/trueforge` | App + CLI; tarball includes `dist/_frontend/` |+| `@truefoundry/trueforge-sdk` | `packages/trueforge-sdk` | Fern-generated — do not hand-edit |+| `@truefoundry/trueforge-ui` | `packages/trueforge-ui` | Embeddable chat UI |-1. **Add a changeset** in the same PR as the code change:+`packages/frontend` is not published; its build is copied into `@truefoundry/trueforge`'s tarball.+`workspace:*` is rewritten to exact versions on publish.- ```bash- pnpm changeset- # non-interactive:- pnpm change --bump patch --summary "…" @truefoundry/trueforge-core- ```+## Flow- Name only the packages that should bump. A dependency can ship without its dependents. SDK regeneration on a PR already adds `@truefoundry/trueforge-sdk` via `pnpm changeset:sdk-regen`.+No `v*` tag publish. [`release.yml`](.github/workflows/release.yml) does both version and publish+(`select-mode` → `version` \| `pack` → `publish`):-2. **Merge to `main`.** `.github/workflows/release.yml` runs. `changesets/action/select-mode` picks the path. With pending `.changeset/*.md` files, the **version** job opens or updates a **Version Packages** PR (`pnpm run version`: `changeset version`, then `pnpm sdk:generate` only if the SDK version moved). Review bumps and changelogs, then merge.+1. Add a changeset in the same PR as the code change (`pnpm changeset`, or+ `pnpm change --bump patch --summary "…" <pkg>`). SDK regen already adds+ `@truefoundry/trueforge-sdk` via `pnpm changeset:sdk-regen`.+2. Merge to `main`. Pending changesets → **Version Packages** PR+ (`pnpm run version`). Review and merge.+3. With no pending changesets, **pack** (build/test) then **publish** via npm+ trusted publishing (OIDC; no `NPM_TOKEN`).+4. If `@truefoundry/trueforge` was published, the publish job dispatches+ **Build and prepare chart release** at `--ref "$GITHUB_SHA"` (pinned to the+ publish commit, not floating `main`).+5. Pin dependents to exact versions during early `0.x`.-3. **Merge Version Packages to publish.** The same workflow sees no pending changesets: **pack** builds/tests and packs tarballs, then **publish** uploads them. Auth is npm trusted publishing over GitHub OIDC (`id-token` only on the publish job; no `NPM_TOKEN`).+`workflow_dispatch` on **Release** re-runs the same workflow.- **Dist-tags:** while `.changeset/pre.json` exists (`pnpm changeset pre enter rc`), publishes use the `rc` tag. After `pnpm changeset pre exit`, the next Version Packages merge publishes to `latest`. Install an RC with `npx @truefoundry/trueforge@rc` or a concrete `x.y.z-rc.N` version.+## Prerelease mode-4. **Update downstream pins** that depend on these packages. Prefer exact versions (no `^`) during early `0.x` churn.+Repo-wide via `.changeset/pre.json` (absent = publish to `latest`):-`workflow_dispatch` on **Release** re-runs the same workflow (useful after a bot-only commit that did not re-trigger it).+| Goal | Command | Then |+| -------- | ----------------------------- | ------------------------------------------------------------------------- |+| Enter RC | `pnpm changeset pre enter rc` | Commit `pre.json`, merge; versions look like `x.y.z-rc.N` (`rc` dist-tag) |+| Exit RC | `pnpm changeset pre exit` | Commit the delete, merge; next Version Packages merge publishes `latest` |-A push to `main` with no pending changesets still publishes any `package.json` version not yet on npm and no-ops the rest.+`pre enter` / `pre exit` do not bump or publish. Do not mix stable and RC packages in one+`changeset version`.-## Prerelease mode+## Trusted publishing-Pre mode is repo-wide (`.changeset/pre.json`), not per-package. The repo is currently in `rc`.+Each public package must list this repo + workflow as a trusted publisher on npmjs.com:-| Goal | Command | Then |-| -------------------- | ----------------------------- | ------------------------------------------------------------------------- |-| Stay on RCs | (already in pre) | Normal PRs + Version Packages. Versions look like `x.y.z-rc.N`. |-| Ship stable `latest` | `pnpm changeset pre exit` | Commit the deleted `pre.json`, merge, then merge the Version Packages PR. |-| Start a new RC line | `pnpm changeset pre enter rc` | Commit `pre.json`, merge, continue as above. |+- Repository: `truefoundry/trueforge`+- Workflow: `release.yml` (exact filename)+- No GitHub Environment name-`pre enter` / `pre exit` do not bump versions or publish. The Version Packages PR versions; merging it publishes.+Do not set `NPM_TOKEN` / `_authToken` on the publish job — that disables OIDC.+Only the **publish** job has `id-token: write`.-Do not mix stable and RC packages in one `changeset version` — exit pre only when the next publish should be GA.+## Local without publishing-## Package layout (`@truefoundry/trueforge-core`)+```bash+pnpm clean && pnpm build && pnpm standalone:start+# or: pnpm pack inside packages/trueforge-core / packages/trueforge+```-Packages publish from their package root. The core build emits CJS (`.js`), ESM (`.mjs`), and `.d.ts` under `dist/`; `package.json` `exports` point at those paths and `files: ["dist", "README.md"]` keeps `src/` out of the tarball.+## Troubleshooting-- Deep imports such as `@truefoundry/trueforge-core/core/llm/LLMTypes` resolve via the package `exports` map for modern `moduleResolution` modes (`bundler`, `node16`, `nodenext`).-- Curated barrels (`.`, `./core`, `./agent-session`) are the supported public API; deep imports are an escape hatch.-- A custom `"trueforge-dev"` export condition points at `./src` for dist-free monorepo development only. `src/` is not in the tarball, and the condition is not named `"development"`, so external tooling will not activate it accidentally.+- **No Version Packages PR** — no `.changeset/*.md` on `main`. Add one, or re-run **Release**.+- **Publish wants a tag** — RCs need the `rc` dist-tag (set automatically while `pre.json` exists).+- **403** — version already on npm, or trusted-publisher config mismatch.+- **OIDC fail** — pnpm >= 11.0.7; remove registry `_authToken`.+- **Missing `dist/_frontend/index.html`** — root `pnpm build` must build `frontend` first.+- **SDK not regenerated on Version PR** — only when `@truefoundry/trueforge-sdk` version moved+ (`scripts/version.mjs`; needs Docker).-Sourcemaps / declaration maps are currently enabled in the published tarball.+----## Why dependents pin exact versions+# Image and Helm chart-On publish, `workspace:*` becomes the **exact version** in the dependency's `package.json`. If that version is missing from npm, consumers fail at install/runtime. Changeset both packages together when a dependent needs new APIs from its dependency.+```text+npm publish @truefoundry/[email protected]+ → dispatch build-and-prepare-chart-release @ publish SHA+ → build Dockerfile (APP_VERSION=X.Y.Z) → push X.Y.Z-<shortSha>+ → open/update PR on branch release-chart/trueforge+ → merge PR → tag + GH Release + OCI push (release-chart.yml)-## Local iteration without publishing+manual rebuild (same or other app version)+ → workflow_dispatch build-and-prepare-chart-release+ → same PR path-```bash-pnpm clean && pnpm build && pnpm standalone:start-# or pack only:-cd packages/trueforge-core && pnpm build && pnpm pack-cd packages/trueforge && pnpm pack+chart-only+ → human PR bumps Chart.yaml version+ → human tags charts/[email protected] (or gh release create)+ → release-chart.yml publishes OCI (no image rebuild)```-Point consumers at a tarball with a `file:` dependency (or `yalc`) until a real version is published.+## Dockerfiles-## npm trusted publishing+| File | Role |+| ---------------------------------- | --------------------------------------------------------------------------------------- |+| [`Dockerfile`](Dockerfile) | Prod/OSS. `ARG APP_VERSION` → `npm install @truefoundry/trueforge@$APP_VERSION` |+| [`Dockerfile.dev`](Dockerfile.dev) | From-source. Used by [`docker-compose.yml`](docker-compose.yml) and **Build dev image** |-Each of the four packages must list this repository and workflow as a trusted publisher on npmjs.com:+Prod fails if that npm version is missing (no workspace fallback), so `appVersion` stays honest+even when `main` has moved on.-- Repository: `truefoundry/trueforge`-- Workflow filename: `release.yml` (must match exactly)-- No GitHub Environment name (the publish job does not use one)+## Build and prepare chart release-Configure the trusted-publisher row **before** the first publish for a new package. Do not set `NPM_TOKEN` or an `_authToken` in `.npmrc` on the publish job — that disables the OIDC exchange. Only the **publish** job has `id-token: write`.+[`build-and-prepare-chart-release.yml`](.github/workflows/build-and-prepare-chart-release.yml)+(`workflow_dispatch`):-## Troubleshooting+| Input | Default | Meaning |+| -------------------- | ------------------------- | -------------------------------------------------------------------- |+| `app_version` | `Chart.yaml` `appVersion` | npm version to install into the image |+| `update_app_version` | `false` | Also write that version into `Chart.yaml` `appVersion` on the bot PR |-- **Version Packages PR never appears** — no `.changeset/*.md` on `main` (only `config.json` / `README.md` / `pre.json` remain). Add a changeset and merge, or run **Release** via `workflow_dispatch`.-- **Publish fails requiring a tag** — prerelease versions need the `rc` dist-tag. `changeset publish` sets that while pre mode is on; for a local publish use `pnpm publish --tag rc`.-- **Publish fails with 403/E403** — version already published (npm versions are immutable), or the trusted publisher config does not match the workflow filename/repo exactly.-- **OIDC/auth error** — requires pnpm >= 11.0.7 (native OIDC; `pnpm/action-setup@v4` reads `packageManager` from the root) and a matching trusted publisher config. Remove any registry `_authToken`.-- **Missing `dist/_frontend/index.html`** — root `pnpm build` must build `frontend` before `@truefoundry/trueforge`; the pack job fails closed if the copy is absent.-- **Version PR did not regenerate the SDK** — `scripts/version.mjs` only runs `pnpm sdk:generate` when `@truefoundry/trueforge-sdk`'s version changed. That step needs Docker (available on `ubuntu-latest`).+Always: build/push `{appVersion}-{shortSha}`, patch-bump chart `version`, set `image.tag`,+open/update one PR on `release-chart/trueforge`.----+```bash+gh workflow run build-and-prepare-chart-release.yml+gh workflow run build-and-prepare-chart-release.yml -f app_version=0.1.0+# after npm publish of a new app version:+gh workflow run build-and-prepare-chart-release.yml \+ -f app_version=0.1.0 -f update_app_version=true+```-# Server image and Helm chart+You may edit chart SemVer (minor/major) on the PR before merging; the tag follows+`Chart.yaml` `version` at merge time. Each run rebuilds the `release-chart/trueforge` branch+from `main`, but a chart `version` on the branch that outranks the patch bump is carried over,+so a manual bump survives later image rebuilds. Other manual edits on that branch do not —+commit them to `main` instead.-A separate pipeline ships the deployable artifacts: the server container image (API + UI, built from the root `Dockerfile`) and the `charts/trueforge` Helm chart. It is driven by `.github/workflows/release-image-and-chart.yml` and runs only on manual **`workflow_dispatch`** (Actions → **Release image and Helm chart** → Run workflow).+## Publish Helm chart-Install a published chart with:+[`release-chart.yml`](.github/workflows/release-chart.yml) is one job with three entry points:-```bash-helm install trueforge oci://tfy.jfrog.io/tfy-helm/trueforge \- --version <x.y.z>-```--## What the workflow does+| Trigger | What it does |+| --------------------------------------------------------- | ------------------------------------------------------------------- |+| Merged PR from `release-chart/trueforge` (same repo only) | Create `charts/trueforge@<version>` + GitHub Release, then OCI push |+| Push of tag `charts/trueforge@*` | OCI push only (tag already exists) |+| `workflow_dispatch` with `tag=` | OCI push for an existing tag (retry) |-The dispatch commit SHA is the image tag. The workflow:+Only the `release-chart/trueforge` branch auto-tags. Ordinary merges never create chart tags.-1. **Builds and pushes the image** via `truefoundry/github-workflows-public/.github/workflows/build.yml@main` to the public JFrog Artifactory repository, tagged with `github.sha`.-2. **Stamps the chart in the runner workspace** — sets `Chart.yaml` `version` to `0.0.0-<sha>` (Helm SemVer-compatible prerelease), and `appVersion` / `image.tag` to the raw SHA. Those stamps are **not** committed back to `main`.-3. **Publishes the chart** — packages `charts/trueforge` and pushes it to the JFrog public OCI Helm repository (`oci://tfy.jfrog.io/tfy-helm`). It does not attach artifacts to a GitHub Release.+Chart-only example:-## Per-release flow+```bash+# after merging a PR that bumped Chart.yaml version:+git tag charts/[email protected]+git push origin charts/[email protected]+```-1. On the commit you want to ship, run the workflow from the Actions tab (or `gh workflow run release-image-and-chart.yml`).-2. Watch the run. The image and chart land in JFrog; the job summary prints the image URI.+## Dev / floating main-## Required repository configuration+External deploy repo owns `truefoundry.yaml` (`git-helm-repo` @ `main`). Build a from-source image:-**Variables:** `TRUEFOUNDRY_ARTIFACTORY_REGISTRY_URL`, `TRUEFOUNDRY_ARTIFACTORY_PUBLIC_REPOSITORY`, `TRUEFOUNDRY_ARTIFACTORY_PUBLIC_HELM_REPOSITORY`.+```bash+gh workflow run build-dev-image.yml --ref main+# → tfy.jfrog.io/tfy-images/trueforge:<fullSha>+```-**Secrets:** `TRUEFOUNDRY_ARTIFACTORY_PUBLIC_USERNAME`, `TRUEFOUNDRY_ARTIFACTORY_PUBLIC_PASSWORD`.+Patch that SHA into `image.tag`. Secrets via `secretKeyRef` only — never plaintext in git.+Do not use SHA-tagged images as production chart defaults.## Bundled chart dependencies-The chart optionally bundles Postgres and Redis (Bitnami subcharts from `oci://registry-1.docker.io/bitnamicharts`, pinned by `Chart.lock`). The workflow runs `helm dependency build` before packaging. Disable them with `postgresql.enabled=false` / `redis.enabled=false` to use external services.+Optional Postgres/Redis Bitnami subcharts (`Chart.lock`). Publish runs `helm dependency build`.+Disable with `postgresql.enabled=false` / `redis.enabled=false`.-Bitnami left the charts public but moved versioned container images to `docker.io/bitnamilegacy`. `charts/trueforge/values.yaml` points the subcharts at pinned tags mirrored on JFrog and sets `global.security.allowInsecureImages: true`. Mirror once per pinned tag:+Subchart **images** are mirrored on JFrog (`values.yaml`). Mirror once per pin:```bashfor img in \@@ -154,18 +203,15 @@ for img in \redis:8.2.1-debian-12-r0; docrane copy "docker.io/bitnamilegacy/${img}" "tfy.jfrog.io/tfy-mirror/bitnamilegacy/${img}"done-# If you enable metrics/volumePermissions, also mirror:-# postgres-exporter:0.17.1-debian-12-r16 os-shell:12-debian-12-r51-# redis-exporter:1.76.0-debian-12-r0```-To bump a bundled version: change `dependencies:` in `Chart.yaml`, run `pnpm chart:deps`, update the matching `image.tag` in `values.yaml`, and mirror the new legacy tag to JFrog.+To bump: edit `Chart.yaml` deps → `pnpm chart:deps` → update `values.yaml` image tags → mirror.-## Validating the chart locally+## Validate chart locally```bash-pnpm chart:deps # helm dependency build (uses Chart.lock)-pnpm chart:lint # helm lint with charts/trueforge/ci/lint-values.yaml-pnpm chart:template # render manifests-pnpm chart:package # package to dist/ (gitignored)+pnpm chart:deps+pnpm chart:lint+pnpm chart:template+pnpm chart:package```diff --git a/charts/trueforge/Chart.yaml b/charts/trueforge/Chart.yamlindex 4fc8273d0..df823cfca 100644--- a/charts/trueforge/Chart.yaml+++ b/charts/trueforge/Chart.yaml@@ -2,9 +2,8 @@ apiVersion: v2name: trueforgedescription: TrueForge server (API + UI) served from a single container image.type: application-# version (chart) and appVersion are stamped at publish time by-# .github/workflows/release-image-and-chart.yml (workflow_dispatch, commit SHA);-# committed values are placeholders until that workflow runs.+# version / appVersion are maintained on main (bot chart-release PR or human).+# Publishing is gated by git tag charts/trueforge@<version> (must match version).version: 0.0.1appVersion: "0.0.1"kubeVersion: ">=1.25.0-0"diff --git a/charts/trueforge/README.md b/charts/trueforge/README.mdindex 969487bed..407a675ad 100644--- a/charts/trueforge/README.md+++ b/charts/trueforge/README.md@@ -1,15 +1,17 @@# trueforge Helm chartDeploys the TrueForge server, a single container image that serves both the API-and the UI (built from the repository-root `Dockerfile`).+and the UI. **Production** images install `@truefoundry/trueforge` from npm+(repository-root [`Dockerfile`](../../Dockerfile) with `APP_VERSION`).+**Local smoke / from-source** builds use [`Dockerfile.dev`](../../Dockerfile.dev)+(see [`docker-compose.yml`](../../docker-compose.yml)).The chart always runs the server in **distributed** mode (`STANDALONE=false`) againstPostgres and Redis.-The chart version, `appVersion`, and `image.tag` are stamped at publish time by-[`.github/workflows/release-image-and-chart.yml`](../../.github/workflows/release-image-and-chart.yml)-(manual `workflow_dispatch`, commit SHA as the image tag). Committed chart-values are placeholders until that workflow runs.+Chart `version` / `appVersion` / `image.tag` are maintained on `main` (chart-release+bot PR or human). Publishing is gated by git tag `charts/trueforge@<version>`.+See [`RELEASING.md`](../../RELEASING.md).## Dev defaults (read before exposing)diff --git a/charts/trueforge/values.yaml b/charts/trueforge/values.yamlindex f39fc4faa..13a5462d4 100644--- a/charts/trueforge/values.yaml+++ b/charts/trueforge/values.yaml@@ -4,8 +4,8 @@ replicaCount: 1image:repository: tfy.jfrog.io/tfy-images/trueforge- # Tag defaults to the chart appVersion when empty; the release workflow stamps- # the released version here.+ # Tag defaults to chart appVersion when empty. Prod chart-release PRs set this+ # to {appVersion}-{shortSha} for the npm-install image already in the registry.tag: ""pullPolicy: IfNotPresentdiff --git a/docker-compose.yml b/docker-compose.ymlindex e661b65fa..4033f7a66 100644--- a/docker-compose.yml+++ b/docker-compose.yml@@ -39,6 +39,8 @@ services:server:build:context: .+ # From-source image; root Dockerfile is the npm-install prod recipe.+ dockerfile: Dockerfile.devimage: truefoundry-server:latestports:# Host 8791 avoids conflict with host `pnpm dev` on 8790.