@kenkaiiii/ggcoder 5.72.0 → 5.74.0

package/assets/skills/refactoring/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: refactoring
-description: Use when restructuring existing code without changing behavior — "refactor", "clean up", "reduce duplication", "split this god class", "modernize", migrating legacy code or APIs (strangler fig, parallel change, codemods across many files, callback→async), planning a refactor, or mid-build when a change needs preparatory restructuring first. Two hats, test-guarded steps, revert-on-red. Do NOT use for new features, bug fixes (stubborn ones: root-cause), performance tuning (lean), schema/data migrations (durable), styling or copy, the refactor step of a user-requested TDD flow (tdd), or a from-scratch rewrite.
+description: Use for behavior-preserving restructuring: extract, move, split, deduplicate, plan a refactor, or migrate an implementation behind an unchanged contract. Baseline tests, small steps, revert-on-red. Do NOT use for requested behavior or API-contract changes (including new return/error semantics), even when called a "refactor"; use the normal implementation workflow with regression tests and update affected callers together. Also exclude bug fixes (root-cause when stubborn), performance work (lean), data migrations (durable), styling/copy, TDD's refactor step (tdd), and rewrites.
 license: Behavior-preservation methodology synthesized from public sources (Fowler's Refactoring catalog, Tidy First?, and community agent skills by bienhoang, wondelai, mattpocock, jeffallan, vasilyu1983), audited 2026-09-12.
 ---
 
 # Refactoring
 
+**Scope gate:** Decide from the requested behavior, not the word "refactor". A requested change to return values, error handling, or an API contract is implementation work, not a behavior-preserving cleanup. Use the normal implementation workflow: inspect the affected callers, make the requested contract and caller changes together, add regression coverage, and run the checks. Do not manufacture a separate pure-rename stage merely to enter this skill. Existing authorization and safety controls still apply. For a genuine behavior-preserving refactor, use the gated loop below unchanged.
+
 **Route first:**
 
 | Situation | Mode | Next |

package/dist/app-error.d.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import { type FormattedChatError } from "@kenkaiiii/gg-ai";
+declare const appErrorSchema: z.ZodObject<{
+    scope: z.ZodDefault<z.ZodString>;
+    headline: z.ZodString;
+    message: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    guidance: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    reason: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    source: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    provider: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    statusCode: z.ZodCatch<z.ZodOptional<z.ZodNumber>>;
+    requestId: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    occurredAt: z.ZodCatch<z.ZodOptional<z.ZodNumber>>;
+    resetsAt: z.ZodCatch<z.ZodOptional<z.ZodNumber>>;
+}, z.core.$strip>;
+export type AppErrorPayload = z.infer<typeof appErrorSchema>;
+/** The same sanitized snapshot goes to SSE and the append-only history marker. */
+export declare function createAppErrorPayload(error: FormattedChatError, scope: string, occurredAt: number, secrets: Iterable<string>): AppErrorPayload;
+/** Backward-compatible read: no migration or reclassification of old saved text. */
+export declare function restoreAppErrorPayload(value: unknown): AppErrorPayload | undefined;
+export {};

package/dist/app-error.js

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import { redactValue } from "@kenkaiiii/gg-ai";
+const timestamp = z.number().int().nonnegative().max(8_640_000_000_000).optional().catch(undefined);
+const optionalText = z.string().max(8_000).optional().catch(undefined);
+const appErrorSchema = z.object({
+    scope: z.string().max(80).default("error"),
+    headline: z.string().min(1).max(1_000),
+    message: optionalText,
+    guidance: optionalText,
+    reason: z.string().max(40).optional().catch(undefined),
+    source: z.string().max(40).optional().catch(undefined),
+    provider: z.string().max(80).optional().catch(undefined),
+    statusCode: z.number().int().min(100).max(599).optional().catch(undefined),
+    requestId: z.string().max(300).optional().catch(undefined),
+    occurredAt: timestamp,
+    resetsAt: timestamp,
+});
+/** The same sanitized snapshot goes to SSE and the append-only history marker. */
+export function createAppErrorPayload(error, scope, occurredAt, secrets) {
+    return redactValue({
+        scope,
+        headline: error.headline,
+        message: error.message,
+        guidance: error.guidance,
+        reason: error.reason,
+        source: error.source,
+        provider: error.provider,
+        statusCode: error.statusCode,
+        requestId: error.requestId,
+        occurredAt,
+        resetsAt: error.resetsAt,
+    }, { secrets, maxStringLength: 8_000 });
+}
+/** Backward-compatible read: no migration or reclassification of old saved text. */
+export function restoreAppErrorPayload(value) {
+    const parsed = appErrorSchema.safeParse(value);
+    return parsed.success ? parsed.data : undefined;
+}
+//# sourceMappingURL=app-error.js.map

package/dist/app-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-error.js","sourceRoot":"","sources":["../src/app-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,WAAW,EAA2B,MAAM,kBAAkB,CAAC;AAExE,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;AACpG,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;AACvE,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;IAC1C,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC;IACtC,OAAO,EAAE,YAAY;IACrB,QAAQ,EAAE,YAAY;IACtB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC;IACtD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC;IACtD,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC;IACxD,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC;IAC1E,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC;IAC1D,UAAU,EAAE,SAAS;IACrB,QAAQ,EAAE,SAAS;CACpB,CAAC,CAAC;AAGH,kFAAkF;AAClF,MAAM,UAAU,qBAAqB,CACnC,KAAyB,EACzB,KAAa,EACb,UAAkB,EAClB,OAAyB;IAEzB,OAAO,WAAW,CAChB;QACE,KAAK;QACL,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,UAAU;QACV,QAAQ,EAAE,KAAK,CAAC,QAAQ;KACzB,EACD,EAAE,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,CACpC,CAAC;AACJ,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,sBAAsB,CAAC,KAAc;IACnD,MAAM,MAAM,GAAG,cAAc,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/C,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AAClD,CAAC"}

package/dist/app-sidecar.js

@@ -19,7 +19,8 @@ import path from "node:path";
 import { randomUUID } from "node:crypto";
 import { parseArgs } from "node:util";
 import { spawn } from "node:child_process";
-import { environmentSecrets, formatError, redactValue, } from "@kenkaiiii/gg-ai";
+import { environmentSecrets, formatChatError, redactValue, } from "@kenkaiiii/gg-ai";
+import { createAppErrorPayload, restoreAppErrorPayload, } from "./app-error.js";
 import { runJsonMode } from "./modes/json-mode.js";
 import { runSubagentWorkerMode } from "./modes/subagent-worker-mode.js";
 import { setStreamDiagnostic } from "@kenkaiiii/gg-agent";
@@ -68,6 +69,7 @@ import { loadCustomCommands } from "./core/custom-commands.js";
 import { discoverProjects } from "./core/project-discovery.js";
 import { listSidecarSessions } from "./app-sidecar-sessions.js";
 import { loadTasksSync, saveTasksSync, pruneDoneTasksSync, getNextPendingTask, markTaskInProgress, } from "./core/tasks-store.js";
+import { readChecklistSnapshot } from "./core/checklist-snapshot.js";
 import { initLogger, log } from "./core/logger.js";
 import { installTerminationHandlers } from "./core/shutdown.js";
 import { KeepAwake } from "./core/keep-awake.js";
@@ -1319,35 +1321,21 @@ async function createSession(deps, opts) {
     // `400 {"code":"400",...}` with no "is this me or them / when does it reset"
     // context that the CLI has always given.
     function broadcastError(type, logLabel, err) {
-        const f = formatError(err);
+        const f = formatChatError(err);
         const message = f.message ? desktopGuidance(f.message) : undefined;
         const guidance = localNetworkGuidance(f.source) ?? desktopGuidance(f.guidance);
+        const payload = createAppErrorPayload({ ...f, ...(message ? { message } : {}), guidance }, type, Date.now(), environmentSecrets(process.env));
         log("ERROR", "app-sidecar", logLabel, {
-            headline: f.headline,
+            headline: payload.headline,
             source: f.source,
-            ...(message ? { message } : {}),
-            ...(f.provider ? { provider: f.provider } : {}),
-            ...(f.statusCode != null ? { statusCode: String(f.statusCode) } : {}),
-            ...(f.requestId ? { requestId: f.requestId } : {}),
+            ...(payload.message ? { message: payload.message } : {}),
+            ...(payload.provider ? { provider: payload.provider } : {}),
+            ...(payload.statusCode != null ? { statusCode: String(payload.statusCode) } : {}),
+            ...(payload.requestId ? { requestId: payload.requestId } : {}),
         });
-        broadcast(type, {
-            headline: f.headline,
-            ...(message ? { message } : {}),
-            guidance,
-            ...(f.provider ? { provider: f.provider } : {}),
-            ...(f.statusCode != null ? { statusCode: f.statusCode } : {}),
-            ...(f.resetsAt != null ? { resetsAt: f.resetsAt } : {}),
-        });
-        // Persist the error row (display-only marker) so a resumed session shows
-        // the same headline/message/guidance the live run did. Best-effort.
-        void session
-            .persistAppMarker("error", {
-            scope: type,
-            headline: f.headline,
-            ...(message ? { message } : {}),
-            guidance,
-        })
-            .catch(() => { });
+        broadcast(type, payload);
+        // Same sanitized snapshot for live and restored rows, including reset metadata.
+        void session.persistAppMarker("error", payload).catch(() => { });
     }
     // ── MCP elicitation bridge ─────────────────────────────────
     // An MCP server can ask for user input in the middle of a tool call. The
@@ -3412,16 +3400,9 @@ async function createSession(deps, opts) {
                             });
                         }
                         else if (marker.kind === "error" && typeof d.headline === "string") {
-                            history.push({
-                                role: "assistant",
-                                text: "",
-                                error: {
-                                    scope: typeof d.scope === "string" ? d.scope : "error",
-                                    headline: d.headline,
-                                    ...(typeof d.message === "string" ? { message: d.message } : {}),
-                                    ...(typeof d.guidance === "string" ? { guidance: d.guidance } : {}),
-                                },
-                            });
+                            const error = restoreAppErrorPayload(d);
+                            if (error)
+                                history.push({ role: "assistant", text: "", error });
                         }
                         else if (marker.kind === "interrupted_run") {
                             // Rendered as an error row: the run's tools already changed the
@@ -3968,6 +3949,29 @@ async function createSession(deps, opts) {
             json(res, 200, { tasks: pruneDoneTasksSync(cwd) });
             return;
         }
+        if (method === "GET" && url === "/checklist") {
+            const controller = new AbortController();
+            res.once("close", () => controller.abort());
+            void (async () => {
+                try {
+                    const result = await readChecklistSnapshot(cwd, new Date(), controller.signal);
+                    if (res.destroyed)
+                        return;
+                    if (!result.ok) {
+                        log("WARN", "app-sidecar", "checklist read failed", { error: result.error });
+                        json(res, 500, { error: result.error });
+                        return;
+                    }
+                    json(res, 200, result.value);
+                }
+                catch (error) {
+                    log("WARN", "app-sidecar", "checklist snapshot failed", { error: String(error) });
+                    if (!res.destroyed)
+                        json(res, 500, { error: "Could not read the project checklist" });
+                }
+            })();
+            return;
+        }
         // ── Radio (app-wide) ──────────────────────────────────────
         // Radio is now APP-WIDE: all windows share one daemon process, and the
         // player lives in `core/radio.ts` module-level singletons (one stream for