@agent-plan/core 0.2.19-next.0 → 0.2.19-next.10

package/dist/recap.d.ts

@@ -0,0 +1,32 @@
+import type { PlanStore } from "./plan-store.js";
+/**
+ * Web UI info for the recap (harness-agnostic — no module globals).
+ * Pass { localUrl, lanUrl, port } from whichever harness runs the server.
+ * Omit/empty → the recap notes the dashboard is not running.
+ */
+export interface RecapWebInfo {
+    localUrl?: string | undefined;
+    lanUrl?: string | undefined;
+    port?: number | undefined;
+}
+/** Which harness is presenting the recap — drives command-name hints. */
+export type RecapHarness = "pi" | "mcp";
+export interface RecapOptions {
+    harness?: RecapHarness;
+}
+/**
+ * Build a consolidated planner recap (project state + active focus + pending
+ * handoffs + web URL). SHARED across all harnesses (Pi command, Pi tool,
+ * Claude Code/Codex MCP) so every adapter presents identical content.
+ *
+ * English by default; Italian if project.chatLanguage is set to Italian.
+ * Uses human-readable names/titles plus composite IDs (F00x / P00x(F00x) / T00x)
+ * so the user/agent can reference entities unambiguously.
+ *
+ * Pass opts.harness to get harness-correct command hints in the actionable
+ * lines (e.g. "/planner task start" in Pi vs "planner-task-start" in MCP).
+ * When the plan is fully complete, stale resume.nextSteps are suppressed and a
+ * "plan complete — add a feature/phase to continue" hint is shown instead.
+ */
+export declare function buildRecap(st: PlanStore, web?: RecapWebInfo, opts?: RecapOptions): Promise<string>;
+//# sourceMappingURL=recap.d.ts.map

package/dist/recap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recap.d.ts","sourceRoot":"","sources":["../src/recap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAGjD;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B;AAED,yEAAyE;AACzE,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,KAAK,CAAC;AAExC,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAKD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,GAAE,YAAiB,EAAE,IAAI,GAAE,YAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CA8HhH"}

package/dist/recap.js

