qcobjects-cli 2.5.143-beta → 2.5.145-beta

package/.cursor/rules/collaboration-features.mdc

@@ -0,0 +1,25 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Collaboration Features
+
+## Overview
+The project includes real-time collaboration features implemented through:
+- Core collab functionality: [src/qcobjects-collab.ts](mdc:src/qcobjects-collab.ts)
+- Collab server implementation: [src/collab-server.ts](mdc:src/collab-server.ts)
+
+## Client Services
+Client-side services are managed through:
+- Main services: [src/client_services.ts](mdc:src/client_services.ts)
+- API client services: [src/api-client_services.ts](mdc:src/api-client_services.ts)
+
+## Enterprise Features
+Enterprise-specific commands and features:
+- Enterprise commands: [src/enterprise-commands.ts](mdc:src/enterprise-commands.ts)
+- JIRA integration: [src/cli-commands-jira.ts](mdc:src/cli-commands-jira.ts)
+
+## Security
+- Certificate creation utilities: [src/qcobjects-createcert.ts](mdc:src/qcobjects-createcert.ts)
+- Key generation script: [generatekeys.sh](mdc:generatekeys.sh)

package/.cursor/rules/development-guidelines.mdc

@@ -0,0 +1,37 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Development Guidelines
+
+## TypeScript Configuration
+The project uses TypeScript with strict type checking. Configuration is split across multiple files:
+- Main config: [tsconfig.json](mdc:tsconfig.json)
+- Declaration config: [tsconfig.d.json](mdc:tsconfig.d.json)
+- Test config: [tsconfig.jasmine.json](mdc:tsconfig.jasmine.json)
+
+## Code Style
+ESLint is used for code style enforcement:
+- ESLint config: [eslint.config.mjs](mdc:eslint.config.mjs)
+
+## Testing
+- Test specifications are located in the [spec/](mdc:spec) directory
+- Use Jasmine for writing tests
+
+## Build Process
+The build process uses ESBuild for bundling:
+- Build script: [build-esbuild.js](mdc:build-esbuild.js)
+- Build command implementation: [src/cli-commands-build-esbuild.ts](mdc:src/cli-commands-build-esbuild.ts)
+
+## Adding New CLI Commands
+When adding new CLI commands:
+1. Create a new file in `src/` with pattern `cli-commands-*.ts`
+2. Register the command in [src/cli-commands.ts](mdc:src/cli-commands.ts)
+3. Implement the command following existing patterns in other command files
+
+## Server Implementation
+When working with server components:
+- Base HTTP server: [src/qcobjects-http-server.ts](mdc:qcobjects-http-server.ts)
+- Main server implementation: [src/main-http-server.ts](mdc:src/main-http-server.ts)
+- Follow existing patterns for error handling and logging

package/.cursor/rules/project-structure.mdc

@@ -0,0 +1,36 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# QCObjects CLI Project Structure
+
+This is a TypeScript-based CLI tool for QCObjects framework. Here's the key structure:
+
+## Entry Points
+- Main CLI entry: [src/cli-main.ts](mdc:src/cli-main.ts)
+- Core CLI implementation: [src/qcobjects-cli.ts](mdc:src/qcobjects-cli.ts)
+
+## Core Components
+- Server implementations:
+  - HTTP: [src/qcobjects-http-server.ts](mdc:src/qcobjects-http-server.ts)
+  - HTTP2: [src/qcobjects-http2-server.ts](mdc:src/qcobjects-http2-server.ts)
+  - GAE: [src/qcobjects-gae-http-server.ts](mdc:src/qcobjects-gae-http-server.ts)
+
+## CLI Commands
+The CLI commands are modularized in separate files:
+- Build commands:
+  - ESBuild: [src/cli-commands-build-esbuild.ts](mdc:src/cli-commands-build-esbuild.ts)
+  - TypeScript: [src/cli-commands-build-typescript.ts](mdc:src/cli-commands-build-typescript.ts)
+- Version management: [src/cli-commands-version.ts](mdc:src/cli-commands-version.ts)
+- Static publishing: [src/cli-commands-publish-static.ts](mdc:src/cli-commands-publish-static.ts)
+- JIRA integration: [src/cli-commands-jira.ts](mdc:src/cli-commands-jira.ts)
+
+## Configuration
+- Default settings: [src/defaultsettings.ts](mdc:src/defaultsettings.ts)
+- Project config: [config.json](mdc:config.json)
+- TypeScript config: [tsconfig.json](mdc:tsconfig.json)
+
+## Build System
+- ESBuild configuration: [build-esbuild.js](mdc:build-esbuild.js)
+- Transpilation setup: [transpile.js](mdc:transpile.js)

