# 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` (``, `/`), **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 `` 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.