@@ -0,0 +1,119 @@
+import { formatPhaseRef, formatTwoDigitNumber } from "./naming.js";
+const fref = (n) => `F${formatTwoDigitNumber(n)}`;
+const tref = (n) => `T${formatTwoDigitNumber(n)}`;
+/**
+ * Build a consolidated planner recap (project state + active focus + pending
+ * handoffs + web URL). SHARED across all harnesses (Pi command, Pi tool,
+ * Claude Code/Codex MCP) so every adapter presents identical content.
+ *
+ * English by default; Italian if project.chatLanguage is set to Italian.
+ * Uses human-readable names/titles plus composite IDs (F00x / P00x(F00x) / T00x)
+ * so the user/agent can reference entities unambiguously.
+ *
+ * Pass opts.harness to get harness-correct command hints in the actionable
+ * lines (e.g. "/planner task start" in Pi vs "planner-task-start" in MCP).
+ * When the plan is fully complete, stale resume.nextSteps are suppressed and a
+ * "plan complete — add a feature/phase to continue" hint is shown instead.
+ */
+export async function buildRecap(st, web = {}, opts = {}) {
+    const [plan, resume, handoffs] = await Promise.all([
+        st.loadAll(),
+        st.loadResume().catch(() => null),
+        st.listHandoffs(),
+    ]);
+    const feats = plan.features.features;
+    const phases = plan.phases;
+    const allTasks = phases.flatMap((p) => p.tasks.map((task) => ({ phase: p, task })));
+    const totalF = feats.length;
+    const doneF = feats.filter((x) => x.status === "done").length;
+    const activeF = feats.filter((x) => x.status === "in-progress").length;
+    const totalP = phases.length;
+    const doneP = phases.filter((x) => x.status === "done").length;
+    const activeP = phases.filter((x) => x.status === "in-progress" || x.status === "discovery").length;
+    const totalT = allTasks.length;
+    const doneT = allTasks.filter(({ task }) => task.status === "done").length;
+    const activeT = allTasks.filter(({ task }) => task.status === "in-progress").length;
+    // Plan is fully complete: there is work and all of it is done, nothing active.
+    // (totalT > 0 guards the empty/unstarted case from looking "complete".)
+    const planComplete = totalT > 0 && doneT === totalT && doneP === totalP && doneF === totalF;
+    // Current focus = first in-progress task (and its phase/feature).
+    const focusTask = allTasks.find(({ task }) => task.status === "in-progress");
+    const focusPhase = focusTask?.phase;
+    const focusFeature = focusPhase ? feats.find((x) => x.id === focusPhase.featureId) : undefined;
+    const italian = (plan.project.chatLanguage || "").toLowerCase().includes("ital");
+    // Harness-aware command names for actionable hints.
+    const isPi = opts.harness === "pi";
+    const cmd = (piCmd, mcpCmd) => (isPi ? piCmd : mcpCmd);
+    const taskAddCmd = cmd("/planner task add", "planner-task-add");
+    const taskStartCmd = cmd("/planner task start", "planner-task-start");
+    const featureAddCmd = cmd("/planner feature add", "planner-feature-add");
+    const phaseAddCmd = cmd("/planner phase add", "planner-phase-add");
+    const handoffShowCmd = cmd("/planner handoff show", "planner-handoff-show");
+    const lines = [];
+    lines.push(italian ? "## Ripresa planner" : "## Planner recap");
+    const name = plan.project.name || "(unnamed project)";
+    lines.push(`${italian ? "Progetto" : "Project"}: ${name}${plan.project.goal ? " — " + plan.project.goal : ""}`);
+    lines.push(italian
+        ? `Avanzamento: feature ${doneF}/${totalF} completate (${activeF} attive) · fasi ${doneP}/${totalP} completate (${activeP} attive) · task ${doneT}/${totalT} completati (${activeT} attivi)`
+        : `Progress: Features ${doneF}/${totalF} done (${activeF} active) · Phases ${doneP}/${totalP} done (${activeP} active) · Tasks ${doneT}/${totalT} done (${activeT} active)`);
+    if (focusTask && focusPhase) {
+        const fr = focusFeature ? fref(focusFeature.number) : "?";
+        const pr = formatPhaseRef(focusPhase.number, focusFeature?.number);
+        const tr = tref(focusTask.task.number);
+        lines.push(`${italian ? "Focus corrente" : "Current focus"}: ${fr} — ${focusFeature?.name ?? "?"} / ${pr} — ${focusPhase.title} / ${tr} — ${focusTask.task.title} (in-progress)`);
+    }
+    else if (planComplete) {
+        lines.push(italian
+            ? "Focus corrente: piano completo — tutte le feature/fasi/task sono concluse."
+            : "Current focus: plan complete — all features/phases/tasks are done.");
+    }
+    else {
+        lines.push(`${italian ? "Focus corrente" : "Current focus"}: ${italian ? "nessun task attivo — rivedi il piano e scegli il prossimo task concreto" : "no active task — review the plan and pick the next concrete task"}`);
+    }
+    // Next step: the phase handoff (phase.handoff) is the authoritative,
+    // actively-managed resume context. When a handoff is pending, point to it
+    // instead of surfacing potentially-stale resume.json nextSteps. When no
+    // handoff exists, fall back to resume.nextSteps but mark them as possibly
+    // stale (free-text that refreshResume never touches, so they can drift).
+    if (handoffs.length > 0) {
+        lines.push(italian
+            ? `Prossimo step: leggi l'handoff di fase pendente sotto (fonte autorevole, gestita attivamente). I nextSteps legacy di resume.json sono soppressi perché possono essere stale.`
+            : `Next step: read the pending phase handoff below (authoritative, actively maintained). Legacy resume.json nextSteps are suppressed because they may be stale.`);
+    }
+    else if (!planComplete && resume?.nextSteps?.length) {
+        lines.push(`${italian ? "Prossimo step" : "Next step"}: ${resume.nextSteps[0]}`);
+        const staleNote = resume.nextStepsUpdatedAt
+            ? (italian
+                ? `⚠️ nextSteps free-text da resume.json, ultimo aggiornamento ${resume.nextStepsUpdatedAt} — può essere stale; verifica contro lo stato attuale prima di agire.`
+                : `⚠️ nextSteps are free-text from resume.json, last updated ${resume.nextStepsUpdatedAt} — may be stale; verify against current state before acting.`)
+            : (italian
+                ? `⚠️ nextSteps free-text da resume.json — può essere stale; verifica contro lo stato attuale prima di agire.`
+                : `⚠️ nextSteps are free-text from resume.json — may be stale; verify against current state before acting.`);
+        lines.push(staleNote);
+    }
+    if (handoffs.length > 0) {
+        lines.push("", italian ? `## Handoff di fase pendenti (${handoffs.length})` : `## Pending phase handoffs (${handoffs.length})`);
+        handoffs.forEach((h, i) => lines.push(`[${i + 1}] ${h.compositeRef} — ${h.updatedAt} — "${h.firstLine}"`));
+        lines.push("", italian
+            ? `→ Leggi quello pertinente con ${handoffShowCmd} <ref> (valida contro lo stato attuale). L'handoff è MANTENUTO finché un task della fase non parte (auto-archiviato) o la fase non si conclude — non serve cancellarlo a mano.`
+            : `→ Read the relevant one with ${handoffShowCmd} <ref> (validate against current state). It is KEPT until a task in that phase starts (then auto-archived) or the phase completes — no need to clear it manually.`);
+    }
+    else if (planComplete) {
+        lines.push("", italian
+            ? `Piano completo — aggiungi una nuova feature (${featureAddCmd}) o fase (${phaseAddCmd}) per continuare.`
+            : `Plan complete — add a new feature (${featureAddCmd}) or phase (${phaseAddCmd}) to continue.`);
+    }
+    else if (activeT === 0) {
+        lines.push("", italian
+            ? `Nessun handoff pendente e nessun task in-progress. Usa ${taskAddCmd} / ${taskStartCmd} per iniziare.`
+            : `No phase handoff pending and no task in-progress. Use ${taskAddCmd} / ${taskStartCmd} to begin work.`);
+    }
+    if (web.localUrl) {
+        lines.push("", italian ? "## Web UI" : "## Web UI", `🌐 Web UI: ${web.localUrl}${web.lanUrl ? " (LAN: " + web.lanUrl + ")" : ""}${web.port ? " (port " + web.port + ")" : ""}`);
+    }
+    else {
+        lines.push("", italian ? "## Web UI" : "## Web UI", `🌐 Web UI: ${italian ? "non attiva — avvia con /planner load" : "not running — start with /planner load"}`);
+    }
+    lines.push("", italian ? "Vuoi che riprendiamo da qui?" : "Do you want to resume from here?");
+    return lines.join("\n");
+}

