[cueweb/docs] Add Services (Facility Service Defaults) page (CueCommander parity)

[ramonfigueiredo]

Related Issues

Main issue:

• [cueweb] Finalize CueWeb with Full CueGUI Functionality and Professional UI #2016

Issues related to this PR:

• [cueweb] Show, Subscription, Service, Limits: Services list page #2303
• [cueweb] Add Services (Facility Service Defaults) page (CueCommander parity) #2430

Summarize your change.

[cueweb] Add Services (Facility Service Defaults) page (CueCommander parity)

Wire the existing CueCommander "Services" menu item to a new /services page mirroring CueGUI's "Facility Service Defaults" tab (ServiceDialog): a left pane listing facility default services and a right-pane edit form. (In CueGUI the Services tab is the Facility Service Defaults tab, so the page lives at /services where the sidebar item already points.)

• Form fields match CueGUI: Name, Threadable, Min/Max Threads (100 = 1 thread), Min Memory MB, Min Gpu Memory MB, Timeout, Timeout LLU, OOM Increase MB, predefined Tags (two-column order) plus a Custom Tags toggle. Memory converts MB<->KB (x1024); threads stored as cores*100.
• Save validates (name length/charset, non-negative integers, min <= max threads when max > 0, OOM > 0, tag charset) then shows a facility-wide confirmation before Create (new) or Update (existing). New / Del in the left pane (Del confirms first).
• Proxy routes under app/api/service/: getdefaultservices, create, update, delete. Service type + getDefaultServices in get_utils; create/update/deleteService in action_utils.
• Surface load/save/delete failures instead of masking them: getDefaultServices throws on a non-array response (mirroring getHosts) so a backend outage reaches the page's error state rather than rendering "No services defined"; numeric fields require non-negative integers (fractional input rejected up front since they back integer proto fields); the Save/Delete confirm handlers throw when create/update/deleteService return false, so ConfirmDialog stays open for retry instead of dismissing as if the action succeeded.

[cueweb/docs] Document Facility Service Defaults (Services) page

• User guide: Add user-facing Facility Service Defaults section with screenshots
• Reference: Add technical entry (routes, RPCs, MB/KB and units, validation)
• Developer guide: Add CueCommander-parity architecture section
• Other guides: Add overview entry
• Add CueCommander Facility Services screenshots (light + dark variants)

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds complete facility-wide default service management to cueweb, including data types, four API route handlers (create, read, update, delete), client-side service utilities, an editable form component, and a page to list and manage services.

Changes

Facility Service Defaults Management

Layer / File(s)	Summary
Service type definition and data fetching cueweb/app/utils/get_utils.ts	Adds Service type representing facility-wide default service templates with thread limits, memory constraints, timeouts, GPU limits, and OOM memory increase settings. Introduces getDefaultServices() to fetch and validate services from the API.
Service API route handlers cueweb/app/api/service/getdefaultservices/route.ts, cueweb/app/api/service/create/route.ts, cueweb/app/api/service/update/route.ts, cueweb/app/api/service/delete/route.ts	Four new Next.js POST routes validate HTTP method, parse JSON, check request payloads, forward to RPC endpoints, and return standardized JSON responses with upstream status codes.
Service action helpers cueweb/app/utils/action_utils.ts	createService, updateService, and deleteService call action endpoints and return Promise<boolean> success status for UI-driven refresh logic without triggering toast behavior.
Service edit form component cueweb/components/ui/service-defaults-form.tsx	Form manages service fields (name, thread limits, memory, timeout, OOM increase) and tag selection (predefined checkbox grid or custom comma/space/pipe-separated text). Validates field constraints, converts memory from MB to KB, and calls createService or updateService on confirmed save.
Services management page cueweb/app/services/page.tsx	Page loads services via getDefaultServices(), displays a left sidebar list (supporting select/new/delete actions) and a keyed right form panel. Supports deleting services with confirmation and reloads the list after save or delete.
Documentation docs/_docs/developer-guide/cueweb-development.md, docs/_docs/other-guides/cueweb.md, docs/_docs/reference/cueweb.md, docs/_docs/user-guides/cueweb-user-guide.md	Comprehensive documentation describing the /services page, field specifications, validation rules, save/delete flows, UI layout, and API integration across developer guide, feature reference, and user guide.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Suggested reviewers

• DiegoTavares
• lithorus

