mirror of
https://github.com/johannesjo/super-productivity.git
synced 2026-07-17 16:37:43 +00:00
No description
electron-apphacktoberfesthacktoberfest2020jiralinuxmacosproductivitytask-managertime-trackertimetrackingto-do-listtodo
aa94abd890
* feat(sync): add one observable busy definition for sync work
Task 3 needs a single busy/idle definition so callers stop polling three
signals independently and disagreeing about what "busy" means. Two of the
three were only readable point-in-time: SyncCycleGuard.isActive is a plain
field and isEncryptionOperationInProgress is a getter, so a consumer could
ask "busy now?" but never be told when that stopped being true. No
behaviour change; nothing consumes SyncBusyService yet.
SyncCycleGuard now backs its state with a subject and exposes isActive$,
emitting on BOTH transitions. Claim-visibility is the load-bearing part:
the side channels (immediate upload, WS download) claim a cycle without
touching any other sync signal, so a release-only edge would report those
cycles as idle for their entire duration — exactly the coverage the guard
is in the union for. A spec pins that case.
released$ remains as sugar for the release edge, derived via pairwise() so
an idle guard cannot fire a phantom release at subscribe time. Both it and
isActive$ are re-check HINTS, not lock hand-offs: the guard's no-deadlock
property rests on callers never waiting on it, so the docblock states the
emission carries no claim and subscribers must still win tryBegin(). A
spec asserts two subscribers racing one edge get [true, false].
SyncBusyService merges the guard's activity with the wrapper's sync and
encryption signals and recomputes the whole union on every edge, so no
interleaving can desynchronise it. That ordering is load-bearing: sync()'s
finally clears isSyncInProgress$ while the guard is still held, and only
the guard's release resolves the union to idle.
Provider SYNCING is deliberately excluded — it is presentation state set
only by sync(), strictly narrower than the guard, and would be a fourth
lock disagreeing with the other three.
* feat(sync): add a config epoch for revalidating deferred sync work
Task 3 defers background sync work while other work is in flight, so a
request can outlive the target it was made against: a queued sync must not
run after the user switches provider, moves the folder, or signs out.
Add the monotonic in-tab counter that deferred work will capture and
revalidate before I/O. No behaviour change; nothing reads it yet.
Bumped on all four authoritative transitions: any provider-config write,
a target move asserted by a bypass ingress, an active provider switch, and
a credential revoke.
The last two are the reason this is a counter on the manager rather than a
projection of providerConfigChanged$: NEITHER emits on that stream. A
provider switch deliberately does not (switches are handled via
getLastSyncedProviderId -> forceFromSeq0) and clearAuthCredentials never
did, so an epoch derived from that stream alone would silently miss both —
including provider switch, which Task 3's acceptance criteria require to
invalidate a queued request. Specs pin both, asserting the switch case
bumps while providerConfigChanged$ stays silent.
Machine-only OAuth token refresh for an unchanged account still does NOT
bump: it goes through the credential store and moves no target, so
invalidating healthy queued work there would be a regression.
Follows the existing _activeProviderSetupId shape (in-tab, not persisted,
not cross-tab). Documented as a staleness heuristic, never a security
input — callers compare epochs, never configuration.
* feat(sync): add the background full-sync scheduler
Background triggers (interval, resume, visibility, settle) call sync()
behind an exhaustMap, which DROPS any trigger arriving while a sync runs —
the work it asked for is lost until something else happens to trigger
again. Add the single owner of generic pending background work: a burst
collapses into at most one pending rerun, which drains once the current
work settles. Dormant; nothing routes through it yet (that is the next
tranche, where the behaviour actually changes).
request() is fire-and-forget with no result and no failure taxonomy.
sync() resolves with the truthy string 'HANDLED_ERROR' on handled failure,
so its result cannot be truth-tested; the scheduler reads it not at all —
settled success and settled failure release identical state, and
source-specific retry stays with the source.
Deferral is the whole point, and a deferral is exactly the window in which
the user switches provider, moves the folder, or signs out. So a request
captures {configEpoch, providerId} and revalidates before EVERY leading or
trailing run, not only at request() time. A stale request is DROPPED, not
retargeted: the trigger that wanted target A has no opinion about target B,
and a live trigger will ask again.
It never calls sync() while anything else is active — that call would only
bounce off the cycle guard and return HANDLED_ERROR, silently burning the
request — and never before the awaited initial path opens the gate, so it
cannot start a shadow initial sync.
TWO wake-ups are required, and this is the subtle part. sync()'s finally
releases the busy signals BEFORE SyncEffects flips the gate in its .then().
A scheduler waking only on the busy edge therefore finds the gate still
shut, returns, and strands the request forever — the session's first
background sync would silently never run. Verified by removing the gate
wake-up: exactly that scenario fails.
Also exposes SyncTriggerService.initialSyncGateOpen$, the observable mirror
of isInitialSyncDoneSync() (setInitialSyncDone is the sole writer of both).
It deliberately excludes the MAX_WAIT_FOR_INITIAL_SYNC failsafe that the
existing public observables merge in: that timer keeps the UI from hanging
on a sync that never lands, which is right for rendering and wrong here —
it would open the gate on a schedule rather than on the initial sync having
actually completed.
* feat(sync): route background sync triggers through the scheduler
Split the dynamic background branch out of triggerSync$ into
scheduleBackgroundSync$, which calls scheduler.request() instead of
sync(). Interval, resume, visibility, idle/activity, online-regained and
the trailing settle timer now go through the scheduler; initial,
after-enable and before-close stay directly awaited, as do the ~14
explicit user/manual sync callers.
This is the behaviour change the previous three commits were seams for: a
background trigger arriving while a sync is in flight used to be DROPPED by
the shared exhaustMap, losing the work it asked for until something else
happened to trigger again. It is now deferred and drained.
exhaustMap's cross-source protection is not lost but upgraded. It stays on
triggerSync$, where it now guards only initial vs after-enable. Background
exclusion becomes the scheduler's busy check plus SyncCycleGuard.tryBegin()
— which was always the real authority; exhaustMap was a coarse
approximation that could only drop, never defer.
Kept deliberately unchanged so the split does not quietly alter behaviour
as a side effect: the 2s throttle (the scheduler collapses bursts anyway,
but this preserves the pre-existing rate ceiling), the E2E auto-sync kill
switch, and the offline skip.
Incidental correctness win: the ungated setInitialSyncDone(true) in the
catch used to mean ANY failing background sync — hours into a session —
flipped the initial gate. Only initial/after-enable reach that catch now,
so the gate is opened solely by the paths that own it.
Also drops SyncCycleGuard.released$, which had zero consumers: it was built
for Task 4 and is speculative until something needs it. isActive$ is what
the busy union actually consumes, and its edge tests move with it.
* test(sync): make SyncEffects testable and cover the trigger routing
The routing split was the whole behaviour change of this branch and had
NO test coverage: sync.effects.spec.ts is 61 lines testing constants, so
the split broke no test because no test was watching. Two things blocked
covering it, both fixed here.
1. createEffect stamps a non-configurable marker onto whatever object the
factory returns, and syncBeforeQuit$ returned the shared EMPTY singleton
when not on Electron. The first construction branded EMPTY process-wide,
so every later one died with "Cannot redefine property
__@ngrx/effects_create__" — the class could not be built twice in one
suite. This, not the Dropbox SDK the spec header blames, is why it never
had behavioural tests. defer(() => EMPTY) hands over a fresh instance per
construction; subscribed behaviour is unchanged.
2. isOnline$ is a module-level shareReplay(1) whose startWith(navigator.onLine)
captures its initial value at import time, and headless Chrome reports
navigator.onLine === false. Anything gated on it is permanently offline
under test with no seam to override, so an online-gated assertion would
pass while proving nothing. Add an IS_ONLINE$ token whose default factory
returns that same observable — no runtime change, just somewhere for a
spec to provide a fake.
The 8 new tests pin the acceptance criterion: a background trigger reaches
the scheduler and does NOT call sync(); the settle branch routes even though
it emits null rather than a trigger name (so routing cannot depend on the
emitted value); offline and the E2E kill switch suppress it; and the initial
sync still calls sync() directly, bypassing the scheduler, with only that
path flipping the initial gate.
* fix(sync): stop the scheduler running syncs back-to-back
Two real bugs, both found after the branch looked finished, neither by
reasoning: the first by wiring the real guard and busy service to the real
scheduler, the second by adversarial review. The full unit suite was green
throughout — it was never evidence for either.
1. Re-entrancy. The scheduler drained SYNCHRONOUSLY on the busy edge, and
that edge fires from SyncCycleGuard.end(), which sync() calls inside its
own finally. So the next sync started part-way through the previous
one's teardown, and the wrapper's SYNCING safeguard — which runs two
lines later — then saw the NEW sync's status and reset it to
UNKNOWN_OR_CHANGED. Provider status is still a live exclusion gate for
the immediate-upload side channel, so that is not cosmetic. Wake-ups now
drain on a microtask, letting the finishing cycle unwind first.
2. A permanent back-to-back sync loop. exhaustMap was the ONLY thing
bounding the sync RATE; throttleTime(2000) bounds the TRIGGER rate and
was never the binding constraint, so the previous commit's claim that
keeping it "preserves the pre-existing rate ceiling" was simply wrong.
I_INTERVAL_TIMER is self-sustaining and independent of sync activity and
is not clamped by SYNC_MIN_INTERVAL, so whenever a sync outlasts
syncInterval — a 90s WebDAV sync on a 60s interval is ordinary, since
getFileRev is a full GET rather than a cheap ETag — every tick lands
mid-sync and, once triggers are deferred instead of dropped, drains the
instant the previous run settles. Idle time goes from ~25% to zero,
permanently.
The wasted I/O is the lesser harm. sync() opens the hydration window and
closes it in its finally, so with no gap between runs isInSyncWindow is
effectively always true and skipDuringSyncWindow() would suppress
TODAY_TAG repair and day-change effects INDEFINITELY.
Add a duty-cycle floor: record the settle time and re-arm a timer rather
than run when less than SYNC_MIN_INTERVAL has passed. It lives in the
scheduler because only the scheduler can see run duration. The
defer-don't-drop win is unaffected — the trailing run still happens, just
not immediately.
Both fixes are pinned by specs that fail without them.
Also corrects initialSyncGateOpen$'s docblock, which claimed to exclude the
MAX_WAIT_FOR_INITIAL_SYNC failsafe. It does not: the 8s failsafe timers call
setInitialSyncDone(true) from a tap, writing the very subject the gate reads.
I had verified setInitialSyncDone was the sole writer of the subject and
never checked who calls it. The gate therefore means "the gate is open", not
"the initial sync landed" — harm is low since both paths call the same
sync(), but Task 4+ must not build a stronger invariant on it.
* fix(sync): make the duty-cycle floor monotonic and cross-source
Three more real bugs, all found by a second adversarial review of the
already-"finished" branch. None were found by reasoning about the code.
1. A backward wall-clock jump stalled ALL background sync. _lastSettleAt
used Date.now(), so an NTP correction after Android Doze / Electron
resume / a VM restore made the elapsed calculation negative and armed a
timer of `floor + jump` — a one-hour correction armed a one-hour timer,
and _armSpacingTimer early-returns while one exists, so nothing shortened
it. Background sync is now the only automatic sync path, so that is a
total stall. Clamping the delay would NOT have fixed it: each retry
recomputes the same negative elapsed and re-arms, stalling just as hard
in a loop. Use performance.now(), which cannot go backwards.
2. The floor only spaced the scheduler against ITSELF. _lastSettleAt was
written solely inside our own run, so initial, manual, after-enable, quit
and forceUpload syncs settled without touching it. Consequences: the
session's first background sync ran back-to-back with the initial sync
with zero gap — exactly the "blur right after initial sync" case the old
shared throttleTime guarded, which the effect split dissolved — and a
trigger deferred during the before-close sync started fresh I/O at the
instant the window closed, turning a rare crash-mid-sync into a routine
one. Stamp on any busy->idle transition, so the floor means "5s idle
after ANY sync work".
3. Fixing (2) naively introduced a third bug, caught by our own spec:
isBusy$ replays `false` to every subscriber, so filtering on the value
stamped _lastSettleAt at construction and delayed the session's first
background sync by the whole floor. pairwise() makes it a real
transition.
The specs drive performance.now() explicitly — jasmine's mockDate fakes
Date, not the monotonic clock, so the floor would otherwise read real time
and the coverage would be silently meaningless.
Known and deliberate: the floor narrows the skipDuringSyncWindow idle
window versus master (~25% -> ~5% in the slow-provider case), since
SYNC_MIN_INTERVAL is 5s. skipDuringSyncWindow is a drop-filter, so the idle
FRACTION is what matters to TODAY_TAG repair and day-change effects. Still
strictly better than the unbounded loop it replaces, but it is a tradeoff,
not a win, and is worth revisiting with a provider-aware floor.
|
||
|---|---|---|
| .agents/skills/commit-messages | ||
| .air | ||
| .codex | ||
| .devcontainer | ||
| .github | ||
| .husky | ||
| .signpath/policies/super-productivity | ||
| .vscode | ||
| android | ||
| build | ||
| docs | ||
| e2e | ||
| electron | ||
| eslint-local-rules | ||
| fastlane | ||
| ios | ||
| nginx | ||
| packages | ||
| scripts | ||
| snap/hooks | ||
| src | ||
| tools | ||
| .browserslistrc | ||
| .dockerignore | ||
| .editorconfig | ||
| .env.example | ||
| .gitattributes | ||
| .gitignore | ||
| .gitmodules | ||
| .gitpod.yml | ||
| .npmrc | ||
| .nvmrc | ||
| .prettierignore | ||
| .prettierrc.json | ||
| .stylelintrc.mjs | ||
| AGENTS.md | ||
| angular.json | ||
| ARCHITECTURE-DECISIONS.md | ||
| capacitor.config.ts | ||
| CLAUDE.md | ||
| CONTRIBUTING.md | ||
| docker-compose.e2e.fast.yaml | ||
| docker-compose.e2e.yaml | ||
| docker-compose.supersync.yaml | ||
| docker-compose.yaml | ||
| docker-entrypoint.sh | ||
| Dockerfile | ||
| Dockerfile.e2e.dev | ||
| Dockerfile.e2e.dev.fast | ||
| electron-builder.yaml | ||
| eslint.config.js | ||
| funding.json | ||
| Gemfile | ||
| Gemfile.lock | ||
| LICENSE | ||
| ngsw-config.json | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
| SECURITY.md | ||
| tsconfig.base.json | ||
| tsconfig.json | ||
| webdav.yaml | ||
An advanced todo list app with timeboxing & time tracking capabilities that supports importing tasks from your calendar, Jira, GitHub and others
🌐 Open Web App or 💻 Download
💻 Downloads & Install
For all current downloads, package links, and platform-specific notes:
check the wiki
✔️ Features
- Keep organized and focused! Plan and categorize your tasks using sub-tasks, projects and tags and color code them as needed.
- Use timeboxing and track your time. Create time sheets and work summaries in a breeze to easily export them to your company's time tracking system.
- Helps you to establish healthy & productive habits:
- A break reminder reminds you when it's time to step away.
- The anti-procrastination feature helps you gain perspective when you really need to.
- Need some extra focus? A Pomodoro timer is also always at hand.
- Collect personal metrics to see, which of your work routines need adjustments.
- Integrate with Jira, Trello, GitHub, GitLab, Gitea, OpenProject, Linear, ClickUp and Azure DevOps. Auto import tasks assigned to you, plan the details locally, automatically create work logs, and get notified immediately, when something changes.
- Basic CalDAV integration.
- Back up and synchronize your data across multiple devices with Dropbox and WebDAV support
- Attach context information to tasks and projects. Create notes, attach files or create project-level bookmarks for links, files, and even commands.
- Super Productivity respects your privacy and does NOT collect any data and there are no user accounts or registration. You decide where you store your data!
- It's free and open source and always will be.
And much more!
Note
The web version has some limitations: See the Web App vs Desktop comparison for more details.
📖 Documentation and Guides
Getting Started
- Getting started guide (article)
- Video walkthrough (YouTube)
- Eat the frog prioritizing scheme
Starting Point in Wiki:
First steps •
Reference •
How-To
Productivity Tips:
Keyboard Shortcuts •
Short Syntax
Need Help?
Visit the discussions page
See the bottom of the README for more information on the documentation.
Advanced Topics
Here are some other topics covered in the official wiki:
Development:
Run dev server •
Package the app •
Build for Android •
Run with Docker
Data Management:
User Data •
Issue Providers •
Sync Providers
Customization:
Plugins •
Themes
APIs:
Sync Server •
Plugins •
REST
Community
The development of Super Productivity is driven by a wonderful community of users and contributors. Thank you all so much for your support!
👀 Check out our awesome curated list of community-created resources about Super Productivity
♥️ Contributing
If you want to get involved, please check out the CONTRIBUTING.md
There are several ways to help.
-
Spread the word: More users mean more people testing and contributing to the app which in turn means better stability and possibly more and better features. You can vote for Super Productivity on Slant, Product Hunt, Softpedia or on AlternativeTo, you can tweet about it, share it on LinkedIn, reddit or any of your favorite social media platforms. Every little bit helps!
-
Provide a Pull Request: Here is a list of the most popular community requests and here some info on how to run the development build (wiki). Please make sure that you're following the commit message format and to also include the issue number in your commit message, if you're fixing a particular issue (e.g.:
feat: add nice feature #31). -
Answer questions: You know the answer to another user's problem? Share your knowledge!
-
Provide your opinion: Some community suggestions are controversial. Your input might be helpful and if it is just an up- or down-vote.
-
Provide a more refined UI spec for existing feature requests
-
Make a feature or improvement request: Something can be done better? Something essential missing? Let us know!
-
Translations, Icons, etc.: You don't have to be a programmer to help; learn how to contribute translations!
-
Create custom plugins or custom themes
Special Thanks to our Sponsors!!!
Recently support for Super Productivity has been growing! A big thank you to all our sponsors!
(If you are, intend to or have been a sponsor and want to be shown here, please let me know!)
Code Signing
Windows binaries are signed. Free code signing is provided by SignPath.io, certificate by SignPath Foundation.
Documentation: Manual versus Automated
There are two wikis: the official one hosted in by GitHub and the autonomously generated variant using DeepWiki.com. The manually curated version is a more stable and approachable resource designed to help you understand the app from a more human-focused perspective whereas DeepWiki is optimized for explaining the code itself with little regard for context beyond that.
Official Wiki
It is preferable to maintain local documentation rather than rely on an external service. It also preferable that the documentation is updated in tandem with the code changes as demonstrated in this commit.
Changes to files within ./docs/wiki are linted in CI before being automatically
sync'd to the repository's official Wiki hosted by GitHub.
Migrating to Docusaurus is a long-term goal once the content and structure of the wiki has matured and the remaining "legacy docs" have either been reworked or removed. There are some automations in development to help reduce the difference between the published docs and the state of the code while retaining a human-in-the-loop.
DeepWiki.com
If you have very specific questions about how the code works or why a bug might be producing
a particular message it might be useful to
. It can help "cite your sources" when discussing functionality and code that you don't fully
understand as part of feature requests or bug reports.
This automated reference does come with some significant drawbacks:
- Intent: Describes what code does, not why decisions or tradeoffs were made.
- Staleness: Will *always* lag behind the code.
- Code-Focused: Does not provide guides or conceptual explanations.
- Cost: Potential future cost and higher resource usage than static docs.