@patimweb/pi-zep 1.0.0 → 1.0.2

package/README.md

@@ -107,17 +107,17 @@ Other message texts observed:
 ```
 zep_setup  name=work userid=patrick.weppelmann password=… mandant=zepneoimpulse
 zep_status probe=true
-zep_projects projekt=Julabo
+zep_projects projekt=Contoso
 zep_week
-zep_book   datum=2026-09-17 von=08:00 bis=12:00 projekt=413 vorgang=90-01 taetigkeit=co bemerkung="3447 Ladeanzeige nach Pick"
+zep_book   datum=2026-09-17 von=08:00 bis=12:00 projekt=413 vorgang=90-01 taetigkeit=co bemerkung="4711 Beispiel-Ticket"
 zep_book   datum=2026-09-17 entries=[{von:"08:00",bis:"12:00",bemerkung:"…"},{von:"13:00",bis:"17:00",bemerkung:"…"}]
 ```
 
 `projekt` and `vorgang` accept either an id (`413`, `3284`) or part of the label
-(`Julabo`, `90-01`). A full example, `dryRun` first:
+(`Contoso`, `90-01`). A full example, `dryRun` first:
 
 ```
-zep_book projekt=Julabo vorgang=90-01 datum=2026-09-17 von=08:00 bis=12:00 dryRun=true
+zep_book projekt=Contoso vorgang=90-01 datum=2026-09-17 von=08:00 bis=12:00 dryRun=true
 ```
 
 ## Important behaviour

package/index.ts

@@ -5,6 +5,7 @@
  * PHP endpoint instead of the paid ZEP REST API.
  *
  * Tools:
+ *   - zep_doctor:   diagnose config, session and reachability without spending a login attempt
  *   - zep_setup:    store userid/password/Mandant
  *   - zep_login:    log in (password, or adopt a browser tab session)
  *   - zep_status:   show config, log in, prove the session works
@@ -26,6 +27,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 import { loadConfig } from "./src/config.ts";
+import { ZepDoctorTool } from "./src/tools/zep-doctor.ts";
 import { ZepSetupTool } from "./src/tools/zep-setup.ts";
 import { ZepLoginTool } from "./src/tools/zep-login.ts";
 import { ZepStatusTool } from "./src/tools/zep-status.ts";