package/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [main, development]
+  pull_request:
+    branches: [main, development]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # TODO: Add setup step for your language/runtime
+      # TODO: Add lint step (e.g., ruff check .)
+      - name: Lint (placeholder)
+        run: echo "Replace with your linter command"
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # TODO: Add setup step for your language/runtime
+      # TODO: Add test step (e.g., pytest -v)
+      - name: Test (placeholder)
+        run: echo "Replace with your test command"

package/.github/workflows/main-pr-source.yml

@@ -0,0 +1,26 @@
+# Enforce that pull requests into main come only from development.
+# In GitHub: Settings -> Branches -> Branch protection for main ->
+# require status checks and select the job from this workflow.
+name: Main PR source
+
+on:
+  pull_request:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  allowed-source-for-main:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Require head branch development for PRs to main
+        run: |
+          head="${{ github.head_ref }}"
+          if [ "$head" = "development" ]; then
+            echo "OK: PR head is development."
+            exit 0
+          fi
+          echo "::error::Pull requests to main must use development as the head branch (got: $head)."
+          exit 1

package/.github/workflows/npmpublish-beta.yml

@@ -5,8 +5,6 @@ name: Node.js Publish Beta version
 
 on:
   push:
-    branches:
-      - 'v*.*-beta'
     tags:
       - 'v*.*.*-beta'
 
@@ -14,26 +12,32 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3.3.0
-      - uses: actions/setup-node@v3.6.0
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          ref: ${{ github.ref }}
+      - uses: actions/setup-node@v4
         with:
           node-version: 22
-      - run: npm i --legacy-peer-deps && npm ci --legacy-peer-deps --install-strategy=nested
+      - run: npm i --legacy-peer-deps
       - run: npm test
 
   publish-npm:
     needs: build
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
     steps:
-      - uses: actions/checkout@v3.3.0
-      - uses: actions/setup-node@v3.6.0
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          ref: ${{ github.ref }}
+      - uses: actions/setup-node@v4
         with:
           node-version: 22
-          registry-url: https://registry.npmjs.org/
-      - name: Set up NPM authentication
-        run: echo "registry=https://registry.npmjs.org/:_authToken=${{secrets.NPM_TOKEN}}" >> ~/.npmrc
-      - run: npm i --legacy-peer-deps && npm ci --legacy-peer-deps --install-strategy=nested
+      - name: Upgrade npm for OIDC support (requires >=11.5.1)
+        run: npm install -g npm@latest
+      - run: npm i --legacy-peer-deps
       - run: npm test
-      - run: npm publish --tag ${GITHUB_REF##*/}
-        env:
-          NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}
+      - run: npm publish --tag beta

package/.github/workflows/npmpublish-lts.yml

@@ -5,8 +5,6 @@ name: Node.js Publish LTS version
 
 on:
   push:
-    branches:
-      - 'v*.*-lts'
     tags:
       - 'v*.*.*-lts'
 
@@ -14,25 +12,31 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3.3.0
-      - uses: actions/setup-node@v3.6.0
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          ref: ${{ github.ref }}
+      - uses: actions/setup-node@v4
         with:
           node-version: 22
-      - run: npm ci --legacy-peer-deps
+      - run: npm i --legacy-peer-deps
       - run: npm test
 
   publish-npm:
     needs: build
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
     steps:
-      - uses: actions/checkout@v3.3.0
-      - uses: actions/setup-node@v3.6.0
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          ref: ${{ github.ref }}
+      - uses: actions/setup-node@v4
         with:
           node-version: 22