package/dist/refs.d.ts

@@ -21,4 +21,27 @@ import type { Phase, Feature } from "./schema.js";
  * @param ref     the human-facing ref (P00x / P00x(F00x) / UUID / title)
  */
 export declare function findPhaseByRef(phases: Phase[], features: Feature[], ref: string): Phase | undefined;
+/**
+ * Resolve a task reference to { phase, task }. Harness-agnostic, shared by all
+ * adapters so resolution semantics are identical everywhere.
+ *
+ * Supported task refs (case-insensitive):
+ *   - UUID:     "bd6ed366-..."            -> task.id
+ *   - Short:    "T003" | "t3"             -> task.number (GLOBALLY unique under the
+ *                                           new global-sequence numbering; bare T00x
+ *                                           is unambiguous across all phases)
+ *   - Compos:   "F001/P002/T003"          -> feature/phase/task numbers with parent
+ *                "P002(F001)/T003"          validation (feature + phase must match)
+ *                "P002/T003"
+ *   - ShortId:  "UUXD1"                   -> task.shortId (5-char, globally unique)
+ *   - Title:    exact match, then includes (backward-compat fallback)
+ *
+ * Returns `undefined` when not found, or when a composite parent (phase/feature)
+ * does not match the resolved task's parent.
+ */
+import type { Task } from "./schema.js";
+export declare function findTaskByRef(phases: Phase[], features: Feature[], ref: string): {
+    phase: Phase;
+    task: Task;
+} | undefined;
 //# sourceMappingURL=refs.d.ts.map

