nextcloud-workflow-deck-automation/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this is

A Nextcloud app (`workflow_deck_automation`, namespace `WorkflowDeckAutomation`) targeting **Nextcloud Hub 26 Spring (server 34.x)**. It lets each user configure, from their personal settings, automation "workflows" that move overdue [Deck](https://github.com/nextcloud/deck) cards from one stack to another, with optional assigned-user/label filters and an email notification. A background `TimedJob` evaluates all enabled workflows every 5 minutes.

## Non-negotiable architectural constraint

**No HTTP/OCS calls against Deck, anywhere.** Every read (boards, stacks, cards, labels, assigned users) and the card move itself must go through Deck's own internal PHP classes (`OCA\Deck\Service\CardService`, `StackService`, `BoardService`, `OCA\Deck\Db\CardMapper`, …), resolved in-process via `\OCP\Server::get()`. This was an explicit, repeated product requirement from the user — do not "fix" it by switching to `IClientService`/`curl` against `/ocs/...`, even though that would be the more conventional cross-app integration approach.

All Deck access is funneled through `lib/Service/DeckIntegrationService.php` — it is the *only* class that references `OCA\Deck\*`. If you need new Deck data, extend that class rather than reaching into Deck internals from elsewhere. Every call in there is wrapped (`class_exists()` checks, `IAppManager::isEnabledForUser('deck', …)`, try/catch → `DeckUnavailableException`) because `OCA\Deck\*` is not a documented/stable public API — it has no `@since` markers and can change between Deck releases without notice.

## Per-user impersonation in the background job

Deck's ACL/permission checks read the *live* `IUserSession`, not a value frozen at construction. `RunWorkflowsJob` (a `TimedJob`) has no logged-in user by default and must evaluate workflows belonging to many different users within one PHP process. `lib/Service/WorkflowRunner.php` therefore groups workflows by owner and, per owner, temporarily impersonates them (`IUserSession::setUser()`, restored in a `finally`) before touching Deck. Don't remove this — without it, Deck's permission checks inside the cron run would be evaluated against no user (or the wrong user).

The filter-matching logic (`WorkflowRunner::cardMatchesFilters()`, `::isOverdue()`) is deliberately `static` and side-effect-free so it's unit-testable without a real Deck installation — see `tests/Unit/Service/WorkflowRunnerFilterTest.php`.

## Registration is declarative, not Bootstrap-based

Background jobs and classic personal settings are registered in `appinfo/info.xml` (`<background-jobs>`, `<settings><personal>/<personal-section>`), **not** via `IRegistrationContext` in `lib/AppInfo/Application.php` — that interface has no `registerBackgroundJob()`/`registerSettings()` methods on NC 34. `Application.php` is intentionally near-empty.

## Commands

**PHP and npm are not available in the local dev sandbox this repo is normally edited from.** Do not try to run `composer`, `php`, or `npm` locally to verify changes — they will fail with "command not found". Verification happens by pushing to `main` (or opening a PR) and checking the Gitea Actions run; the self-hosted runner tag is `gitea-runner-server03` (see `.gitea/workflows/*.yml`, all pinned to that `runs-on:` label).

Commands as they'd run in CI/on a machine that has the tools:

```bash
composer install
composer run lint       # php -l over lib/ and tests/
composer run cs:check   # nextcloud/coding-standard (php-cs-fixer); composer run cs:fix to auto-fix
composer run test:unit  # PHPUnit — pure logic only, no live Deck/Nextcloud instance needed

npm install              # no package-lock.json is committed (gitignored) — use install, not `npm ci`
npm run build             # production build
npm run watch              # rebuild on change during development
```

To run a single PHPUnit test: `vendor/bin/phpunit --filter testUserFilterIsOrAgainstAssignedUsers tests/Unit/Service/WorkflowRunnerFilterTest.php`.

There is no meaningful way to test the Deck integration itself outside a real Nextcloud+Deck instance (`php occ background-job:worker workflow_deck_automation`) — the unit tests intentionally stop at the pure filter logic.

### Release process

1. Bump `<version>` in `appinfo/info.xml` and `version` in `package.json` (keep them in sync).
2. Commit, push to `main`, confirm the lint/phpunit pipelines are green.
3. `git tag vX.Y.Z && git push origin vX.Y.Z` — this triggers `.gitea/workflows/build-release.yml`, which builds the frontend and runs `make appstore`, producing `build/artifacts/appstore/workflow_deck_automation.tar.gz` as a **workflow artifact**, downloadable from the Gitea Actions run for that tag.

**If the tagged build fails and no artifact was ever produced**, fix the issue on `main` and *move* the existing tag to the fixed commit instead of bumping to a new version number (`git tag -d vX.Y.Z && git tag -a vX.Y.Z -m "..." && git push origin :refs/tags/vX.Y.Z && git push origin vX.Y.Z`) — this is how `v0.1.0` was handled through several `build-release.yml` fixes before it first built successfully. Once a version has actually produced a published artifact, don't move its tag anymore; bump normally instead.

**`actions/upload-artifact` must stay on `@v3`, not `@v4`+.** This self-hosted Gitea instance identifies as GHES to the official `actions/*` JS actions, which refuse to run `@actions/artifact` v2.0.0+ (used internally by `upload-artifact@v4` and later) against GHES: `GHESNotSupportedError`. `actions/checkout` and `actions/setup-node` don't have this problem and can be kept on their latest majors — only the artifact upload/download actions are affected, because they're the ones that talk to a version-specific backend API rather than just running local commands.

### Rolling build for manual server deploys

`.gitea/workflows/build-main.yml` builds the same appstore package on every push to `main` (no tag needed) and publishes it as the asset on a rolling pre-release tagged `latest-main` — the release+tag are deleted and recreated each run via the Gitea REST API (`curl`, not an `actions/*` artifact action, so the GHES artifact-API restriction above doesn't apply here), so the download URL for `workflow_deck_automation.tar.gz` on that release always serves the newest `main` build. This exists specifically so a build can be grabbed and copied onto the server (`nextcloud.gnilebein.de`) without cutting a version tag first — it produced `v0.1.0`-shaped raw-repo confusion once already when the app directory was populated by copying the git working tree instead of a built package; this gives a one-click alternative to that mistake.

This requires a **repo secret named `RELEASE_TOKEN`**, a Gitea Personal Access Token with repo write access (create it under the repo owner's Gitea user settings → Applications, then add it under the repo's Settings → Actions → Secrets). Without that secret, the `curl` calls to the Gitea release API in the job will fail with 401s — the workflow doesn't fall back to anything else.

## Data flow / architecture map

- **UI**: `src/PersonalSettings.vue` (Vue 3, mounted from `templates/settings/personal.php` into the section registered by `lib/Settings/PersonalSection.php` + `lib/Settings/Personal.php`) talks to `lib/Controller/WorkflowController.php` (an `OCSController`) via `src/api.js`, hitting OCS routes declared in `appinfo/routes.php` (`/ocs/v2.php/apps/workflow_deck_automation/api/v1/...`).
- **Storage**: `lib/Db/Workflow.php` (Entity) / `lib/Db/WorkflowMapper.php` (QBMapper) over the `wfda_workflows` table, created in `lib/Migration/Version1000Date20260813120000.php`. Filter fields (`filter_user_ids`, `filter_label_ids`) are stored as JSON-encoded arrays in text columns, not join tables.
- **Automation**: `lib/BackgroundJob/RunWorkflowsJob.php` (5 min `TimedJob`) → `lib/Service/WorkflowRunner.php` (per-user impersonation + filtering, both filters OR-within-themselves and AND-between-each-other) → `lib/Service/DeckIntegrationService.php` (all actual Deck class calls) and `lib/Service/NotificationMailer.php` (email via `OCP\Mail\IMailer` to the workflow owner's account address, never a manually-entered address).
- Both the controller's board/stack/label/participant lookups (for populating the settings UI dropdowns) and the runner's card reads/moves go through the same `DeckIntegrationService` — there is no separate read path.

## Composer/npm lockfiles are intentionally not committed

`.gitignore` excludes `composer.lock` and `package-lock.json`. This means CI must use `composer install`/`npm install`, not `composer install --no-dev` assumptions tied to a lock file or `npm ci` (which hard-requires a lock file and will fail otherwise — this has already broken `build-release.yml` once). If you add a lockfile-dependent step, either commit the lockfile deliberately or keep using the non-`ci`/non-locked install form.

## Frontend build gotchas already hit (don't reintroduce)

None of these were discoverable locally — there's no npm here (see "Local-only notes" below), so all three were only caught by an actual Gitea Actions run against `build-release.yml`:

- **`vite` version must satisfy `@nextcloud/vite-config`'s peer requirement.** `package.json` pins `@nextcloud/vite-config` to `^2.2.0`, which currently resolves to `2.5.4` and peer-requires `vite@^7.3.6`. If you bump `@nextcloud/vite-config`, check its `peerDependencies.vite` and bump our `vite` devDependency to match, or `npm install` fails with `ERESOLVE`.
- **`package.json` needs `"type": "module"`.** `vite.config.js` uses `import`/`export` syntax and `@nextcloud/vite-config` is ESM-only; without `"type": "module"`, Node treats `.js` as CommonJS and `vite build` fails trying to `require()` an ESM-only package.
- **A `tsconfig.json` must exist at the repo root, even though this project has no TypeScript source.** `@nextcloud/vite-config`'s `index.js` barrel statically re-exports `createLibConfig` from `libConfig.js`, which imports `vite-plugin-dts` at module scope — that import chain runs just from importing `createAppConfig`, regardless of whether `createLibConfig` is ever called. The minimal `tsconfig.json` in this repo exists to give that a config to resolve, not because we write TypeScript. On its own this did **not** fix the crash below — see the next bullet.
- **`typescript` must be an explicit devDependency.** `vite-plugin-dts` (pulled in transitively by the bullet above, version `^4.5.4` as of `@nextcloud/vite-config@2.5.4`) peer-depends on `typescript: "*"` but doesn't install it itself. Without a `typescript` devDependency in our own `package.json`, nothing provides that package, and `vite-plugin-dts`'s `@volar/typescript` integration crashes at module-load time — before `vite.config.js`'s own code or `tsconfig.json` are ever consulted — with `Cannot read properties of undefined (reading 'useCaseSensitiveFileNames')` (`proxyCreateProgram`). This is the actual fix; `tsconfig.json` existing is necessary but not sufficient. Keep `typescript` reasonably close to the version `@nextcloud/vite-config` itself develops against (currently `^5.9.3`) if you bump either.
- **`createAppConfig` prefixes every entry name with the app id**, so the entry `personal-settings` is emitted as `js/workflow_deck_automation-personal-settings.mjs` and `css/workflow_deck_automation-personal-settings.css`. `Util::addScript()`/`addStyle()` take that *full on-disk basename* (minus extension), not the bare entry name — `lib/Settings/Personal.php` therefore passes `Application::APP_ID . '-personal-settings'`. Getting this wrong produces a **silently blank settings page**: the template's empty mount `<div>` renders fine, and the only symptom is `Could not find resource workflow_deck_automation/js/….js to load` (`jsresourceloader`) plus a matching `Could not find resource file "/apps/workflow_deck_automation/css/….css"` in `nextcloud.log`. If you rename the entry in `vite.config.js`, rename it in `Personal.php` too.
- **The bulk of the CSS lives in a hashed `*.chunk.css`**, loaded at runtime by the `.mjs` bundle (`cssCodeSplit: true`). The `css/workflow_deck_automation-personal-settings.css` that `addStyle()` points at is the ~100-byte stub produced by `createEmptyCSSEntryPoints: true`. A near-empty entry CSS file is expected — don't "fix" it by turning off code splitting.

## Local-only notes

`CLAUDE.local.md` (gitignored) carries session-specific environment notes (e.g. "no PHP/npm available locally"). Check it at the start of work in this repo — it's not duplicated here since it can change independently of the committed guidance.