-          registry-url: https://registry.npmjs.org/
-      - name: Set up NPM authentication
-        run: echo "registry=https://registry.npmjs.org/:_authToken=${{secrets.NPM_TOKEN}}" >> ~/.npmrc
-      - run: npm ci --legacy-peer-deps
-      - run: npm publish --tag ${GITHUB_REF##*/}
-        env:
-          NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}
+      - name: Upgrade npm for OIDC support (requires >=11.5.1)
+        run: npm install -g npm@latest
+      - run: npm i --legacy-peer-deps
+      - run: npm publish --tag lts

package/.github/workflows/npmpublish-main.yml

@@ -5,8 +5,6 @@ name: Node.js Publish Package
 
 on:
   push:
-    branches:
-      - main
     tags:
       - 'v*.*.*'
 
@@ -14,25 +12,31 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3.3.0
-      - uses: actions/setup-node@v3.6.0
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          ref: ${{ github.ref }}
+      - uses: actions/setup-node@v4
         with:
           node-version: 22
-      - run: npm ci --legacy-peer-deps
+      - run: npm i --legacy-peer-deps
       - run: npm test
 
   publish-npm:
     needs: build
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
     steps:
-      - uses: actions/checkout@v3.3.0
-      - uses: actions/setup-node@v3.6.0
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          ref: ${{ github.ref }}
+      - uses: actions/setup-node@v4
         with:
           node-version: 22
-          registry-url: https://registry.npmjs.org/
-      - name: Set up NPM authentication
-        run: echo "registry=https://registry.npmjs.org/:_authToken=${{secrets.NPM_TOKEN}}" >> ~/.npmrc
-      - run: npm ci --legacy-peer-deps
+      - name: Upgrade npm for OIDC support (requires >=11.5.1)
+        run: npm install -g npm@latest
+      - run: npm i --legacy-peer-deps
       - run: npm publish
-        env:
-          NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}

package/.github/workflows/open-pr-to-development.yml

@@ -0,0 +1,70 @@
+# When you push to feature/*, fix/*, or bugfix/*, open a PR into development if none exists yet.
+# Runs entirely on GitHub Actions (no local GitHub CLI required).
+#
+# REQUIRED — or POST /pulls returns 403 "not permitted to create or approve pull requests":
+#   Repo: Settings -> Actions -> General -> Workflow permissions
+#   - Select "Read and write permissions"
+#   - Enable "Allow GitHub Actions to create and approve pull requests"
+#   Orgs: enable the same policy at the organization level first, then the repo checkbox unlocks.
+name: Open PR to development
+
+on:
+  push:
+    branches:
+      - "feature/**"
+      - "fix/**"
+      - "bugfix/**"
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  open-pr:
+    runs-on: ubuntu-latest
+    if: ${{ !github.event.repository.fork }}
+    steps:
+      - name: Create pull request if missing
+        uses: actions/github-script@v8
+        with:
+          script: |
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+            const branch = context.ref.replace("refs/heads/", "");
+            const head = `${owner}:${branch}`;
+
+            const { data: openPrs } = await github.rest.pulls.list({
+              owner,
+              repo,
+              head,
+              base: "development",
+              state: "open",
+              per_page: 100,
+            });
+            if (openPrs.length > 0) {
+              console.log(`Open PR already exists: #${openPrs[0].number}`);
+              return;
+            }
+
+            const { data: commit } = await github.rest.repos.getCommit({
+              owner,
+              repo,
+              ref: context.sha,
+            });
+            const raw = commit.commit.message || "";
+            const title = (raw.split("\n")[0] || branch).trim().slice(0, 300) || branch;
+            const body = [
+              `Opened automatically when \`${branch}\` was pushed.`,
+              "",
+              "_Edit the title or description if needed._",
+            ].join("\n");
+
+            const { data: created } = await github.rest.pulls.create({
+              owner,
+              repo,
+              title,
+              head: branch,
+              base: "development",
+              body,
+            });
+            console.log(`Created PR #${created.number}: ${created.html_url}`);

package/.opencode/instructions/git-workflow.md

