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 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:

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.

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.