package/dist/refs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"refs.d.ts","sourceRoot":"","sources":["../src/refs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAKlD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,KAAK,EAAE,EACf,QAAQ,EAAE,OAAO,EAAE,EACnB,GAAG,EAAE,MAAM,GACV,KAAK,GAAG,SAAS,CA2BnB"}
+{"version":3,"file":"refs.d.ts","sourceRoot":"","sources":["../src/refs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAKlD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,KAAK,EAAE,EACf,QAAQ,EAAE,OAAO,EAAE,EACnB,GAAG,EAAE,MAAM,GACV,KAAK,GAAG,SAAS,CAgCnB;AACD;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAexC,wBAAgB,aAAa,CAC3B,MAAM,EAAE,KAAK,EAAE,EACf,QAAQ,EAAE,OAAO,EAAE,EACnB,GAAG,EAAE,MAAM,GACV;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,IAAI,CAAA;CAAE,GAAG,SAAS,CAiD1C"}

package/dist/refs.js

@@ -31,7 +31,78 @@ export function findPhaseByRef(phases, features, ref) {
         if (found)
             return found;
     }
-    // 3. Title fallback (backward compatibility with agents using titles)
+    // 3. ShortId
+    found = phases.find((p) => p.shortId && p.shortId.toLowerCase() === normalized);
+    if (found)
+        return found;
+    // 4. Title fallback (backward compatibility with agents using titles)
+    // 5. Title fallback (backward compatibility with agents using titles)
     return (phases.find((p) => p.title.toLowerCase() === normalized) ??
         phases.find((p) => p.title.toLowerCase().includes(normalized)));
 }
+// Extract optional feature/phase/task numbers from a composite ref.
+// Accepts 1+ digits so "t3" == "t003". Numbers are GLOBAL (post-migration).
+function parseTaskComposite(ref) {
+    const t = ref.match(/t0*(\d+)/);
+    const p = ref.match(/p0*(\d+)/);
+    const f = ref.match(/f0*(\d+)/);
+    return {
+        taskNum: t ? parseInt(t[1], 10) : undefined,
+        phaseNum: p ? parseInt(p[1], 10) : undefined,
+        featureNum: f ? parseInt(f[1], 10) : undefined,
+    };
+}
+export function findTaskByRef(phases, features, ref) {
+    const normalized = ref.trim().toLowerCase();
+    if (!normalized)
+        return undefined;
+    // 1. UUID (exact)
+    for (const phase of phases) {
+        const task = phase.tasks.find((t) => t.id.toLowerCase() === normalized);
+        if (task)
+            return { phase, task };
+    }
+    // 2. Composite / short ref with a T segment
+    const { featureNum, phaseNum, taskNum } = parseTaskComposite(normalized);
+    if (taskNum !== undefined) {
+        if (phaseNum !== undefined) {
+            // Composite: validate phase (and feature if present), then resolve task by number.
+            const phase = phases.find((p) => p.number === phaseNum);
+            if (!phase)
+                return undefined;
+            if (featureNum !== undefined) {
+                const feat = features.find((f) => f.number === featureNum);
+                if (!feat || phase.featureId !== feat.id)
+                    return undefined;
+            }
+            const task = phase.tasks.find((t) => t.number === taskNum);
+            if (task)
+                return { phase, task };
+            return undefined;
+        }
+        // Bare T00x — globally unique under the new numbering. Find the one task.
+        for (const phase of phases) {
+            const task = phase.tasks.find((t) => t.number === taskNum);
+            if (task)
+                return { phase, task };
+        }
+    }
+    // 3. ShortId (5-char)
+    for (const phase of phases) {
+        const task = phase.tasks.find((t) => t.shortId && t.shortId.toLowerCase() === normalized);
+        if (task)
+            return { phase, task };
+    }
+    // 4. Title fallback (backward compatibility)
+    for (const phase of phases) {
+        const exact = phase.tasks.find((t) => t.title.toLowerCase() === normalized);
+        if (exact)
+            return { phase, task: exact };
+    }
+    for (const phase of phases) {
+        const incl = phase.tasks.find((t) => t.title.toLowerCase().includes(normalized));
+        if (incl)
+            return { phase, task: incl };
+    }
+    return undefined;
+}