@@ -38,6 +40,7 @@ import { ZepDeleteTool } from "./src/tools/zep-delete.ts";
 export default function (pi: ExtensionAPI) {
   loadConfig();
 
+  pi.registerTool(ZepDoctorTool);
   pi.registerTool(ZepSetupTool);
   pi.registerTool(ZepLoginTool);
   pi.registerTool(ZepStatusTool);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patimweb/pi-zep",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "ZEP time-tracking for pi coding agent — book project times (Projektzeiten) on zep-online.de over plain HTTP, without the paid ZEP API",
   "keywords": [
     "pi-package",

package/src/clients/zep-client.ts

@@ -51,6 +51,14 @@ export class ZepError extends Error {
   }
 }
 
+export interface ZepPing {
+  readonly status: number;
+  /** The login form rendered, i.e. the server is up and reachable. */
+  readonly loginPageOk: boolean;
+  /** login.php bounced us into the app, i.e. we are already authenticated. */
+  readonly redirectedToApp: boolean;
+}
+
 export interface ZepClientOptions {
   /** Called whenever a fresh session was established, so it can be cached. */
   readonly onSession?: (session: ZepSession) => void;
@@ -117,6 +125,17 @@ export class ZepClient {
    * where `noch` is the remaining attempt count before a lockout.
    */
   async login(): Promise<LoginResult> {
+    // Refuse before touching the network. Without this guard an absent
+    // password becomes the literal string "undefined" in the form body, which
+    // ZEP counts as a real failed attempt - and the account is locked after 5.
+    if (!this.account.password) {
+      throw new ZepError(
+        `No password stored for ZEP user "${this.account.userid}". Add a "password" to the ` +
+          "profile in ~/.pi/zep-config.json (or run zep_setup). Refusing to send an empty " +
+          "password, because ZEP locks the account after 5 failed attempts.",
+      );
+    }
+
     this.cookies.clear();
     this.clientsessid = null;
     this.requesttoken = null;
@@ -131,9 +150,16 @@ export class ZepClient {
       login: "Anmelden",
     }).toString();
 
+    // Match the browser form POST exactly: same-origin form submissions carry
+    // Referer and Origin, and ZEP's login handler is the pickiest endpoint.
+    const loginUrl = `${this.root}/view/login.php`;
     const res = await this.raw("/view/login.php", {
       method: "POST",
-      headers: { "content-type": "application/x-www-form-urlencoded" },
+      headers: {
+        "content-type": "application/x-www-form-urlencoded",
+        referer: loginUrl,
+        origin: this.root,
+      },
       body,
     });
 
@@ -190,6 +216,22 @@ export class ZepClient {
     return this.lastLogin;
   }
 
+  /**
+   * Reachability probe used by zep_doctor. Read-only: it fetches the login
+   * page and reports what came back. Never call it on a client that holds a
+   * live session - priming a new PHPSESSID would replace the working cookie.
+   */
+  async ping(): Promise<ZepPing> {
+    const res = await this.raw("/view/login.php", { method: "GET" });
+    const body = await res.text();
+    const location = res.headers.get("location") ?? "";
+    return {
+      status: res.status,
+      loginPageOk: /id="login-form"/.test(body),
+      redirectedToApp: /index\.php/.test(location) && !/action=login/.test(location),
+    };
+  }
+
   /** Log in only when there is no usable session yet. */
   async ensureLogin(): Promise<void> {
     if (this.hasSession) return;
@@ -229,9 +271,9 @@ export class ZepClient {
     const headers = new Headers(rest.headers ?? {});
     headers.set("user-agent", USER_AGENT);
     headers.set("accept-language", "de-DE,de;q=0.9,en;q=0.8");
-    if (rest.method && rest.method !== "GET" && !headers.has("x-requested-with")) {
-      headers.set("x-requested-with", "XMLHttpRequest");
-    }
+    // Deliberately no automatic X-Requested-With here: the browser only sends
+    // it on ajax.php calls, never on the login form POST. Sending it on the
+    // login made the request diverge from the real form.
     if (this.cookies.size > 0) {
       headers.set(
         "cookie",
@@ -449,8 +491,8 @@ export class ZepClient {
       letzterReiseOrt: "D-Office",
       ortProjektrelevant: "1",
       reise: "0",
-      startort: "Gottmadingen Im Brühl 1",
-      zielort: "Ismaningen Neoimpulse",
+      startort: "Beispielweg 1",
+      zielort: "Beispielort",
       fahrzeug: "Firmenwagen",
       km: "285",
       mitfahrer: "1",

package/src/clients/zep-parse.ts

@@ -297,13 +297,51 @@ function resolveDayDate(dayLabel: string, kwDate: string): string | null {
   return monday.toISOString().slice(0, 10);
 }
 
+/**
+ * Label of a day row: `Do 17.09.`.
+ *
+ * The label cell also carries the meals/breaks icons, whose text content is
+ * literally `restaurant` / `local_cafe`; taking the plain text of the cell
+ * would render as `Do 17.09. restaurant`. Prefer the dedicated weekday and
+ * day/month divs and only fall back to text surgery.
+ */
+function dayRowLabel(cellHtml: string, joined: string): string {
+  const weekday = /class="modimidofrsaso"[^>]*>\s*([A-Za-z]{2})\s*</.exec(cellHtml)?.[1];
+  const dayMonth = /class="tag_monat"[^>]*>\s*([0-9]{2}\.[0-9]{2}\.)\s*</.exec(cellHtml)?.[1];
+  if (weekday && dayMonth) return `${weekday} ${dayMonth}`;
+
+  return joined
+    .split(/\s{2,}/)[0]!
+    .replace(/\s*(restaurant|local_cafe)\b.*$/i, "")
+    .trim();
+}
+
+/**
+ * Place of work of a booking row, or null when ZEP does not render it.
+ *
+ * The Ort cell is the row's last column (`von` + 9) and, unlike the other
+ * metadata columns, it carries no `data-columnid` of its own. ZEP only emits
+ * it when there is something to report, so an absent cell means the booking
+ * sits on the default place of work (`NULL`). A trailing `*` marks a
+ * deviation from that default and is not part of the value.
+ */
+function bookingOrt(flat: ReadonlyArray<string>, from: number): string | null {
+  return (flat[from + 9] ?? "").replace(/[\s*]+$/, "").trim() || null;
+}
+
 /**
  * Parse the week table rendered into `#ProjektzeitTableDiv`.
  *
- * Row shapes observed on the live system:
- *   day row      `["Do 17.09. restaurant", ...]`   (icons = meals/breaks)
- *   booking row  `["editdelete", von, bis, Dauer, "", Projekt, Vorgang, Taet, "payments", Bemerkung]`
- *   sum row      `["Summe", "8,00", "payments 8,00"]`
+ * Row shapes observed on the live system (2026-09-17, ZEP v7.13.88):
+ *
+ *   day, no bookings   `["Do 17.09. restaurant", ""]`
+ *   day, with bookings `["Do 17.09. restaurant", "", "editdelete", von, bis, Dauer, "", Projekt, Vorgang, Taet, fakturierbar, Bemerkung, Ort]`
+ *   further bookings   `["editdelete", von, bis, Dauer, "", Projekt, Vorgang, Taet, "payments", Bemerkung, Ort]`
+ *   sum row            `["Summe", "4,00", ...]`
+ *
+ * The day's FIRST booking is rendered inside the day row itself (the label
+ * cell then has `rowspan=N`), which is why the booking columns must be read
+ * relative to the first `HH:MM` cell rather than at a fixed offset.
  */
 export function parseWeek(tableHtml: string, kwDate: string): ZepWeek {
   const days: ZepWeekDay[] = [];
@@ -341,19 +379,22 @@ export function parseWeek(tableHtml: string, kwDate: string): ZepWeek {
     // --- day header -------------------------------------------------------
     const joined = flat.join(" ").trim();
     const dayMatch = DAY_RE.exec(joined);
-    if (dayMatch && cells.length <= 3) {
+    // A day row is identified by its `id="day_YYYY-MM-DD"` cell; the label
+    // text is only used as a fallback so that a markup change in the label
+    // cannot silently re-attach a day's bookings to the previous day.
+    const dayId =
+      /id="day_(\d{4}-\d{2}-\d{2})"/.exec(row.html) ??
+      /openMahlzeiten\s*\(\s*this\s*,\s*'(\d{4}-\d{2}-\d{2})'/.exec(row.html);
+    if (dayId || (dayMatch && cells.length <= 3)) {
       flush();
-      const iso =
-        /id="day_(\d{4}-\d{2}-\d{2})"/.exec(row.html) ??
-        /openMahlzeiten\s*\(\s*this\s*,\s*'(\d{4}-\d{2}-\d{2})'/.exec(row.html);
-      const label = joined.split(/\s{2,}/)[0] ?? joined;
+      const label = dayRowLabel(cells[0] ?? "", joined) || joined;
       current = {
         label,
-        date: iso?.[1] ?? resolveDayDate(label, kwDate),
+        date: dayId?.[1] ?? resolveDayDate(label, kwDate),
         bookings: [],
         classes: row.classes,
       };
-      continue;
+      // deliberately no `continue`: this row may carry the day's first booking
     }
 
     if (!current) continue;
@@ -368,22 +409,26 @@ export function parseWeek(tableHtml: string, kwDate: string): ZepWeek {
     }
 
     // --- booking row ------------------------------------------------------
-    const from = /^\d{2}:\d{2}$/.test(flat[1] ?? "");
-    if (!from) continue;
+    // Anchor on the `von` cell: cell 1 in a standalone booking row, cell 3
+    // behind the label in a day row that carries its first booking.
+    const from = flat.findIndex((c, index) => index > 0 && /^\d{2}:\d{2}$/.test(c));
+    if (from === -1) continue;
 
-    const objectId = /objectId=(\d+)/.exec(row.html)?.[1] ?? null;
+    const objectId =
+      /objectId=?(\d+)/.exec(row.html)?.[1] ?? null;
     current.bookings.push({
       objectId,
       dayLabel: current.label,
       date: current.date,
-      from: flat[1] ?? "",
-      to: flat[2] ?? "",
-      duration: flat[3] ?? "",
-      project: flat[5] ?? "",
-      vorgang: flat[6] ?? "",
-      taetigkeit: flat[7] ?? "",
-      billable: /payments/i.test(flat[8] ?? "") || /payments/i.test(row.html),
-      comment: flat[9] ?? "",
+      from: flat[from] ?? "",
+      to: flat[from + 1] ?? "",
+      duration: flat[from + 2] ?? "",
+      project: flat[from + 4] ?? "",
+      vorgang: flat[from + 5] ?? "",
+      taetigkeit: flat[from + 6] ?? "",
+      billable: /payments/i.test(flat[from + 7] ?? "") || /payments/i.test(row.html),
+      comment: flat[from + 8] ?? "",
+      ort: bookingOrt(flat, from),
     });
   }
 

package/src/config.ts

@@ -10,14 +10,20 @@
  * on every call.
  */
 
-import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
 import type { ZepAccount, ZepConfigFile, ZepSession } from "./types.ts";
 
-const CONFIG_PATH = join(homedir(), ".pi", "zep-config.json");
-const SESSION_PATH = join(homedir(), ".pi", "zep-session.json");
+/** Resolved on every call, so honouring $HOME works and tests can relocate it. */
+function configFile(): string {
+  return join(homedir(), ".pi", "zep-config.json");
+}
+
+function sessionFile(): string {
+  return join(homedir(), ".pi", "zep-session.json");
+}
 
 export const DEFAULT_BASE_URL = "https://zep-online.de";
 export const DEFAULT_MANDANT = "zepneoimpulse";
@@ -28,6 +34,19 @@ let config: { profiles: Record<string, ZepAccount>; activeProfile: string | null
 };
 let sessions: Record<string, ZepSession> = {};
 
+// mtimes of the last read, so refreshConfig() can tell whether the files
+// changed on disk. -1 means "never read".
+let configMtime = -1;
+let sessionMtime = -1;
+
+function mtimeOf(path: string): number {
+  try {
+    return statSync(path).mtimeMs;
+  } catch {
+    return -1;
+  }
+}
+
 function writePrivate(path: string, data: unknown): void {
   const dir = dirname(path);
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -49,12 +68,31 @@ function readJson<T>(path: string, fallback: T): T {
 }
 
 export function loadConfig(): void {
-  const loaded = readJson<ZepConfigFile>(CONFIG_PATH, { profiles: {}, activeProfile: null });
+  const loaded = readJson<ZepConfigFile>(configFile(), { profiles: {}, activeProfile: null });
   config = {
     profiles: loaded?.profiles ?? {},
     activeProfile: loaded?.activeProfile ?? null,
   };
-  sessions = readJson<Record<string, ZepSession>>(SESSION_PATH, {});
+  sessions = readJson<Record<string, ZepSession>>(sessionFile(), {});
+  configMtime = mtimeOf(configFile());
+  sessionMtime = mtimeOf(sessionFile());
+}
+
+/**
+ * Re-read the files when they changed on disk.
+ *
+ * pi loads an extension once per session, so without this a config file that
+ * the user wrote by hand (the documented alternative to zep_setup) is only
+ * picked up after a restart - the tools would keep reporting
+ * "No ZEP profile configured" while a perfectly valid file sits on disk.
+ *
+ * Cheap: two stat() calls in the common case where nothing changed.
+ */
+export function refreshConfig(): void {
+  const nextConfig = mtimeOf(configFile());
+  const nextSession = mtimeOf(sessionFile());
+  if (nextConfig === configMtime && nextSession === sessionMtime) return;
+  loadConfig();
 }
 
 export function getConfig(): ZepConfigFile {
@@ -102,14 +140,14 @@ export function getProfile(name?: string): ZepAccount {
 export function saveProfile(name: string, account: ZepAccount): void {
   config.profiles[name] = account;
   if (!config.activeProfile) config.activeProfile = name;
-  writePrivate(CONFIG_PATH, config);
+  writePrivate(configFile(), config);
 }
 
 export function updateProfile(name: string, patch: Partial<ZepAccount>): void {
   const existing = config.profiles[name];
   if (!existing) return;
   config.profiles[name] = { ...existing, ...patch };
-  writePrivate(CONFIG_PATH, config);
+  writePrivate(configFile(), config);
 }
 
 export function useProfile(name: string): void {
@@ -117,7 +155,7 @@ export function useProfile(name: string): void {
     throw new Error(`ZEP profile "${name}" not found.`);
   }
   config.activeProfile = name;
-  writePrivate(CONFIG_PATH, config);
+  writePrivate(configFile(), config);
 }
 
 export function deleteProfile(name: string): void {
@@ -126,16 +164,16 @@ export function deleteProfile(name: string): void {
   if (config.activeProfile === name) {
     config.activeProfile = listProfiles()[0] ?? null;
   }
-  writePrivate(CONFIG_PATH, config);
-  writePrivate(SESSION_PATH, sessions);
+  writePrivate(configFile(), config);
+  writePrivate(sessionFile(), sessions);
 }
 
 export function configPath(): string {
-  return CONFIG_PATH;
+  return configFile();
 }
 
 export function sessionPath(): string {
-  return SESSION_PATH;
+  return sessionFile();
 }
 
 // ------------------------------------------------------------------- sessions
@@ -146,10 +184,10 @@ export function getSession(profileName: string): ZepSession | undefined {
 
 export function saveSession(profileName: string, session: ZepSession): void {
   sessions[profileName] = session;
-  writePrivate(SESSION_PATH, sessions);
+  writePrivate(sessionFile(), sessions);
 }
 
 export function clearSession(profileName: string): void {
   delete sessions[profileName];
-  writePrivate(SESSION_PATH, sessions);
+  writePrivate(sessionFile(), sessions);
 }

package/src/formatting/formatters.ts

@@ -65,7 +65,8 @@ export function formatWeek(week: ZepWeek): string {
       lines.push(
         `    #${booking.objectId ?? "?"}  ${booking.from}-${booking.to} (${booking.duration})  ` +
           `${booking.project} / ${booking.vorgang} / ${booking.taetigkeit}` +
-          `${booking.billable ? " [billable]" : ""}`,
+          `${booking.billable ? " [billable]" : ""}` +
+          `${booking.ort ? `  @ ${booking.ort}` : ""}`,
       );
       if (booking.comment) lines.push(`        ${booking.comment}`);
     }

package/src/session.ts

@@ -6,7 +6,14 @@
  * after 5 failed password attempts.
  */
 
-import { clearSession, getActiveProfileName, getProfile, getSession, saveSession } from "./config.ts";
+import {
+  clearSession,
+  getActiveProfileName,
+  getProfile,
+  getSession,
+  refreshConfig,
+  saveSession,
+} from "./config.ts";
 import { ZepClient, ZepError } from "./clients/zep-client.ts";
 
 export interface ClientHandle {
@@ -17,6 +24,7 @@ export interface ClientHandle {
 }
 
 export async function createClient(profileName?: string): Promise<ClientHandle> {
+  refreshConfig();
   const name = profileName ?? getActiveProfileName();
   if (!name) {
     throw new ZepError("No ZEP profile configured. Call zep_setup first.");
@@ -62,6 +70,7 @@ export async function createClient(profileName?: string): Promise<ClientHandle>
  * Used by zep_login force=true.
  */
 export async function loginProfile(profileName: string): Promise<ZepClient> {
+  refreshConfig();
   const account = getProfile(profileName);
   clearSession(profileName);
 

package/src/tools/zep-book.ts

@@ -64,13 +64,13 @@ export const ZepBookTool = {
     bemerkung: Type.Optional(
       Type.String({
         description:
-          "Comment. Convention: include the ticket/story numbers (e.g. '3447 Ladeanzeige nach Pick, 3455 Fach-HU-Nummer').",
+          "Comment. Convention: include the ticket/story numbers (e.g. '4711 Ladeanzeige, 4712 Fach-HU-Nummer').",
       }),
     ),
     projekt: Type.Optional(
       Type.String({
         description:
-          "Project id (e.g. '413' for Julabo) or part of its label (e.g. 'Julabo'). Falls back to the project ZEP has selected for this user.",
+          "Project id (e.g. '413' for Contoso) or part of its label (e.g. 'Contoso'). Falls back to the project ZEP has selected for this user.",
       }),
     ),
     vorgang: Type.Optional(
@@ -85,7 +85,10 @@ export const ZepBookTool = {
       }),
     ),
     ort: Type.Optional(
-      Type.String({ description: "Location code, e.g. 'D-Office' or 'D'. Defaults to 'NULL' (first place of work)." }),
+      Type.String({
+        description:
+          "Location code, e.g. 'D-Office' (office), 'D' (inland away) or 'D-3M'. The default 'NULL' is the first place of work (Erste Tätigkeitsstätte).",
+      }),
     ),
     entries: Type.Optional(
       Type.Array(
@@ -228,6 +231,10 @@ export const ZepBookTool = {
         const comment = entry.bemerkung ?? params.bemerkung ?? "";
 
         const vorgangLabel = scope.vorgaenge.find((v) => v.id === vorgangId)?.label;
+        // Always state the place of work that goes onto the wire: 'NULL' is
+        // the default (Erste Tätigkeitsstätte) and is exactly what a booking
+        // without an explicit ort gets, so it must not be invisible here.
+        const ortLabel = form.orte.find((o) => o.id === ort)?.label;
 
         planned.push({
           request: {
@@ -245,7 +252,8 @@ export const ZepBookTool = {
             `${date}  ${from}-${to}  (${duration})\n` +
             `         project ${projectId}${scope.project ? ` "${scope.project.label}"` : ""}\n` +
             `         Vorgang ${vorgangId}${vorgangLabel ? ` "${vorgangLabel}"` : ""}\n` +
-            `         Tätigkeit ${taetigkeit}${ort === "NULL" ? "" : `, Ort ${ort}`}` +
+            `         Tätigkeit ${taetigkeit}, Ort ${ort}` +
+            `${ortLabel && ortLabel !== ort ? ` (${ortLabel})` : ""}` +
             `${comment ? `\n         "${comment}"` : ""}`,
         });
       }

package/src/tools/zep-doctor.ts

@@ -0,0 +1,297 @@
+/**
+ * zep_doctor -- diagnose the ZEP setup without spending a login attempt.
+ *
+ * Why this exists: every login attempt costs one of only five tries before
+ * ZEP locks the account, and a rejected login says only "Benutzername oder
+ * Kennwort falsch" - it cannot distinguish a wrong userid from a wrong
+ * password, nor from a config file that carries a trailing space. This tool
+ * checks everything that can be checked for free, and performs the real
+ * credential check only when explicitly asked for.
+ */
+
+import { existsSync, statSync } from "node:fs";
+import { Type } from "typebox";
+
+import {
+  configPath,
+  getActiveProfileName,
+  getProfile,
+  getSession,
+  listProfiles,
+  refreshConfig,
+  sessionPath,
+} from "../config.ts";
+import { ZepClient } from "../clients/zep-client.ts";
+import { errorResult, textResult, type ToolResult } from "./shared.ts";
+
+interface Check {
+  readonly name: string;
+  readonly status: "ok" | "warn" | "fail" | "skip";
+  readonly detail: string;
+  /** What to do about it, when it is not "ok". */
+  readonly hint?: string;
+}
+
+const ICON = { ok: "OK  ", warn: "WARN", fail: "FAIL", skip: "SKIP" } as const;
+
+function render(checks: ReadonlyArray<Check>): string {
+  return checks
+    .map((c) => {
+      const head = `${ICON[c.status]}  ${c.name}: ${c.detail}`;
+      return c.hint ? `${head}\n         -> ${c.hint}` : head;
+    })
+    .join("\n");
+}
+
+export const ZepDoctorTool = {
+  name: "zep_doctor",
+  label: "ZEP Doctor",
+  description:
+    "Check the ZEP configuration and connectivity before booking: config file, permissions, profile fields, password hygiene (whitespace is the usual cause of 'Benutzername oder Kennwort falsch'), cached session, and reachability of the server. Uses no login attempt unless checkCredentials is set, and reports how many password tries are left.",
+  parameters: Type.Object({
+    profile: Type.Optional(
+      Type.String({ description: "ZEP profile to check. Defaults to the active profile." }),
+    ),
+    checkCredentials: Type.Optional(
+      Type.Boolean({
+        description:
+          "Also perform ONE real login attempt to verify userid and password. This consumes one of the 5 tries before ZEP locks the account, so it is off by default.",
+      }),
+    ),
+  }),
+
+  async execute(
+    _toolCallId: string,
+    params: { profile?: string; checkCredentials?: boolean },
+  ): Promise<ToolResult> {
+    // Re-read from disk: the doctor is exactly the tool you run right after
+    // editing the config by hand.
+    refreshConfig();
+    const checks: Check[] = [];
+
+    // ------------------------------------------------------------ config file
+    const path = configPath();
+    if (!existsSync(path)) {
+      checks.push({
+        name: "config file",
+        status: "fail",
+        detail: `${path} does not exist`,
+        hint: "Run zep_setup, or write the file by hand (profiles.<name>.userid/password, activeProfile).",
+      });
+      return errorResult(render(checks), { ok: false });
+    }
+
+    const mode = statSync(path).mode & 0o777;
+    checks.push({
+      name: "config file",
+      status: mode === 0o600 ? "ok" : "warn",
+      detail: `${path} (mode ${mode.toString(8)})`,
+      ...(mode === 0o600
+        ? {}
+        : { hint: `chmod 600 ${path} - the file holds a password in clear text.` }),
+    });
+
+    const profiles = listProfiles();
+    const name = params.profile ?? getActiveProfileName();
+    if (!name) {
+      checks.push({
+        name: "active profile",
+        status: "fail",
+        detail: `none set (known: ${profiles.join(", ") || "none"})`,
+        hint: 'Set "activeProfile" in the config file, or run zep_profile action=use.',
+      });
+      return errorResult(render(checks), { ok: false });
+    }
+
+    let account;
+    try {
+      account = getProfile(name);
+    } catch (error) {
+      checks.push({
+        name: `profile "${name}"`,
+        status: "fail",
+        detail: error instanceof Error ? error.message : String(error),
+        hint: `Known profiles: ${profiles.join(", ") || "none"}`,
+      });
+      return errorResult(render(checks), { ok: false });
+    }
+    checks.push({ name: "profile", status: "ok", detail: `"${name}" (active)` });
+
+    // --------------------------------------------------------------- fields
+    const missing = (["baseUrl", "mandant", "userid", "password"] as const).filter(
+      (field) => !account[field],
+    );
+    checks.push(
+      missing.length === 0
+        ? { name: "profile fields", status: "ok", detail: "baseUrl, mandant, userid, password" }
+        : {
+            name: "profile fields",
+            status: "fail",
+            detail: `missing or empty: ${missing.join(", ")}`,
+            hint: 'Add the field to the profile in the config file, or re-run zep_setup.',
+          },
+    );
+
+    checks.push({
+      name: "target",
+      status: "ok",
+      detail: `${account.baseUrl}/${account.mandant} as ${account.userid}`,
+    });
+
+    // ------------------------------------------------- password hygiene
+    const raw = account.password ?? "";
+    const hygiene = passwordShapeIssues(raw);
+
+    checks.push(
+      hygiene.length === 0
+        ? { name: "password shape", status: "ok", detail: `${raw.length} characters, no whitespace` }
+        : {
+            name: "password shape",
+            status: "fail",
+            detail: hygiene.join("; "),
+            hint: "Fix the stored password. ZEP reports all of these as 'Benutzername oder Kennwort falsch'.",
+          },
+    );
+
+    // --------------------------------------------------------- session cache
+    const cached = getSession(name);
+    let liveSession: ZepClient | null = null;
+
+    if (!cached) {
+      checks.push({
+        name: "cached session",
+        status: "skip",
+        detail: `${sessionPath()} has no entry for "${name}"`,
+        hint: "A login is needed once; after that the session is reused.",
+      });
+    } else {
+      const client = new ZepClient(account, {});
+      client.applySession(cached);
+      const alive = await client.probe();
+      checks.push({
+        name: "cached session",
+        status: alive ? "ok" : "warn",
+        detail: `CLIENTSESSID ${cached.clientsessid} saved ${cached.savedAt} - ${
+          alive ? "still accepted" : "no longer accepted"
+        }`,
+        ...(alive ? {} : { hint: "It expired; the next call performs a fresh login." }),
+      });
+      if (alive) liveSession = client;
+    }
+
+    // ------------------------------------------------------------ reachability
+    // A dedicated client: ping() primes a fresh PHPSESSID, which must not
+    // overwrite the one belonging to a live session.
+    try {
+      const ping = await new ZepClient(account, {}).ping();
+      checks.push({
+        name: "reachability",
+        status: ping.loginPageOk || ping.redirectedToApp ? "ok" : "warn",
+        detail: `GET /view/login.php -> HTTP ${ping.status}, login form ${
+          ping.loginPageOk ? "present" : "absent"
+        }${ping.redirectedToApp ? ", redirects into the app (already authenticated)" : ""}`,
+        ...(ping.loginPageOk || ping.redirectedToApp
+          ? {}
+          : { hint: "Unexpected response; a proxy or maintenance page may be in the way." }),
+      });
+    } catch (error) {
+      checks.push({
+        name: "reachability",
+        status: "fail",
+        detail: error instanceof Error ? error.message : String(error),
+        hint: "Check network/proxy. Override baseUrl per profile if a mirror is used.",
+      });
+    }
+
+    // --------------------------------------------------------- live session
+    if (liveSession) {
+      try {
+        const { form } = await liveSession.loadForm();
+        checks.push({
+          name: "booking form",
+          status: "ok",
+          detail: `${form.projects.length} projects, ${form.vorgaenge.length} Vorgänge for the selected project`,
+        });
+      } catch (error) {
+        checks.push({
+          name: "booking form",
+          status: "fail",
+          detail: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+
+    // ------------------------------------------------------ credential check
+    if (params.checkCredentials) {
+      const client = new ZepClient(account, {});
+      try {
+        const result = await client.login();
+        checks.push({
+          name: "credential check",
+          status: result.ok ? "ok" : "fail",
+          detail: result.ok
+            ? `login accepted (CLIENTSESSID ${result.clientsessid})`
+            : `${result.message ?? "rejected"}${
+                result.attemptsLeft !== undefined ? ` - ${result.attemptsLeft} tries left` : ""
+              }`,
+          ...(result.ok
+            ? {}
+            : {
+                hint:
+                  "ZEP cannot tell 'wrong userid' from 'wrong password'. Verify both; do NOT retry blindly - the account locks after 5.",
+              }),
+        });
+      } catch (error) {
+        checks.push({
+          name: "credential check",
+          status: "fail",
+          detail: error instanceof Error ? error.message : String(error),
+        });
+      }
+    } else {
+      checks.push({
+        name: "credential check",
+        status: "skip",
+        detail: "not attempted (costs one of 5 tries before lockout)",
+        hint: "Re-run with checkCredentials=true only when the stored userid/password are confirmed.",
+      });
+    }
+
+    const text = render(checks);
+    const failed = checks.some((c) => c.status === "fail");
+    const warnOrFail = failed || checks.some((c) => c.status === "warn");
+
+    const verdict = failed
+      ? "\n\nVerdict: something must be fixed before booking will work."
+      : warnOrFail
+        ? "\n\nVerdict: usable, with warnings above."
+        : "\n\nVerdict: everything checks out.";
+
+    return warnOrFail
+      ? errorResult(text + verdict, { ok: !failed, checks })
+      : textResult(text + verdict, { ok: true, checks });
+  },
+};
+
+/**
+ * Problems with a stored password that ZEP would all report as
+ * "Benutzername oder Kennwort falsch" - i.e. silently. Pure, so it is testable
+ * without a config file.
+ */
+export function passwordShapeIssues(raw: string): string[] {
+  const issues: string[] = [];
+  if (raw !== raw.trim()) issues.push("leading/trailing whitespace (copy-paste!)");
+  if (/\s/.test(raw.trim())) issues.push("contains an inner whitespace character");
+  if (raw === "undefined" || raw === "null") issues.push(`literally the string "${raw}"`);
+  if (raw.length < 6) issues.push(`suspiciously short (${raw.length} chars)`);
+  // `!` starts history expansion in an interactive bash. A password written
+  // through a shell command can silently lose everything from the `!` on -
+  // and ZEP then only says "wrong password".
+  if (raw.includes("!")) {
+    issues.push(
+      `contains "!" (${raw.length} chars) - in an interactive shell "!" starts history expansion, ` +
+        "so a password written via a command line may be truncated at that position",
+    );
+  }
+  return issues;
+}

package/src/tools/zep-profile.ts

@@ -10,6 +10,7 @@ import {
   getActiveProfileName,
   listProfiles,
   useProfile,
+  refreshConfig,
 } from "../config.ts";
 import { errorResult, textResult, type ToolResult } from "./shared.ts";
 
@@ -31,6 +32,7 @@ export const ZepProfileTool = {
     _toolCallId: string,
     params: { action?: string; name?: string },
   ): Promise<ToolResult> {
+    refreshConfig();
     const action = params.action ?? "list";
     try {
       if (action === "list") {

package/src/tools/zep-status.ts

@@ -4,7 +4,13 @@
 
 import { Type } from "typebox";
 
-import { configPath, getActiveProfileName, listProfiles, sessionPath } from "../config.ts";
+import {
+  configPath,
+  getActiveProfileName,
+  listProfiles,
+  refreshConfig,
+  sessionPath,
+} from "../config.ts";
 import { ZepClient } from "../clients/zep-client.ts";
 import { createClient, ZepError } from "../session.ts";
 import { formatFormData } from "../formatting/formatters.ts";
@@ -35,6 +41,7 @@ export const ZepStatusTool = {
     _toolCallId: string,
     params: { profile?: string; probe?: boolean; relogin?: boolean },
   ): Promise<ToolResult> {
+    refreshConfig();
     const lines: string[] = [];
     const profiles = listProfiles();
 

package/src/types.ts

@@ -94,6 +94,13 @@ export interface ZepBooking {
   readonly taetigkeit: string;
   readonly billable: boolean;
   readonly comment: string;
+  /**
+   * Place of work as the table renders it, e.g. `D-Office`.
+   *
+   * ZEP only draws this cell when there is something to say, so `null` means
+   * "no cell rendered" and therefore the default place of work (`NULL`).
+   */
+  readonly ort: string | null;
 }
 
 export interface ZepWeekDay {