Merge pull request 'ci: use ci-workflows@v1 again' (#66) from ci/pin-v1 into develop

v1 now contains node.yaml publishing (ci-workflows 0e0f145).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.circleci/config.yml

@@ -1,14 +0,0 @@
-version: 2.1
-setup: true
-orbs:
-  qqq-orb: kingsrook/qqq-orb@0.7.4
-workflows:
-  setup:
-    jobs:
-    - qqq-orb/generate_pipeline:
-        orb_version: 0.7.4
-        filters:
-          branches:
-            ignore: automation/qbit-rc-pending
-          tags:
-            only: /.*/

.eslintignore

@@ -1,3 +1,4 @@
 node_modules
 lib
 coverage
+lib-cjs

.gitea/workflows/build.yaml

@@ -0,0 +1,17 @@
+name: build
+on:
+  push:
+jobs:
+  node:
+    # @main until the owner moves ci-workflows v1 onto the publishing node.yaml; then back to @v1.
+    uses: self:KofTwentyTwo/ci-workflows/.gitea/workflows/node.yaml@v1
+    secrets: inherit
+    with:
+      node-version: '24'
+      commands: |
+        npm run lint
+        npm test
+        npm run prepublishOnly
+      # A vX.Y.Z[-RC.N] tag equal to package.json publishes @qrunio/qqq-frontend-core to the
+      # QRun-IO Gitea npm registry (RC -> dist-tag next). Branches only verify.
+      publish: true

.gitignore

@@ -17,3 +17,4 @@ lib
 # Claude Code local settings
 .claude/
 
+lib-cjs

.qqq-ci.yml

@@ -1,4 +0,0 @@
-profile: frontend-core
-orb_version: 0.7.4
-default_branch: develop
-node_version: '24.21'

README.md

@@ -35,6 +35,17 @@ If you want a ready-to-use admin UI, use [qqq-frontend-material-dashboard](https
 npm install @qrunio/qqq-frontend-core
 ```
 
+Releases are published to the QRun-IO Gitea npm registry (release candidates under the `next`
+dist-tag). Point the scope there in `.npmrc`:
+
+```ini
+@qrunio:registry=https://git.kof22.com/api/packages/QRun-IO/npm/
+//git.kof22.com/api/packages/QRun-IO/npm/:_authToken=${GITEA_TOKEN}
+```
+
+To release: set the version (`npm version 0.41.0-RC.1 --no-git-tag-version`), merge, and tag the
+merge commit `v<version>`; CI verifies the tag equals `package.json`, runs the checks and publishes.
+
 ```typescript
 import { QController } from '@qrunio/qqq-frontend-core';
 

docs/npm-publishing.md

@@ -1,12 +1,19 @@
-# npm publishing
-
-CircleCI publishes `@qrunio/qqq-frontend-core` with npm Trusted Publishing using `kingsrook/qqq-orb@0.6.8` and `cimg/node:24.21`. In the package Settings on npmjs.com, add a **CircleCI** trusted publisher with the values below and explicitly allow **npm publish** (the staged-only default does not run this pipeline). Existing workflow branch filters and dist-tags remain in place.
-
-| npm field | Value |
-| --- | --- |
-| Organization ID | `bb329fea-03cd-4fb5-b530-15e85703598d` |
-| Project ID | `5bd1e544-282a-4080-afc1-36ffdebf5487` |
-| Pipeline definition ID | `3bd87740-26e6-5f18-8600-10685a13a81e` |
-| VCS origin | `github.com/QRun-IO/qqq-frontend-core` |
-
-These are public identifiers, not credentials. The job obtains a short-lived npm-audience OIDC identity only for publication, so no new `NPM_TOKEN` is needed. Do not use `npm whoami` or a publish dry run as proof: verify the real immutable version at npm and install it in a clean consumer. Once that succeeds, remove obsolete token access only after checking its other consumers. CircleCI Trusted Publishing currently does not attach npm provenance attestations. See [npm documentation](https://docs.npmjs.com/trusted-publishers/).
+# npm publishing
+
+CircleCI publishes `@qrunio/qqq-frontend-core` with npm Trusted Publishing through the shared `frontend-core` profile in `.qqq-ci.yml`. The canonical caller tracks `kingsrook/qqq-orb@0.8` and uses `cimg/node:24.21`. Publishing logic lives in the orb, not in a repository-specific workflow. In the package Settings on npmjs.com, add a **CircleCI** trusted publisher with the values below and explicitly allow **npm publish** (the staged-only default does not run this pipeline).
+
+Develop snapshots use build-specific versions such as `0.40.28-SNAPSHOT.1234`
+and the npm `snapshot` dist-tag. The version is calculated in the publishing
+workspace; the job does not push a version-only `[skip ci]` commit back to
+`develop`. Required checks therefore stay attached to the source head being
+published. See [version management](version-management.md) and the
+[shared orb policy](https://github.com/QRun-IO/qqq-orb/blob/main/docs/GENERATED-PIPELINES.md#node-snapshot-versions).
+
+| npm field | Value |
+| --- | --- |
+| Organization ID | `bb329fea-03cd-4fb5-b530-15e85703598d` |
+| Project ID | `5bd1e544-282a-4080-afc1-36ffdebf5487` |
+| Pipeline definition ID | `3bd87740-26e6-5f18-8600-10685a13a81e` |
+| VCS origin | `github.com/QRun-IO/qqq-frontend-core` |
+
+These are public identifiers, not credentials. The job obtains a short-lived npm-audience OIDC identity only for publication, so no new `NPM_TOKEN` is needed. Do not use `npm whoami` or a publish dry run as proof: verify the real immutable version at npm and install it in a clean consumer. Once that succeeds, remove obsolete token access only after checking its other consumers. CircleCI Trusted Publishing currently does not attach npm provenance attestations. See [npm documentation](https://docs.npmjs.com/trusted-publishers/).

docs/version-management.md

@@ -1,42 +1,46 @@
-# Version Management
-
-## Current Versions (as of 2026-01-12)
-
-| Package | Version | Registry |
-|---------|---------|----------|
-| `@qrunio/qqq-frontend-core` | 0.40.1-SNAPSHOT | npm |
-| `qqq-frontend-material-dashboard` | 0.40.1-SNAPSHOT | Maven Central |
-| `qqq` (backend) | 0.40.0-SNAPSHOT | Maven Central |
-
-## Frontend vs Backend Versioning
-
-Frontend repos can version independently from the backend. In `qqq-frontend-material-dashboard`:
-
-```xml
-<properties>
-  <revision>0.40.1-SNAPSHOT</revision>      <!-- This artifact's version -->
-  <qqq.version>0.40.0-SNAPSHOT</qqq.version> <!-- Backend dependency version -->
-</properties>
-```
-
-This allows frontend-only releases without requiring a full backend release.
-
-## Version Bump Process
-
-### qqq-frontend-core (npm)
-1. Update `version` in `package.json`
-2. Push to develop branch
-3. CI automatically publishes to npm
-
-### qqq-frontend-material-dashboard (Maven)
-1. Update `revision` property in `pom.xml`
-2. Optionally update `qqq.version` if backend changes needed
-3. Push to develop branch
-4. CI runs Playwright tests + publishes to Maven Central
-
-## CI/CD Orb Behavior
-
-The `kingsrook/qqq-orb` `calculate_version.sh` script:
-- For develop branch with existing SNAPSHOT: keeps current version
-- Only bumps version on release merges or RC versions
-- Each repo manages its own version independently
+# Version Management
+
+## Historical Versions (2026-01-12)
+
+| Package | Version | Registry |
+|---------|---------|----------|
+| `@qrunio/qqq-frontend-core` | 0.40.1-SNAPSHOT | npm |
+| `qqq-frontend-material-dashboard` | 0.40.1-SNAPSHOT | Maven Central |
+| `qqq` (backend) | 0.40.0-SNAPSHOT | Maven Central |
+
+## Frontend vs Backend Versioning
+
+Frontend repos can version independently from the backend. In `qqq-frontend-material-dashboard`:
+
+```xml
+<properties>
+  <revision>0.40.1-SNAPSHOT</revision>      <!-- This artifact's version -->
+  <qqq.version>0.40.0-SNAPSHOT</qqq.version> <!-- Backend dependency version -->
+</properties>
+```
+
+This allows frontend-only releases without requiring a full backend release.
+
+## Version Bump Process
+
+### qqq-frontend-core (npm)
+1. Merge a verified source change to `develop` through the shared required checks.
+2. The orb calculates `MAJOR.MINOR.NEXT_PATCH-SNAPSHOT.CIRCLE_BUILD_NUM` from the source package version and the unique CircleCI job number. For example, source `0.40.27-SNAPSHOT` in job 1234 publishes `0.40.28-SNAPSHOT.1234`.
+3. CI builds and publishes that immutable npm version under the `snapshot` dist-tag. It keeps the source branch unchanged; no snapshot version commit or manual per-build version bump is needed.
+4. Verify the published version and install it in a clean consumer before claiming publication success. CI-only declaration updates may run verification without publishing.
+
+Stable, RC and hotfix publication keep their existing shared orb policies. A
+snapshot publication is not a stable release.
+
+### qqq-frontend-material-dashboard (Maven)
+1. Update `revision` property in `pom.xml`
+2. Optionally update `qqq.version` if backend changes needed
+3. Push to develop branch
+4. CI runs Playwright tests + publishes to Maven Central
+
+## CI/CD Orb Behavior
+
+For Maven projects, the shared orb's `calculate_version.sh` script:
+- For develop branch with existing SNAPSHOT: keeps current version
+- Only bumps version on release merges or RC versions
+- Each repo manages its own version independently

package-lock.json

@@ -1,12 +1,12 @@
 {
    "name": "@qrunio/qqq-frontend-core",
-   "version": "0.40.21-SNAPSHOT",
+   "version": "0.40.27-RC.1",
    "lockfileVersion": 3,
    "requires": true,
    "packages": {
       "": {
          "name": "@qrunio/qqq-frontend-core",
-         "version": "0.40.21-SNAPSHOT",
+         "version": "0.40.27-RC.1",
          "license": "Apache-2.0",
          "dependencies": {
             "axios": "0.34.0",

package.json

@@ -1,15 +1,16 @@
 {
    "name": "@qrunio/qqq-frontend-core",
-   "version": "0.40.22-SNAPSHOT",
+   "version": "0.40.27-RC.1",
    "description": "",
-   "main": "qqq-frontend-core.js",
-   "module": "lib/qqq-frontend-core.esm.js",
+   "main": "lib-cjs/qqq-frontend-core.js",
+   "module": "lib/qqq-frontend-core.js",
+   "types": "lib/qqq-frontend-core.d.ts",
    "scripts": {
       "delete-modules": "rm -rf node_modules; rm package-lock.json",
       "lint": "eslint . --ext .ts",
       "npm-install": "npm install",
       "clean-and-install": "npm ci && npm run prepublishOnly",
-      "prepublishOnly": "rm -rf lib/ && tsc -p ./ --outDir lib/",
+      "prepublishOnly": "node scripts/clean-build.cjs && tsc -p ./ --outDir lib/ && tsc -p ./ --module commonjs --outDir lib-cjs/",
       "test": "jest",
       "yalc-push": "npm run prepublishOnly && yalc push --private",
       "yalc-watch": "yalc-watch"
@@ -21,6 +22,7 @@
    "keywords": [],
    "files": [
       "lib",
+      "lib-cjs",
       "package.json",
       "NOTICE"
    ],
@@ -31,7 +33,7 @@
       "url": "https://github.com/QRun-IO/qqq-frontend-core"
    },
    "publishConfig": {
-      "registry": "https://registry.npmjs.org/"
+      "registry": "https://git.kof22.com/api/packages/QRun-IO/npm/"
    },
    "devDependencies": {
       "@types/jest": "^27.0.2",

scripts/clean-build.cjs

@@ -0,0 +1,7 @@
+const {rmSync} = require("node:fs");
+const {resolve} = require("node:path");
+
+// Resolve only these build outputs relative to the repository, never the caller's cwd.
+for (const directory of ["lib", "lib-cjs"]) {
+   rmSync(resolve(__dirname, "..", directory), {recursive: true, force: true});
+}

src/qqq-frontend-core.ts

@@ -23,7 +23,7 @@ import {QFieldMetaData} from "./model/metaData/QFieldMetaData";
 import {QFieldType} from "./model/metaData/QFieldType";
 import {QTableMetaData} from "./model/metaData/QTableMetaData";
 
-module.exports = {
+export {
    QController,
    QTableMetaData,
    QFieldMetaData,

tests/PackageExports.test.ts

@@ -0,0 +1,32 @@
+/*
+ * QQQ - Low-code Application Framework for Engineers.
+ * Copyright (C) 2021-2022.  Kingsrook, LLC
+ * 651 N Broad St Ste 205 # 6917 | Middletown DE 19709 | United States
+ * contact@kingsrook.com
+ * https://github.com/Kingsrook/
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {QController, QFieldMetaData, QFieldType, QTableMetaData} from "../src/qqq-frontend-core";
+
+describe("public package exports", () =>
+{
+   it("exposes the controller and metadata constructors", () =>
+   {
+      expect(typeof QController).toBe("function");
+      expect(typeof QTableMetaData).toBe("function");
+      expect(new QFieldMetaData({name: "id", type: QFieldType.INTEGER}).name).toBe("id");
+      expect(QFieldType.INTEGER).toBeDefined();
+   });
+});