@@ -0,0 +1,46 @@
+---
+description: Git workflow — topic branches; no rebase; SemVer tags; how to sync
+alwaysApply: true
+---
+
+# Git workflow
+
+## Branching and PRs (default)
+
+- **Do not** commit new work **directly** on **`main`** or **`development`**. Use a **topic branch** from **`development`**:
+  `git fetch origin` then `git checkout -b feature/<topic> development` (or `fix/<topic>` / `bugfix/<topic>`).
+- **Push** the topic branch and open a PR into **`development`** via the GitHub UI or `gh pr create`.
+- Merge to **`development`** via **PR** after review.
+- Promotion **`development` → `main`** uses a release PR.
+
+**Exception:** If the user **explicitly** asks to commit or push **directly** to **`development`** or **`main`** (e.g. maintainer emergency), follow their instruction and remind them it bypasses the usual topic-branch flow.
+
+## Never use `git rebase`
+
+Prefer plain **`git pull`** (merge) when updating from remote, unless the user specifies otherwise. Do not use **`git pull --rebase`** or **`git rebase`** for this repo's workflow.
+
+## When the user says "sync git"
+
+Meaning: **save local work and push the current branch** to the remote — **not** "skip branching."
+
+1. If the current branch is **`main`** or **`development`** and there are **new** changes, **prefer** moving work to a topic branch first (unless the user explicitly wants a direct push — see Exception above):
+   e.g. `git fetch origin && git checkout -b feature/<short-description> development`, then bring commits across if needed.
+2. Stage, commit with a **clear message**, push:
+   ```bash
+   git add .
+   git commit -m "<concise message describing the changes>"
+   git push -u origin HEAD
+   ```
+   Use `-u origin HEAD` when the branch has no upstream yet; otherwise `git push`. If there is **nothing to commit**, run **`git push`** if there are unpushed commits.
+3. **Untracked files:** Use **`git add .**` (or add paths explicitly); do not rely on **`git commit -a`** alone if new files exist.
+
+Do not substitute stash/rebase flows for "sync git" unless the user asks for a pull-only or merge-from-remote step.
+
+## Opening a PR
+
+Use the GitHub UI, **`gh pr create`**, or a configured auto-PR workflow (see `.github/workflows/`). Provide a clear title and description of the changes.
+
+## Releases and tags
+
+- **Feature releases:** Open a PR from **`development`** to **`main`**, merge, then tag on **`main`** with an **annotated** SemVer tag: `git tag -a vMAJOR.MINOR.PATCH -m "<description>"`. Push the tag: `git push origin vMAJOR.MINOR.PATCH`.
+- **Integration tags:** After a feature/fix/bugfix PR merges into **`development`**, optionally tag with `vMAJOR.MINOR.PATCH-dev.N` on **`development`**.

package/.pre-commit-config.yaml

@@ -0,0 +1,9 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+        args: [--maxkb=500]

package/AGENTS.md

