State Machine

Punch State Machine Skill

When to use this skill

Load this skill whenever a task:

• Touches src/hooks/useAppState.ts or src/types.ts
• Adds or changes an entry kind, rate period, or financial calculation
• Modifies sync, ETag handling, or attachment logic
• Introduces a new domain entity or view-model interface
• Adds a new page or panel that requires state plumbing

The three-file authoring contract

Every feature that changes behaviour (not just style) requires three coordinated edits, in this order:

1. src/types.ts — add/extend the domain type and the view-model interface(s) for the affected component(s). Both sides of the state boundary must agree before either compiles cleanly.

2. src/hooks/useAppState.ts — implement the business logic and extend the useMemo view-model builder to populate the new fields. This is the only file that reads or mutates domain state; components never import from store.ts or access raw domain arrays.

3. The component (src/components/*.tsx) — consume the new view-model props. Accept data, render it, call callbacks. Done.

Run npx tsc -b after each step and fix errors before moving on. Skipping this causes misleading errors: the component compiles against the old interface while the hook produces the new shape, or vice versa.

Entry kinds and earnings

Three entry kinds exist. The Entry.kind discriminant controls both validation and financial calculation. Get this wrong and numbers break silently everywhere (Track, Export, Earnings, Sidebar).

Note: on a 'project' entry customerId is null — the customer is reached via project.customerId. On 'service' and 'customer' entries customerId is set directly on the entry.

The canonical formula lives in src/lib/earnings.ts → entryEarnValue().
Never duplicate it. Never compute earnings inline in a component or a new helper. All financial aggregations (Track summary, Export totals, Earnings page, Sidebar week earnings) call entryEarnValue() through aggregateBy() or summarize().

// src/lib/earnings.ts
export function entryEarnValue(
  entry: Entry,
  project: Project | undefined,
  service: Service | undefined,
  hoursPerDay: number,
): number {
  if (entry.kind === 'customer') return entry.amount ?? 0;
  if (entry.kind === 'service') return service ? rateForDate(service.rates, entry.date) : 0;
  if (!project) return 0;
  return ((entry.minutes / 60) / hoursPerDay) * rateForDate(project.rates, entry.date);
}

ETag concurrency — the immovable rule

store.saveState(data, etag) sends If-Match: <etag> on every PUT. A 412 response throws store.ConflictError. The hook handles this in pushStateNow() by fetching the remote copy and replacing local state — it does not retry the save.

Agents must never:

• Pass an empty string etag intentionally to bypass the check (empty etag is only valid on the very first write before the blob exists).
• Add a retry loop around saveState — that would silently clobber concurrent writes.
• Implement an "optimistic concurrency bypass for simplicity."

// src/hooks/useAppState.ts — pushStateNow
const result = await store.saveState(data, stateRef.current.stateEtag);
// ...
if (error instanceof store.ConflictError) {
  // fetch remote and replace — do NOT retry the save
}

Entry ID pre-assignment

openEntry() calls uid() to generate an ID before the entry is saved. This is intentional: it lets attachments be uploaded to <entryId>/<attachmentId> in Azure Blob Storage while the modal is still open, before the entry record is persisted.

Any refactor that moves ID assignment to save time will break the attachment upload flow.

// openEntry() — id is assigned here, not at save time
id: entry.id || uid(),

The stateRef pattern

The hook exposes stateRef = useRef(state) and keeps it current via a useEffect. Callbacks use stateRef.current to read state synchronously without adding it to their useCallback dependency arrays. This avoids stale closure bugs in async handlers (sync, attachment upload).

New callbacks should follow this same pattern:

const stateRef = useRef(state);
useEffect(() => { stateRef.current = state; });

const someCallback = useCallback(async () => {
  const current = stateRef.current;  // always fresh
  // ...
}, []); // no [state] dependency needed

Demo mode

Two parallel storage namespaces exist. store.getDemoModeFlag() reads a localStorage boolean. When true:

• All reads/writes go to the demo.v1 localStorage key.
• Remote sync is completely bypassed — pushStateNow and pullStateNow return early.

Any code path that reads or modifies data must check current.demoMode and route accordingly, exactly as pushStateNow() does:

const pushStateNow = useCallback(async () => {
  const current = stateRef.current;
  if (current.demoMode) return; // bypass all remote I/O
  // ...
}, []);

Delete cascades

Deleting a parent entity must cascade to all dependent records:

These cascades are implemented in deleteCustomerById, deleteProjectDraft, and deleteServiceDraft. Follow the same pattern for any new entity type.

Common mistakes