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 (not an attached Gitea Release asset — that would need an additional API step with a repo token, not currently wired up).

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.

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. vite-plugin-dts/@volar/typescript crash (Cannot read properties of undefined (reading 'useCaseSensitiveFileNames')) while loading vite.config.js if there's no tsconfig for it to resolve. The minimal tsconfig.json in this repo exists solely to satisfy that, not because we write TypeScript.

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.