@patimweb/pi-zep 1.0.0 → 1.0.1

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.1",
   "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",

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/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-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();