🐰 Four routes forward requests so right,
Form fields validated with might,
Services sorted by name with care,
Defaults set everywhere! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 43.48% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately reflects the primary changes: adding documentation and implementation of a Services (Facility Service Defaults) page feature with CueCommander parity, though it emphasizes the documentation aspect while implementation spans API routes, components, utilities, and documentation.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@cueweb/app/utils/get_utils.ts`:
- Around line 369-372: getDefaultServices currently converts non-array responses
(including null from accessGetApi on failures) into an empty list, hiding load
failures; change getDefaultServices (the exported async function) to check
whether the response is an array and throw an Error when it is not (mirroring
getHosts behavior) instead of returning [], so callers can handle request
failures distinctly from an empty service list.

In `@cueweb/components/ui/service-defaults-form.tsx`:
- Around line 159-179: The confirm flows call boolean-returning helpers
(createService/updateService and deleteService) but return normally on false,
which lets ConfirmDialog close; change these handlers so a failure propagates as
a thrown error instead of returning silently: in service-defaults-form.tsx's
handleConfirm check the result of createService/updateService (symbols:
createService, updateService, handleConfirm, onSaved) and if ok is false throw
an Error (or reject the promise) with a descriptive message so ConfirmDialog's
onConfirm sees an exception and keeps the modal open; do the same in
app/services/page.tsx for the delete flow (symbol: deleteService and the delete
handler) — throw when deleteService returns false and only call success
toast/onDeleted when the call returned true.
- Around line 117-137: The numeric validation currently allows fractional
numbers (e.g., 1.5) because it only checks Number.isFinite; update the
validation used for numericFields (the array with ["Min Threads", minThreads],
["Max Threads", maxThreads], ["Min Memory MB", minMemoryMb], ["Min Gpu Memory
MB", minGpuMemoryMb], ["Timeout", timeout], ["Timeout LLU", timeoutLlu], ["OOM
Increase MB", oomIncreaseMb]) to reject non-integer values where the field is
integer-backed by adding a Number.isInteger(x) requirement (and keep the
existing non-negative check), and also ensure the OOM check uses integer > 0
(Number.isInteger and x > 0); finally apply the same integer-enforcing change to
the other similar validation block referenced elsewhere (the other numeric
validation around timeout/KB fields) so fractional inputs are rejected
consistently for minCores/maxCores/timeout/timeoutLlu and KB-backed memory
fields.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 4f78bf74-5205-4391-898d-657a5e9d09c9

📥 Commits

Reviewing files that changed from the base of the PR and between f8e6a0b and 3dfd04b.

📒 Files selected for processing (8)

• cueweb/app/api/service/create/route.ts
• cueweb/app/api/service/delete/route.ts
• cueweb/app/api/service/getdefaultservices/route.ts
• cueweb/app/api/service/update/route.ts
• cueweb/app/services/page.tsx
• cueweb/app/utils/action_utils.ts
• cueweb/app/utils/get_utils.ts
• cueweb/components/ui/service-defaults-form.tsx

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

cueweb/app/services/page.tsx (1)

41-45: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Preserve a distinct load-failure state instead of falling back to empty data.

At Line 44, the initial fetch failure is still coerced to [], so the UI can render "No services defined." (Lines 112-114) during backend outages. That reintroduces the same failure-masking behavior this PR is trying to eliminate.

Suggested minimal fix

 export default function FacilityServiceDefaultsPage() {
   const [services, setServices] = React.useState<Service[] | null>(null);
+  const [loadError, setLoadError] = React.useState<string | null>(null);
@@
   const load = React.useCallback(async (isCancelled?: () => boolean) => {
     try {
       const data = await getDefaultServices();
       if (isCancelled?.()) return;
+      setLoadError(null);
       setServices(data);
     } catch (err) {
       if (isCancelled?.()) return;
       handleError(err, "Could not load services");
+      setLoadError("Could not load services");
       setServices((prev) => prev ?? []);
     }
   }, []);
@@
-            ) : sorted.length === 0 ? (
+            ) : loadError ? (
+              <p className="p-3 text-sm text-destructive">{loadError}</p>
+            ) : sorted.length === 0 ? (
               <p className="p-3 text-sm text-muted-foreground">No services defined.</p>
             ) : (

Also applies to: 112-114

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@cueweb/app/services/page.tsx` around lines 41 - 45, In the catch block of the
service loading function, the code is masking the load failure by defaulting to
an empty array with the fallback `prev ?? []` in the setServices call. Instead
of coercing the services state to an empty array when an error occurs, preserve
a distinct failure state that allows the UI to differentiate between a load
failure and genuinely empty services. Either keep the previous value unchanged
or explicitly set an error/loading state so that the UI rendering logic can
display appropriate error messaging instead of showing "No services defined"
during backend outages.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@cueweb/app/services/page.tsx`:
- Around line 41-45: In the catch block of the service loading function, the
code is masking the load failure by defaulting to an empty array with the
fallback `prev ?? []` in the setServices call. Instead of coercing the services
state to an empty array when an error occurs, preserve a distinct failure state
that allows the UI to differentiate between a load failure and genuinely empty
services. Either keep the previous value unchanged or explicitly set an
error/loading state so that the UI rendering logic can display appropriate error
messaging instead of showing "No services defined" during backend outages.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 43c6e3b7-6323-4c98-915c-8846687f791a

📥 Commits

Reviewing files that changed from the base of the PR and between 3dfd04b and 8245516.

📒 Files selected for processing (3)

• cueweb/app/services/page.tsx
• cueweb/app/utils/get_utils.ts
• cueweb/components/ui/service-defaults-form.tsx

🚧 Files skipped from review as they are similar to previous changes (1)

• cueweb/components/ui/service-defaults-form.tsx

[ramonfigueiredo]

@DiegoTavares / @lithorus

Ready for review!