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 cards from one stack to another, with optional assigned-user/label filters and an email notification. A background Job evaluates all enabled workflows on every cron pass.

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

RunWorkflowsJob 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 impersonates each owner in turn. Impersonation here is two steps, and IUserSession::setUser() is the one that barely matters:

1. IUserSession::setUser() — for the handful of Nextcloud services that do read the live session, plus IRootFolder::getUserFolder() for Deck helpers that expect an initialised user FS.
2. DeckIntegrationService::beginUserContext() — pins Deck itself to that user. This is the load-bearing half.

Both are undone in a finally (WorkflowRunner::clearImpersonation()).

Deck does not read the session for permissions. At all. PermissionService — the class behind every permission check, including the ones inside CardService::reorder() — takes the current user as private ?string $userId, and so do CardService, BoardService and ActivityManager. That string comes from the app container's userId service, which is ISession::get('user_id') registered via registerService(), i.e. shared: Pimple resolves it once and caches it for the whole process, and ServerContainer caches Deck's app container just as long. Whoever was active when Deck's container first built PermissionService is who every later check is evaluated against.

In cron that is never the user being impersonated: null if any Deck-owned background job ran earlier in the same cron.php pass, otherwise the first workflow owner touched. null fails every check, so Deck answers NoPermissionException for perfectly intact boards. This produced a real bug — see the next section. beginUserContext() therefore swaps that private field directly (there is no API), records the old value, and endUserContext() puts it back. PermissionService is mandatory: if it can't be pinned, beginUserContext() throws and the runner skips that user entirely rather than acting under someone else's permissions. The other three are best-effort (they only affect activity attribution and unread counts).

Consequence for getUserBoards(): listBoardsForCurrentUser() stays request-only anyway — Deck may already have cached board lists behind that field, and the job has no use for a board list; it asks findStackIds() about one known board id. Before using any other OCA\Deck\* service from the runner, check whether it carries a frozen $userId — the failure mode is silent and user-crossing, not an error.

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.

Workflows are auto-disabled when their Deck targets vanish

WorkflowRunner::findBrokenTarget() checks board and stacks before every run and, if something is gone, switches the workflow off (enabled = false) and sends a one-off mail. Two invariants hold this together and must survive refactors:

• Only positive knowledge disables. DeckIntegrationService::findStackIds() returns null only for "board row gone" (DoesNotExistException, Deck's NotFoundException), "board in the trash" (deleted_at > 0), or "this uid has no read permission" — and throws for everything else. The runner skips the workflow on a throw. If you make that method degrade to []/null on generic errors, a Deck outage will disable every workflow on the instance and mail every user about it.
• findStackIds() must never ask a Deck service to figure out who is asking. It takes the uid as an argument and is assembled from pieces that cannot answer for the wrong user: BoardMapper/StackMapper are plain QBMappers with no user state, and PermissionService::getPermissions($boardId, $userId) is handed the uid explicitly instead of falling back to the frozen field. Do not "simplify" it back to a single StackService::findAll($boardId) — that is precisely what broke. StackService::findAll() runs checkPermission() with no uid, which falls through to the construction-time $userId; with that frozen to null in cron, Deck threw NoPermissionException for an untouched board, the old code read that as "board is gone", and users got "your workflow was deactivated" mails for boards sitting right in front of them. This layer stays correct even if beginUserContext() silently degrades.
• NoPermissionException is not evidence of anything. It is deliberately not in isMissing(). Deck raises it for every failed check regardless of cause.
• The mail ignores the notifyEmail flag — that flag is about moved cards; this is a notice that the user's configuration stopped working. It stays a one-off simply because a disabled workflow is not picked up by findAllEnabled() again.

Archived boards deliberately do not trigger this (they stay readable, so findStackIds() succeeds), even though they're filtered out of the settings dropdowns.

The job has no interval — one run per cron pass

RunWorkflowsJob extends OCP\BackgroundJob\Job, not TimedJob, so it runs every time cron picks it up. There is no interval and no knob: the cadence is the instance's cron cadence. Don't reintroduce one — an earlier version read workflow_deck_automation.interval from config.php (default 300, 60s floor), and that config key is gone as of v0.2.0. TimedJob with setInterval(0) would behave nearly identically but keeps an interval concept nothing uses.

Time sensitivity is what actually decides whether the job runs at all. OC\Core\Service\CronService::runCli() reads maintenance_window_start (default 100, i.e. unset) and, whenever the current UTC hour is outside [start, start+4], calls jobList->getNext($onlyTimeSensitive = true) — time-insensitive jobs are then skipped for the other 20 hours of the day. This app shipped TIME_INSENSITIVE once: on an instance with a maintenance window configured (Nextcloud's admin overview nags admins into setting one) the job simply never ran, showing last_run = 1970-01-01 in occ background-job:list indefinitely. Note this gate only exists in runCli(), so it doesn't apply to ajax/webcron mode, and passing job classes explicitly (occ background-job:worker '<class>') bypasses it — which is exactly why manual testing can look fine while cron does nothing.

Being a plain Job makes that unreachable rather than merely declared. getNext() filters on the time_sensitive column of oc_jobs; JobList::add() doesn't write the column at all (it takes the TIME_SENSITIVE default), and the only place that ever lowers it is a one-way ratchet in JobList::setLastRun():

if ($job instanceof TimedJob && !$job->isTimeSensitive()) {
    $query->set('time_sensitive', $query->createNamedParameter(IJob::TIME_INSENSITIVE));
}

There is no else, and a non-TimedJob never enters it. Note setTimeSensitivity()/isTimeSensitive() live on TimedJob, not on Job — so there is nothing to declare here, and nothing that can go wrong.

Rows written by an older version keep their stamp. Once stamped TIME_INSENSITIVE it stays that way: re-registering an existing job (app update, app:enable) takes add()'s update branch, which leaves the column alone. An instance that ran the pre-v0.1.0-fix build still needs its row fixed once:

UPDATE oc_jobs SET time_sensitive = 0
 WHERE class = 'OCA\\WorkflowDeckAutomation\\BackgroundJob\\RunWorkflowsJob';

or, without DB access, occ background-job:delete <id> followed by occ app:disable workflow_deck_automation && occ app:enable workflow_deck_automation to get a freshly inserted row. Fresh installs are unaffected.

To debug this job on a server: occ background-job:list --class '<class>' for its id and last run, then occ background-job:execute <id> --force-execute to run it right now without waiting for cron. occ background-job:worker takes job classes, not an app id.

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:

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 'OCA\WorkflowDeckAutomation\BackgroundJob\RunWorkflowsJob' — the argument is a job class, not an app id) — 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 run of .gitea/workflows/build-main.yml is green.
3. git tag vX.Y.Z && git push origin vX.Y.Z — this triggers the tag branch of the same workflow, which re-runs the checks, builds the frontend, runs make appstore, and attaches workflow_deck_automation.tar.gz as the asset on a normal (non-pre-) release 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 fixes before it first built successfully. The job deletes any pre-existing release for the tag before creating the new one, so a moved tag republishes cleanly instead of failing on a duplicate asset name. Once a version has actually produced a published artifact, don't move its tag anymore; bump normally instead.

No actions/upload-artifact anywhere — and don't reintroduce it. 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, which pinned us to @v3 for a while. Publishing through the Gitea release REST API with curl sidesteps that version-specific backend API entirely, so the build workflow uses that instead. actions/checkout and actions/setup-node were never affected — only the artifact upload/download actions are, because they're the ones talking to a versioned backend rather than just running local commands — and can stay on their latest majors.

One workflow for everything

.gitea/workflows/build-main.yml is the only workflow: it carries the checks (php-lint across 8.2/8.3/8.4, xml-lint, unit-tests) and the package job that builds and publishes. They used to be four separate workflow files, which meant they all triggered independently on the same push and a latest-main release was published even when PHPUnit was red. needs: only works between jobs of the same workflow (and Gitea's workflow_run can depend on one workflow at a time), so gating the release on the checks required merging them into this file. Don't split them back out.

Consequences of that shape, all intentional:

• package builds and publishes in one job. Handing the tarball to a separate publish job would need actions/upload-artifact (unusable here, see above) or actions/cache — a second Gitea backend API in the critical path for no gain.
• The workflow also runs on pull_request, where the Publish release step is skipped via if: gitea.event_name == 'push' and the job degrades into a frontend-build check. That matters: npm run build used to run only on main, so no PR ever exercised it.
• Tags now get linted and tested too. Previously the check workflows triggered only on main pushes and PRs, so a v* tag published completely unverified.

It runs on pushes to main and on v* tags, and the publish step branches on gitea.ref:

• main → rolling pre-release tagged latest-main; both the release and the tag are deleted and recreated each run, so the download URL for workflow_deck_automation.tar.gz always serves the newest main build.
• v* → normal release on the tag that was just pushed. Only a stale release is deleted here — never the tag, since deleting it would destroy the ref that triggered the run. That's what the RECREATE_TAG flag guards.

The latest-main half exists 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.

Note that make appstore is pure mkdir/tar/rm — no composer, no php. The package job therefore needs Node only; a setup-php step there would be dead weight (the deleted release workflow had one). PHP is set up in the check jobs, which is a different job and a different container.

No manually created token is needed. The publish step authenticates with secrets.GITEA_TOKEN, the token Gitea injects into every Actions job automatically (Gitea 1.27.1 here). The job declares permissions: contents: write, which Gitea maps to Code: write (needed to delete the latest-main tag) plus Releases: write (creating the release and uploading the asset).

This replaced an earlier hand-made RELEASE_TOKEN repo secret. If the publish step ever starts returning 403s, check the repo/org default token permission mode: permissions: requests are clamped by MaxTokenPermissions, so a repository switched from Permissive (the backwards-compatible default) to Restricted silently downgrades releases to read-only and no permissions: block can raise it back. That's a repo setting, not a workflow bug — don't "fix" it by reintroducing a PAT before checking.

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 (plain Job, one run per cron pass) → 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 the build workflow 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 the build workflow:

• 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.

@nextcloud/vue 9 component API (Vue 3) — the v8 idioms silently do nothing

This app is on @nextcloud/vue ^9 / Vue 3. The v8 (Vue 2) prop spellings that most Nextcloud app code online still uses either fail silently or, worse, land as stray DOM attributes instead of erroring:

• No .sync. Vue 3 removed it. NcTextField and NcCheckboxRadioSwitch both bind through modelValue/update:modelValue, so it's v-model="x" — :value.sync="x" / :checked.sync="x" leave the bound state permanently at its initial value. That's how form.title stayed '' and every save died on "Bitte einen Titel angeben."
• NcSelect's label prop is the option display key, not a caption (it's vue-select's). Passing label="Board" makes it read option.Board on every option and render undefined for all of them. The visible caption prop is input-label.
• NcButton: variant is the style, type is the native button type, and native-type no longer exists (v8's type="primary" + native-type="submit" → v9's variant="primary" + type="submit"). A leftover type="primary" renders <button type="primary">, which HTML treats as the invalid-value default submit — so a cancel button silently submits the form.
• NcSelect's reduce is not declared on NcSelect itself; it reaches vue-select through attribute fallthrough (NcSelect's root element is the VueSelect component and it doesn't set inheritAttrs: false). It works, but it's fallthrough, not a documented prop.
• NcNoteCard's prop is still type (success|info|warning|error) — not everything was renamed to variant.

Deck entities are "relational": getters don't return the uid string

Deck's RelationalEntity swaps resolved relations for an OCA\Deck\Db\RelationalObject once an entity is enriched. So on an enriched board/card, $acl->getParticipant(), $board->getOwner() and a card assignment's participant return a RelationalObject (wrapping OCA\Deck\Db\User/Group/Circle), not a uid — the uid is its getPrimaryKey(). Probing for getUID() on the returned object finds nothing and yields null, which is how the settings UI's user dropdown came up empty and why the runner's assigned-user filter could never match. DeckIntegrationService::unwrapUid() handles both shapes (bare string and RelationalObject); route any new participant/owner field through it.

Two more Deck facts that bit us in the same pass: a board's ACL does not contain its owner (a private board has an empty ACL, so participants must be seeded with $board->getOwner()), and ACL entries can be groups (type === 1) whose members have to be expanded via IGroupManager.

BoardService::getUserBoards() defaults to $includeArchived = true, and that flag also gates the deleted_at = 0 condition — with the default you get archived and trashed boards back. We call getUserBoards(null, false) (with a fallback to the no-arg form if Deck ever changes the signature) and still dedupe by id afterwards, because it merges own/group/circle boards and can return the same board twice. Stacks need no such handling: StackMapper::findAll() filters deleted_at = 0 unconditionally and stacks have no archived state.

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.