@@ -0,0 +1,59 @@
+# qcobjects-cli
+
+TypeScript CLI tool and HTTP/HTTP2 server for the [QCObjects](https://qcobjects.dev) framework.
+Node >=22, npm >=10.
+
+## Git workflow
+
+See `.opencode/instructions/git-workflow.md` — topic branches from `development`, no rebase, SemVer tags.
+
+## Commands
+
+| Action | Command |
+|--------|---------|
+| Install | `npm install` |
+| Lint | `npm run lint` (`eslint src/**/*.ts --fix`) |
+| Test | `npm test` (lint → jasmine) |
+| Run single test | `npx ts-node --project ./tsconfig.jasmine.json ./node_modules/jasmine/bin/jasmine` |
+| Build (types → ts → esm) | `npm run build` |
+| Build TS only | `npm run build:ts` — **runs `npm test` first**, then `node ./transpile.js tsconfig.json` |
+| Build types only | `npm run build:ts-types` |
+| Build ESM bundle | `npm run build:esbuild` |
+| Dev server | `npm start` (aliased to `qcobjects-shell`) |
+
+## Architecture
+
+- **CLI framework:** Commander (`src/cli-main.ts` — `SwitchCommander` class)
+- **Commands** in `src/cli-commands-*.ts`, registered via `src/cli-commands.ts`
+- **Servers:** HTTP (`src/main-http-server.ts`), HTTP/2 (`src/main-http2-server.ts`), GAE variant
+- **Build pipeline:** Custom `transpile.js` (TS compiler API) produces CJS → `esbuild` produces ESM + browser IIFE
+- **Output:** `public/cjs/`, `public/esm/`, `public/browser/`, `public/types/`
+
+## Testing quirks
+
+- **Framework:** Jasmine v3.7 (`spec/support/jasmine.json`)
+- Single spec: `spec/testsSpec.ts` — verifies `qcobjects` version matches between `peerDependencies` and `devDependencies`
+- Mock path in `tsconfig.jasmine.json`: `qcobjects-sdk` → `spec/mocks/qcobjects-sdk.mock.ts`
+- Config: `stopSpecOnExpectationFailure: true`, `failSpecWithNoExpectations: true`, `random: false`
+
+## QCObjects patterns used in source
+
+- `InheritClass`, `Package()`, `Export()`, `CONFIG`, `logger`, `Service`, `Component`
+- Plugin autodiscovery: scans `dependencies`/`devDependencies` for packages with `qcobjects-lib`, `qcobjects-handler`, `qcobjects-command` keywords
+
+## Config & env
+
+- `config.json` at root — runtime config
+- `src/defaultsettings.ts` — `$ENV(VAR)` template syntax resolved at runtime
+- `process.env.PORT` overrides HTTP listen port
+- Dev mode: `config.json` `{"devmode":"debug"}`
+
+## Pre-commit
+
+`.pre-commit-config.yaml`: trailing-whitespace, end-of-file-fixer, check-yaml, check-added-large-files (500 KB max).
+Run `pre-commit install` to activate hooks.
+
+## Build artifacts
+
+- `build/templates/` — compiled template copies
+- Lockfile: `package-lock.json` only (no yarn/pnpm)

package/README.md

@@ -35,6 +35,81 @@ To start|stop|prestart the service:
 > service qcobjects restart
 ```
 
+## Synced Semantic Versioning
+
+Version management is handled through the `VERSION` file at the project root. Commands read from and write to this file, and can optionally sync changes to `package.json` and git.
+
+### `v-patch [filename]`
+
+Bumps the patch number (e.g., `1.2.3` → `1.2.4`). Default filename is `VERSION`.
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--sync-git` | `--git` | Commit changes, tag, and push to git |
+| `--sync-npm` | `--npm` | Also update `package.json` via `npm version` (implies `--git`) |
+| `--commit-msg [message]` | `-m` | Custom commit message |
+
+```shell
+# Just bump the VERSION file
+qcobjects v-patch
+
+# Bump, commit, tag, and push
+qcobjects v-patch --git -m "fix: resolve timeout issue"
+
+# Bump VERSION + package.json, commit, tag, push
+qcobjects v-patch --git --npm
+```
+
+### `v-minor [filename]`
+
+Bumps the minor number (e.g., `1.2.3` → `1.3.0`). Supports the same options as `v-patch`.
+
+```shell
+qcobjects v-minor --git -m "feat: add collaboration endpoints"
+```
+
+### `v-major [filename]`
+
+Bumps the major number (e.g., `1.2.3` → `2.0.0`). Supports the same options as `v-patch`.
+
+```shell
+qcobjects v-major --git --npm -m "breaking: migrate to new API"
+```
+
+### `v-sync [filename]`
+
+Reads the current version from `git describe` (latest tag), writes it to the `VERSION` file, updates `package.json` with `npm version`, commits, tags, and pushes.
+
+| Option | Description |
+|--------|-------------|
+| `-m, --commit-msg [message]` | Commit message (default: `Synced Version v<version>`) |
+
+```shell
+qcobjects v-sync -m "sync after release merge"
+```
+
+### `v-changelog`
+
+Generates a changelog from annotated git tags, grouped by minor version, printed to stdout.
+
+```shell
+qcobjects v-changelog > CHANGELOG.md
+```
+
+### Typical workflow
+
+```shell
+# 1. Bump the patch version and push everything
+qcobjects v-patch --git --npm -m "your message"
+
+# 2. CI publishes the new version to npm
+
+# 3. Generate changelog for release notes
+qcobjects v-changelog > CHANGELOG.md
+```
+
+---
+
 ```shell
    .d88888b.  .d8888b.  .d88888b. 888       d8b                888
   d88P" "Y88bd88P  Y88bd88P" "Y88b888       Y8P                888

package/VERSION

@@ -1 +1 @@
-2.5.143-beta
+2.5.145-beta