@mriekki/project-forge 4.23.0 → 4.24.0

package/assets/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.23.0",
+  "version": "4.24.0",
   "defaultProfile": "greenfield-project",
   "profiles": {
     "greenfield-project": {
@@ -13,8 +13,8 @@
   },
   "components": {
     "core": {
-      "revision": "970b7d89c9a2d71cb10c42482cdccc2c43cf9ee3",
-      "version": "4.1.0",
+      "revision": "1e5d8488b00b1a6e7cb0aa131757aaf859849d43",
+      "version": "4.2.0",
       "distribution": "greenfield-workspace",
       "descriptor": "assets/core/distribution.json",
       "sourceRoot": "assets/generated/core",

package/assets/core/distribution.json

@@ -290,6 +290,14 @@
     {
       "source": "core/instructions/project-forge-web-guidance.instructions.md",
       "destination": ".github/instructions/project-forge-web-guidance.instructions.md"
+    },
+    {
+      "source": "tools/setup_maintenance/maintenance.py",
+      "destination": "tools/project-forge-setup/maintenance.py"
+    },
+    {
+      "source": "core/process/WORKSTATION_MAINTENANCE.md",
+      "destination": "docs/process/WORKSTATION_MAINTENANCE.md"
     }
   ]
 }

package/assets/generated/ASSEMBLY.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.23.0",
+  "version": "4.24.0",
   "components": {
     "core": {
-      "revision": "970b7d89c9a2d71cb10c42482cdccc2c43cf9ee3",
-      "version": "4.1.0",
+      "revision": "1e5d8488b00b1a6e7cb0aa131757aaf859849d43",
+      "version": "4.2.0",
       "distribution": "greenfield-workspace",
       "files": [
         {
@@ -21,7 +21,7 @@
         {
           "source": "core/instructions/project-forge-workflow.instructions.md",
           "destination": ".github/instructions/project-forge-workflow.instructions.md",
-          "sha256": "34edc558291ee6b4f6c0a613b2869f00628ec78b9b02056e9724a7e1cc9eb7ee"
+          "sha256": "c2ab2b578c3b5b47d79f9aa64daeafcd40c89cfa8924244177950bdf4e10115b"
         },
         {
           "source": "core/instructions/project-forge-local-development.instructions.md",
@@ -56,7 +56,7 @@
         {
           "source": "core/skills/setup/SKILL.md",
           "destination": ".github/skills/setup/SKILL.md",
-          "sha256": "043e37fcad21cfa9c437694c628e7070d566744008612c33440a56d54b99dcb6"
+          "sha256": "8f92aed1684a3dfd2ecffeb584b5da4daa9c7d7d7ab7ca7f01c8c6a4c82eaa1d"
         },
         {
           "source": "core/skills/build/SKILL.md",
@@ -226,7 +226,7 @@
         {
           "source": "core/process/SETUP_ACCEPTANCE_CHECKLIST.md",
           "destination": "docs/process/SETUP_ACCEPTANCE_CHECKLIST.md",
-          "sha256": "41f97f81b8755920e0a6b86c6bf660800ff2ddcd48a1a07ab12e4fa7dfa16593"
+          "sha256": "8bf7936d8ae33b1656532669a278b3c73aaf4d47f87e641d48bfb38ecd8c56b5"
         },
         {
           "source": "core/process/OPERATION_JOURNAL.md",
@@ -372,6 +372,16 @@
           "source": "core/instructions/project-forge-web-guidance.instructions.md",
           "destination": ".github/instructions/project-forge-web-guidance.instructions.md",
           "sha256": "5e9c32ea86d0ad868882ec8d6c5263931cd12eb26d7f9a432dfae1895f8b0738"
+        },
+        {
+          "source": "tools/setup_maintenance/maintenance.py",
+          "destination": "tools/project-forge-setup/maintenance.py",
+          "sha256": "38cb6bff3153b48ef2dfd099a168dada4079455a4e1798f0e6758034c0faf3df"
+        },
+        {
+          "source": "core/process/WORKSTATION_MAINTENANCE.md",
+          "destination": "docs/process/WORKSTATION_MAINTENANCE.md",
+          "sha256": "79c8e74afa3e219b1486664a570c5c7a7d8f007652d0bcb3f26cf11d7b415fde"
         }
       ]
     },

package/assets/generated/core/core/instructions/project-forge-workflow.instructions.md

@@ -14,6 +14,8 @@ Possible sources include Product Briefs, Feature Briefs, Engineering Enablers, J
 
 Use proportional rigor: `LIGHT`, `STANDARD`, `ELEVATED`.
 
+For ongoing tool maintenance use `/setup update` with the catalog-driven preview/approval/check contract. Do not turn normal `/setup` into a blanket package upgrade or change project-pinned runtimes and managed assets through a workstation update.
+
 Keep explicit human gates for material requirements, substantive plans, meaningful implementation acceptance, the final merge/delivery decision, and production deployment.
 
 Before any substantive approval gate, identify the exact PRIMARY review subject for the current work item/scope and put the best available review surface in front of the human when the host supports it. Treat supporting documents as CONTEXT or TRACEABILITY instead of opening everything. For Markdown prefer rendered preview, for structured approval artifacts prefer formatted source plus a concise summary, for implementation acceptance prefer the meaningful diff/Source Control surface, and for plans prefer the native plan surface or durable plan document. Opening or foregrounding a review surface is read-only presentation and never implies approval.

package/assets/generated/core/core/process/SETUP_ACCEPTANCE_CHECKLIST.md

@@ -14,6 +14,11 @@ Use this checklist after creating or adopting a Project Forge workspace and befo
 - [ ] Optional tools are either available or consciously deferred.
 - [ ] For browser-facing Projects, the exact Modern Web Guidance CLI/Node prerequisites are verified or explicitly deferred; telemetry is disabled without third-party agent-file overwrites.
 
+## Ongoing tool maintenance (optional)
+
+- [ ] `/setup status` can report known installed versions and catalog update eligibility without any write.
+- [ ] `/setup update` requires an exact reviewed plan before upgrading selected tools; pinned Project dependencies and managed Project Forge profiles are excluded.
+
 ## Repository / workspace
 
 - [ ] Git repository and remote state are understood.

package/assets/generated/core/core/process/WORKSTATION_MAINTENANCE.md

@@ -0,0 +1,19 @@
+# Workstation maintenance via /setup
+
+The existing `/setup` command installs missing declared prerequisites; `/setup repair` repairs broken prerequisites; `/setup status` inspects workstation tools read-only; and `/setup update` is the explicit, reviewed ongoing upgrade path.
+
+## Exact source and preview
+
+Use `python tools/project-forge-setup/maintenance.py status` to inspect installed versions and eligibility, or `status --record-check` during normal non-read-only `/setup` to retain only a local check timestamp in ignored `.project-forge/`. At a normal `/setup` call, suggest a check approximately every 30 days if there is no newer recorded check. This is not a scheduled/background service.
+
+Use `python tools/project-forge-setup/maintenance.py update [--tool rtk ...]` for the default non-mutating preview of selected safe candidates. The exact tool IDs, manager commands, installed versions, pins and SHA-256 in this output define the approval scope. Only after the Builder explicitly accepts the reviewed action, run the same selection with `--apply --plan-sha256 <approved-value>`. Changed data invalidates approval.
+
+The helper reads `DEV_ENVIRONMENT.json` and the selected `tools/dev-environment/catalog/*.json` copies generated by Bootstrap. It never guesses package IDs or uses `upgrade --all`. The states `MANAGER_CHECK` and `PINNED_RELEASE_UPGRADE` indicate upgrade eligibility, not a claim that a newer registry version exists. Preview the underlying manager's available version when feasible and expose it to the Builder. Homebrew/winget apply commands are intentionally package-specific; those managers may resolve a newer release at execution time.
+
+## Boundaries
+
+- Never automatically update project-pinned toolchain versions, application dependencies/lockfiles, generated package provenance, Project Forge-managed assets, Docker Desktop, SSH trust, or deployment targets.
+- Package-managed Project Forge updates remain owned by `/project-forge-update`. Modern Web Guidance remains on its approved exact version and independent from normal workstation tool updates.
+- Missing selected catalog entries, unsupported managers or unknown pinned-release integrity are manual-review gaps. An adopted repository without Bootstrap's selected tool catalog must use its existing, human-approved setup/update mechanisms instead of an invented Project Forge catalog.
+- A platform package-manager update may affect other programs and is not transactionally reversible. Report failures honestly and verify installed versions, doctor and relevant runtime checks afterward. Never deploy or restart production as a consequence.
+- Version checks and update previews never install packages or mutate repository state. Only explicit apply can update tools, and the existing setup approval and Project conventions remain authoritative.

package/assets/generated/core/core/skills/setup/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: setup
 description: "Guide and execute setup for this workstation/workspace instance, including verified local runtime convergence, optional remote-enabled capability, named deployment-environment onboarding, and disposable deployment-path proof."
-argument-hint: "[status|repair|local|remote|<environment>]"
+argument-hint: "[status|update|repair|local|remote|<environment>]"
 user-invocable: true
 disable-model-invocation: true
 ---
@@ -21,6 +21,7 @@ Supported focused forms include:
 ```text
 /setup status
 /setup repair
+/setup update
 /setup local
 /setup remote
 /setup <environment>
@@ -99,6 +100,10 @@ NEXT
 
 Do not silently repair state during `status`.
 
+## 2A. Periodic tool maintenance
+
+`/setup update` previews catalog-backed workstation upgrades and stops at one approval gate. Read `docs/process/WORKSTATION_MAINTENANCE.md` and use `python tools/project-forge-setup/maintenance.py status` for read-only tool inventory when present. Run `update` without apply to get the reviewed command list and SHA-256; only then run `update --apply --plan-sha256 <reviewed-hash>` with the same selected tool IDs after explicit approval. A changed plan must be reviewed again. `/setup status` makes no writes; regular `/setup` may record a 30-day check in ignored workstation-local state. An update never implicitly alters Project-pinned runtimes, product dependencies, Project Forge package baselines, Docker/SSH trust, production environments or third-party guidance versions. Missing tool catalogs or unsupported managers are `MANUAL REVIEW`, not guesses.
+
 ## 3. Run generated workstation setup
 
 Select the launcher for the actual workstation OS:

package/assets/generated/core/tools/setup_maintenance/maintenance.py

@@ -0,0 +1,172 @@
+#!/usr/bin/env python3
+"""Project Forge catalog-bound workstation updates. Status/preview never mutate."""
+from __future__ import annotations
+import argparse
+import datetime as dt
+import hashlib
+import json
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+TOOL_ID = re.compile(r"^[a-z0-9][a-z0-9-]*$")
+VERSION = re.compile(r"(?<!\d)(\d+\.\d+\.\d+)(?!\d)")
+PACKAGE_ID = re.compile(r"^[a-zA-Z0-9_.@/+:-]+$")
+
+
+def platform() -> str:
+    return "windows" if sys.platform == "win32" else "macos" if sys.platform == "darwin" else "linux" if sys.platform.startswith("linux") else "unsupported"
+
+
+def load(path: Path) -> dict:
+    value = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(value, dict):
+        raise ValueError(f"expected object in {path}")
+    return value
+
+
+def run(argv: list[str], timeout: int = 15) -> tuple[int, str]:
+    try:
+        result = subprocess.run(argv, capture_output=True, text=True, errors="replace", timeout=timeout, check=False)
+        return result.returncode, (result.stdout + "\n" + result.stderr).strip()[:1000]
+    except (OSError, subprocess.TimeoutExpired) as error:
+        return 127, type(error).__name__
+
+
+def semver(s: str | None) -> tuple[int, int, int] | None:
+    match = VERSION.search(s or "")
+    return tuple(map(int, match.group(1).split("."))) if match else None
+
+
+def inventory(root: Path) -> list[dict]:
+    env = load(root / "DEV_ENVIRONMENT.json")
+    if env.get("schemaVersion") != 1:
+        raise ValueError("unsupported DEV_ENVIRONMENT.json schema")
+    values: list[dict] = []
+    seen = set()
+    for item in env.get("tools", []):
+        name = item.get("id")
+        if not isinstance(name, str) or not TOOL_ID.fullmatch(name) or name in seen:
+            raise ValueError(f"unsafe or duplicate declared tool: {name}")
+        seen.add(name)
+        src = root / "tools/dev-environment/catalog" / (name + ".json")
+        if not src.is_file():
+            values.append({"id": name, "status": "CATALOG_MISSING", "update": "MANUAL_REVIEW"})
+            continue
+        data = load(src)
+        if data.get("id") != name:
+            raise ValueError(f"tool catalog identity mismatch: {name}")
+        executable = data.get("command")
+        verify = data.get("verifyArgs", ["--version"])
+        if not isinstance(executable, str) or not isinstance(verify, list) or not all(isinstance(v, str) for v in verify):
+            raise ValueError(f"invalid verification command for {name}")
+        path = shutil.which(executable)
+        rc, output = run([path, *verify]) if path else (127, "")
+        installed = semver(output) if rc == 0 else None
+        spec = data.get("install", {}).get(platform(), {})
+        spec = spec if isinstance(spec, dict) else {}
+        manager = spec.get("manager")
+        package = spec.get("package")
+        pin = item.get("version")
+        update = "MANUAL_REVIEW"
+        if pin:
+            update = "PROJECT_PINNED"
+        elif rc == 0 and manager in ("winget", "brew") and isinstance(package, str) and PACKAGE_ID.fullmatch(package):
+            update = "MANAGER_CHECK"
+        elif rc == 0 and manager == "project-forge-pinned-release":
+            expected = semver(spec.get("version"))
+            update = "APPROVED_PIN_CURRENT" if installed == expected and expected else (
+                "PINNED_RELEASE_UPGRADE" if installed and expected and installed < expected and name == "rtk" else "MANUAL_REVIEW"
+            )
+        values.append({"id": name, "status": "INSTALLED" if rc == 0 else "NOT_INSTALLED",
+                       "installedVersion": ".".join(map(str, installed)) if installed else None,
+                       "projectPin": pin, "update": update, "manager": manager, "package": package,
+                       "approvedVersion": spec.get("version") if manager == "project-forge-pinned-release" else None})
+    return values
+
+
+def make_plan(root: Path, selected: list[str]) -> dict:
+    items = inventory(root)
+    candidates = {x["id"]: x for x in items}
+    if not selected:
+        selected = [v["id"] for v in items if v["update"] in ("MANAGER_CHECK", "PINNED_RELEASE_UPGRADE")]
+    if len(selected) != len(set(selected)):
+        raise ValueError("duplicate requested tool")
+    ops = []
+    for name in sorted(selected):
+        if name not in candidates:
+            raise ValueError(f"undeclared tool {name}")
+        item = candidates[name]
+        if item["update"] == "MANAGER_CHECK":
+            manager = item["manager"]
+            if not shutil.which(manager):
+                raise ValueError(f"package manager {manager} is missing")
+            cmd = ["brew", "upgrade", item["package"]] if manager == "brew" else [
+                "winget", "upgrade", "--id", item["package"], "--exact",
+                "--accept-source-agreements", "--accept-package-agreements"
+            ]
+        elif item["update"] == "PINNED_RELEASE_UPGRADE":
+            launcher = root / "scripts/setup.sh"
+            if platform() != "linux" or not launcher.is_file() or "--update-rtk" not in launcher.read_text(encoding="utf-8"):
+                raise ValueError("approved pinned RTK update launcher unavailable; use an updated Bootstrap setup script")
+            cmd = ["bash", str(launcher), "--update-rtk"]
+        else:
+            raise ValueError(f"{name} cannot be automatically updated: {item['update']}")
+        ops.append({"id": name, "command": cmd, "fromVersion": item["installedVersion"],
+                    "approvedVersion": item["approvedVersion"]})
+    plan = {"schemaVersion": 1, "platform": platform(), "operations": ops}
+    digest = hashlib.sha256(json.dumps(plan, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
+    return {"plan": plan, "sha256": digest}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("action", choices=["status", "update"])
+    parser.add_argument("--root", type=Path, default=Path(__file__).resolve().parents[2])
+    parser.add_argument("--tool", action="append", default=[])
+    parser.add_argument("--apply", action="store_true")
+    parser.add_argument("--plan-sha256")
+    parser.add_argument("--record-check", action="store_true")
+    args = parser.parse_args()
+    if args.action == "status" and (args.tool or args.apply or args.plan_sha256):
+        parser.error("status is read-only and cannot accept update controls")
+    if args.action == "update" and args.record_check:
+        parser.error("--record-check applies only to status")
+    if args.apply != bool(args.plan_sha256):
+        parser.error("apply requires a reviewed --plan-sha256 and vice versa")
+    root = args.root.resolve()
+    try:
+        if args.action == "status":
+            result = {"platform": platform(), "tools": inventory(root)}
+            marker = root / ".project-forge/setup-maintenance/last-check.json"
+            if marker.is_file():
+                result["previousCheckUtc"] = load(marker).get("checkedAtUtc")
+            if args.record_check:
+                marker.parent.mkdir(parents=True, exist_ok=True)
+                marker.write_text(json.dumps({"checkedAtUtc": dt.datetime.now(dt.timezone.utc).isoformat()}) + "\n", encoding="utf-8")
+            print(json.dumps(result, indent=2))
+            return 0
+        result = make_plan(root, args.tool)
+        if not args.apply:
+            print(json.dumps({"mode": "PREVIEW", **result}, indent=2))
+            return 0
+        if args.plan_sha256 != result["sha256"]:
+            raise ValueError("update plan changed; re-preview and reapprove")
+        applied = []
+        for op in result["plan"]["operations"]:
+            code, _ = run(op["command"], timeout=900)
+            applied.append({"id": op["id"], "exitCode": code})
+            if code:
+                print(json.dumps({"mode": "PARTIAL_FAILURE", "applied": applied}, indent=2))
+                return 2
+        print(json.dumps({"mode": "APPLIED", "applied": applied, "after": inventory(root)}, indent=2))
+        return 0
+    except (OSError, ValueError, KeyError, json.JSONDecodeError) as exc:
+        print(json.dumps({"error": str(exc)}))
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mriekki/project-forge",
-  "version": "4.23.0",
+  "version": "4.24.0",
   "description": "Public consumer distribution and updater for Project Forge engineering assets.",
   "type": "module",
   "bin": {