@docyrus/docyrus 0.0.40 → 0.0.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docyrus/docyrus",
-  "version": "0.0.40",
+  "version": "0.0.41",
   "private": false,
   "description": "Docyrus API CLI",
   "main": "./main.js",

package/resources/pi-agent/extensions/plan.ts

@@ -28,6 +28,7 @@ const PLAN_ANCHOR_TYPE = "plan-anchor";
 const PLAN_CONFIG_FILE = ".pi/plan-policy.json";
 const PLAN_WIDGET_KEY = "plan-mode";
 const PLAN_BRANCH_LABEL = "plan";
+const ARCHITECT_PLAN_ARTIFACT_FILE_NAME = "PLAN.md";
 const ALLOWED_TODO_ACTIONS = new Set(["list", "list-all", "get"]);
 const ALL_THINKING_LEVELS = new Set(["off", "minimal", "low", "medium", "high", "xhigh"] satisfies ThinkingLevel[]);
 
@@ -96,6 +97,12 @@ export interface IReadPlanPolicyResult {
 	error?: string;
 }
 
+interface IPlanningCliEnvironment {
+	executable: string;
+	entryPath: string;
+	scope: "local" | "global";
+}
+
 export type IParseResult<T> = { ok: true; value: T } | { ok: false; error: string };
 
 let currentPlanState: IPlanSessionState | undefined;
@@ -120,6 +127,41 @@ function expandUserPath(inputPath: string): string {
   return inputPath;
 }
 
+function readPlanningCliEnvironment(env: NodeJS.ProcessEnv = process.env): IPlanningCliEnvironment {
+  const executable = env.DOCYRUS_CLI_EXECUTABLE?.trim();
+  const entryPath = env.DOCYRUS_CLI_ENTRY?.trim();
+  const scope = env.DOCYRUS_CLI_SCOPE?.trim() as "local" | "global" | undefined;
+  if (!executable || !entryPath || (scope !== "local" && scope !== "global")) {
+    throw new Error("Missing Docyrus CLI runtime env. Expected DOCYRUS_CLI_EXECUTABLE, DOCYRUS_CLI_ENTRY, and DOCYRUS_CLI_SCOPE.");
+  }
+
+  return {
+    executable,
+    entryPath,
+    scope,
+  };
+}
+
+async function runProjectPlanCliJson<TValue>(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  args: string[],
+): Promise<TValue> {
+  const environment = readPlanningCliEnvironment();
+  const scopedArgs = environment.scope === "global" ? ["-g", ...args] : args;
+  const result = await pi.exec(environment.executable, [environment.entryPath, ...scopedArgs, "--json"], {
+    cwd: ctx.cwd,
+  });
+  const stdout = result.stdout?.toString().trim() || "";
+  const stderr = result.stderr?.toString().trim() || "";
+  const output = stdout || stderr;
+  if (result.code !== 0 || !output) {
+    throw new Error(output || `Command exited with code ${result.code ?? "unknown"}.`);
+  }
+
+  return JSON.parse(output) as TValue;
+}
+
 function resolveAgentRootPath(): string {
   const agentDir = process.env.PI_CODING_AGENT_DIR?.trim();
   return agentDir && agentDir.length > 0 ? expandUserPath(agentDir) : path.join(os.homedir(), ".pi", "agent");
@@ -635,6 +677,28 @@ async function writePlanArtifactFromEvent(event: AgentEndEvent, ctx: ExtensionCo
   }
 }
 
+async function writeArchitectArtifactFromEvent(event: AgentEndEvent, ctx: ExtensionContext): Promise<void> {
+  const state = getPlanState(ctx);
+  if (!state?.active || !state.artifactPath || state.mode !== "architect") {
+    return;
+  }
+
+  const text = extractLastAssistantText(event.messages ?? []);
+  if (!text || parseAskUserRequestFromText(text)) {
+    return;
+  }
+
+  try {
+    await fs.mkdir(state.artifactPath, { recursive: true });
+    await fs.writeFile(path.join(state.artifactPath, ARCHITECT_PLAN_ARTIFACT_FILE_NAME), `${text.trim()}\n`, "utf8");
+  } catch (error) {
+    if (ctx.hasUI) {
+      const message = error instanceof Error ? error.message : String(error);
+      ctx.ui.notify(`Failed to write architect plan artifact: ${message}`, "error");
+    }
+  }
+}
+
 export function shouldBlockTodoAction(action: string | undefined): boolean {
   return !!action && !ALLOWED_TODO_ACTIONS.has(action);
 }
@@ -973,6 +1037,36 @@ export async function endPlanningWorkflow(pi: ExtensionAPI, ctx: ExtensionComman
   setPlanWidget(ctx, undefined);
   await restoreSourceModel(pi, ctx, state);
 
+  if (state.artifactPath) {
+    try {
+      const syncResult = state.mode === "architect"
+        ? await runProjectPlanCliJson<{ updatedTaskIds?: string[] }>(pi, ctx, [
+          "project-plan",
+          "upsert-from-architect",
+          "--artifactDir",
+          state.artifactPath,
+          ...(state.task ? ["--brief", state.task] : []),
+        ])
+        : await runProjectPlanCliJson<{ updatedTaskIds?: string[] }>(pi, ctx, [
+          "project-plan",
+          "upsert-from-plan",
+          "--artifactPath",
+          state.artifactPath,
+          ...(state.task ? ["--task", state.task] : []),
+        ]);
+
+      if (ctx.hasUI) {
+        const updatedCount = Array.isArray(syncResult.updatedTaskIds) ? syncResult.updatedTaskIds.length : 0;
+        ctx.ui.notify(`Project plan synced from ${state.mode} artifact (${updatedCount} task update${updatedCount === 1 ? "" : "s"}).`, "info");
+      }
+    } catch (error) {
+      if (ctx.hasUI) {
+        const message = error instanceof Error ? error.message : String(error);
+        ctx.ui.notify(`Project plan sync failed after ${state.mode}: ${message}`, "warning");
+      }
+    }
+  }
+
   if (ctx.hasUI) {
     const artifactSuffix = state.artifactPath ? ` Artifact: ${state.artifactPath}` : "";
     ctx.ui.notify(`Planning session ended.${artifactSuffix}`, "info");
@@ -1176,6 +1270,7 @@ export default function planExtension(pi: ExtensionAPI) {
     }
 
     await writePlanArtifactFromEvent(event, ctx);
+    await writeArchitectArtifactFromEvent(event, ctx);
   });
 
   pi.on("session_start", async(_event, ctx) => {

package/resources/pi-agent/extensions/tasks.ts

@@ -0,0 +1,497 @@
+import { execFile } from "node:child_process";
+import { StringEnum } from "@mariozechner/pi-ai";
+import { Type } from "@sinclair/typebox";
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+} from "@mariozechner/pi-coding-agent";
+import type { Theme } from "@mariozechner/pi-tui";
+import { Text } from "@mariozechner/pi-tui";
+
+type ITasksAction =
+  | "show"
+  | "get"
+  | "create-feature"
+  | "create-task"
+  | "set-status"
+  | "create-linked-todo";
+
+interface ICliEnvironment {
+  executable: string;
+  entryPath: string;
+  scope: "local" | "global";
+}
+
+interface ICommandResult {
+  code: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+interface IProjectTaskSummary {
+  id: string;
+  title: string;
+  summary: string;
+  type: string;
+  assignee: string;
+  status: string;
+  acceptanceCriteria: string[];
+  featureId: string;
+  sectionId: string;
+  linkedTodoCount: number;
+}
+
+interface IProjectFeatureSummary {
+  id: string;
+  title: string;
+  slug: string;
+  summary: string;
+  sectionId: string;
+  status: string;
+  taskCount: number;
+  tasks: IProjectTaskSummary[];
+}
+
+interface IProjectSectionSummary {
+  sectionId: string;
+  heading: string;
+  filePath: string;
+  status: string;
+  featureCount: number;
+  taskCount: number;
+  features: IProjectFeatureSummary[];
+}
+
+interface IProjectPlanShowPayload {
+  hierarchy: {
+    sections: IProjectSectionSummary[];
+  };
+}
+
+const TaskParams = Type.Object({
+  action: StringEnum([
+    "show",
+    "get",
+    "create-feature",
+    "create-task",
+    "set-status",
+    "create-linked-todo",
+  ] as const),
+  taskId: Type.Optional(Type.String({ description: "Canonical task id" })),
+  featureId: Type.Optional(Type.String({ description: "Canonical feature id" })),
+  sectionId: Type.Optional(Type.String({ description: "Knowledge section id" })),
+  title: Type.Optional(Type.String({ description: "Feature or task title" })),
+  summary: Type.Optional(Type.String({ description: "Feature or task summary" })),
+  slug: Type.Optional(Type.String({ description: "Feature slug" })),
+  type: Type.Optional(Type.String({ description: "Task type" })),
+  assignee: Type.Optional(Type.String({ description: "Task assignee" })),
+  status: Type.Optional(Type.String({ description: "Task status" })),
+  acceptanceCriteria: Type.Optional(Type.Array(Type.String({ description: "Acceptance criterion" }))),
+});
+
+function readCliEnvironment(env: NodeJS.ProcessEnv = process.env): ICliEnvironment {
+  const executable = env.DOCYRUS_CLI_EXECUTABLE?.trim();
+  const entryPath = env.DOCYRUS_CLI_ENTRY?.trim();
+  const scope = env.DOCYRUS_CLI_SCOPE?.trim() as "local" | "global" | undefined;
+  if (!executable || !entryPath || (scope !== "local" && scope !== "global")) {
+    throw new Error("Missing Docyrus CLI runtime env. Expected DOCYRUS_CLI_EXECUTABLE, DOCYRUS_CLI_ENTRY, and DOCYRUS_CLI_SCOPE.");
+  }
+
+  return {
+    executable,
+    entryPath,
+    scope,
+  };
+}
+
+function buildCommandArgs(environment: ICliEnvironment, args: string[], useJson = false): string[] {
+  const scopedArgs = environment.scope === "global" ? ["-g", ...args] : args;
+  return [environment.entryPath, ...scopedArgs, ...(useJson ? ["--json"] : [])];
+}
+
+function summarizeFailure(result: ICommandResult): string {
+  const stderr = result.stderr.trim();
+  if (stderr) {
+    return stderr;
+  }
+
+  const stdout = result.stdout.trim();
+  if (stdout) {
+    return stdout.split(/\r?\n/gu).at(-1) || stdout;
+  }
+
+  if (typeof result.code === "number") {
+    return `Command exited with code ${result.code}.`;
+  }
+
+  return "Command failed.";
+}
+
+function runCli(environment: ICliEnvironment, args: string[], cwd: string, useJson = false): Promise<ICommandResult> {
+  return new Promise((resolve, reject) => {
+    execFile(environment.executable, buildCommandArgs(environment, args, useJson), {
+      cwd,
+      encoding: "utf8",
+      env: {
+        ...process.env,
+      },
+      maxBuffer: 20 * 1024 * 1024,
+    }, (error, stdout, stderr) => {
+      if (error && typeof (error as NodeJS.ErrnoException).code === "string" && (error as NodeJS.ErrnoException).code === "ENOENT") {
+        reject(error);
+        return;
+      }
+
+      resolve({
+        code: typeof (error as { code?: number } | null)?.code === "number" ? (error as { code?: number }).code || null : null,
+        stdout,
+        stderr,
+      });
+    });
+  });
+}
+
+async function runCliJson<TValue>(environment: ICliEnvironment, args: string[], cwd: string): Promise<TValue> {
+  const result = await runCli(environment, args, cwd, true);
+  const output = result.stdout.trim() || result.stderr.trim();
+  if (!output) {
+    throw new Error("Docyrus CLI produced no JSON output.");
+  }
+  if (result.code !== 0) {
+    throw new Error(summarizeFailure(result));
+  }
+  return JSON.parse(output) as TValue;
+}
+
+function formatTaskSummary(task: IProjectTaskSummary): string {
+  return `${task.id} · ${task.title} · ${task.status} · ${task.assignee} · ${task.type}${task.linkedTodoCount > 0 ? ` · ${task.linkedTodoCount} linked todo(s)` : ""}`;
+}
+
+function formatHierarchySummary(payload: IProjectPlanShowPayload): string {
+  const populatedSections = payload.hierarchy.sections.filter((section) => section.features.length > 0);
+  if (populatedSections.length === 0) {
+    return "No project-plan features or tasks yet.";
+  }
+
+  const lines: string[] = [];
+  for (const section of populatedSections) {
+    lines.push(`${section.heading} (${section.status})`);
+    for (const feature of section.features) {
+      lines.push(`  - ${feature.title} (${feature.status})`);
+      for (const task of feature.tasks) {
+        lines.push(`    * ${formatTaskSummary(task)}`);
+      }
+    }
+  }
+
+  return lines.join("\n");
+}
+
+async function selectFromOptions(
+  ctx: ExtensionCommandContext,
+  title: string,
+  options: Array<{ label: string; value: string }>,
+): Promise<string | undefined> {
+  const selected = await ctx.ui.select(title, options.map((option) => option.label));
+  if (selected === undefined) {
+    return undefined;
+  }
+
+  return options.find((option) => option.label === selected)?.value;
+}
+
+async function tasksCommandHandler(pi: ExtensionAPI, ctx: ExtensionCommandContext, rawArgs: string): Promise<void> {
+  const environment = readCliEnvironment();
+  const payload = await runCliJson<IProjectPlanShowPayload>(environment, ["project-plan", "show"], ctx.cwd);
+  const summary = formatHierarchySummary(payload);
+
+  if (!ctx.hasUI) {
+    process.stdout.write(summary.endsWith("\n") ? summary : `${summary}\n`);
+    return;
+  }
+
+  const query = rawArgs.trim().toLowerCase();
+  const sections = payload.hierarchy.sections.filter((section) => section.features.length > 0)
+    .filter((section) => !query || section.heading.toLowerCase().includes(query) || section.sectionId.toLowerCase().includes(query));
+  if (sections.length === 0) {
+    ctx.ui.notify("No project-plan sections with tasks were found.", "info");
+    return;
+  }
+
+  const selectedSectionId = await selectFromOptions(ctx, "Project Sections", sections.map((section) => ({
+    label: `${section.heading} (${section.status})`,
+    value: section.sectionId,
+  })));
+  if (!selectedSectionId) {
+    return;
+  }
+
+  const section = sections.find((item) => item.sectionId === selectedSectionId);
+  if (!section) {
+    return;
+  }
+
+  const selectedFeatureId = await selectFromOptions(ctx, "Features", section.features.map((feature) => ({
+    label: `${feature.title} (${feature.status})`,
+    value: feature.id,
+  })));
+  if (!selectedFeatureId) {
+    return;
+  }
+
+  const feature = section.features.find((item) => item.id === selectedFeatureId);
+  if (!feature) {
+    return;
+  }
+
+  const selectedTaskId = await selectFromOptions(ctx, "Tasks", feature.tasks.map((task) => ({
+    label: formatTaskSummary(task),
+    value: task.id,
+  })));
+  if (!selectedTaskId) {
+    return;
+  }
+
+  const task = feature.tasks.find((item) => item.id === selectedTaskId);
+  if (!task) {
+    return;
+  }
+
+  const actionOptions = [
+    { label: "View", value: "view" },
+    { label: "Mark in progress", value: "in_progress" },
+    { label: "Mark blocked", value: "blocked" },
+    { label: "Mark done", value: "done" },
+    ...(task.assignee === "agent" ? [{ label: "Create linked todo", value: "linked-todo" }] : []),
+    ...(task.assignee === "agent" ? [{ label: "Work on task", value: "work" }] : []),
+  ];
+  const selectedAction = await selectFromOptions(ctx, "Task Action", actionOptions);
+  if (!selectedAction) {
+    return;
+  }
+
+  if (selectedAction === "view") {
+    ctx.ui.notify([
+      `${task.title}`,
+      `status: ${task.status}`,
+      `assignee: ${task.assignee}`,
+      `type: ${task.type}`,
+      ...(task.summary ? [`summary: ${task.summary}`] : []),
+      `linkedTodos: ${task.linkedTodoCount}`,
+    ].join("\n"), "info");
+    return;
+  }
+
+  if (selectedAction === "linked-todo") {
+    const linkedTodo = await runCliJson<{ id: string }>(environment, [
+      "project-plan",
+      "create-linked-todo",
+      "--taskId",
+      task.id,
+    ], ctx.cwd);
+    ctx.ui.notify(`Created linked todo ${linkedTodo.id} for ${task.id}`, "info");
+    return;
+  }
+
+  if (selectedAction === "work") {
+    if (task.linkedTodoCount === 0) {
+      try {
+        await runCliJson(environment, [
+          "project-plan",
+          "create-linked-todo",
+          "--taskId",
+          task.id,
+        ], ctx.cwd);
+      }
+      catch (error) {
+        ctx.ui.notify(error instanceof Error ? error.message : String(error), "warning");
+      }
+    }
+    ctx.ui.setEditorText(`work on task ${task.id} "${task.title}"`);
+    return;
+  }
+
+  await runCliJson(environment, [
+    "project-plan",
+    "set-task-status",
+    "--taskId",
+    task.id,
+    "--status",
+    selectedAction,
+  ], ctx.cwd);
+  ctx.ui.notify(`Updated ${task.id} to ${selectedAction}`, "info");
+}
+
+export default function tasksExtension(pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "project_task",
+    label: "Project Task",
+    description: "Manage the canonical repo-tracked project-plan graph and linked local subtasks.",
+    parameters: TaskParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const environment = readCliEnvironment();
+      const action = params.action as ITasksAction;
+
+      switch (action) {
+        case "show": {
+          const payload = await runCliJson<IProjectPlanShowPayload>(environment, ["project-plan", "show"], ctx.cwd);
+          const text = formatHierarchySummary(payload);
+          return {
+            content: [{ type: "text", text }],
+            details: payload,
+          };
+        }
+
+        case "get": {
+          if (!params.taskId) {
+            return {
+              content: [{ type: "text", text: "taskId required" }],
+              isError: true,
+            };
+          }
+          const payload = await runCliJson<Record<string, unknown>>(environment, [
+            "project-plan",
+            "get-task",
+            "--taskId",
+            String(params.taskId),
+          ], ctx.cwd);
+          return {
+            content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+            details: payload,
+          };
+        }
+
+        case "create-feature": {
+          if (!params.sectionId || !params.title) {
+            return {
+              content: [{ type: "text", text: "sectionId and title required" }],
+              isError: true,
+            };
+          }
+          const args = [
+            "project-plan",
+            "upsert-feature",
+            "--sectionId",
+            String(params.sectionId),
+            "--title",
+            String(params.title),
+          ];
+          if (params.slug) {
+            args.push("--slug", String(params.slug));
+          }
+          if (params.summary) {
+            args.push("--summary", String(params.summary));
+          }
+          const payload = await runCliJson<Record<string, unknown>>(environment, args, ctx.cwd);
+          return {
+            content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+            details: payload,
+          };
+        }
+
+        case "create-task": {
+          if (!params.featureId || !params.title || !params.type || !params.assignee) {
+            return {
+              content: [{ type: "text", text: "featureId, title, type, and assignee required" }],
+              isError: true,
+            };
+          }
+          const args = [
+            "project-plan",
+            "upsert-task",
+            "--featureId",
+            String(params.featureId),
+            "--title",
+            String(params.title),
+            "--type",
+            String(params.type),
+            "--assignee",
+            String(params.assignee),
+          ];
+          if (params.sectionId) {
+            args.push("--sectionId", String(params.sectionId));
+          }
+          if (params.summary) {
+            args.push("--summary", String(params.summary));
+          }
+          if (params.status) {
+            args.push("--status", String(params.status));
+          }
+          if (Array.isArray(params.acceptanceCriteria) && params.acceptanceCriteria.length > 0) {
+            args.push("--acceptanceCriteria", JSON.stringify(params.acceptanceCriteria));
+          }
+          const payload = await runCliJson<Record<string, unknown>>(environment, args, ctx.cwd);
+          return {
+            content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+            details: payload,
+          };
+        }
+
+        case "set-status": {
+          if (!params.taskId || !params.status) {
+            return {
+              content: [{ type: "text", text: "taskId and status required" }],
+              isError: true,
+            };
+          }
+          const payload = await runCliJson<Record<string, unknown>>(environment, [
+            "project-plan",
+            "set-task-status",
+            "--taskId",
+            String(params.taskId),
+            "--status",
+            String(params.status),
+          ], ctx.cwd);
+          return {
+            content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+            details: payload,
+          };
+        }
+
+        case "create-linked-todo": {
+          if (!params.taskId) {
+            return {
+              content: [{ type: "text", text: "taskId required" }],
+              isError: true,
+            };
+          }
+          const args = [
+            "project-plan",
+            "create-linked-todo",
+            "--taskId",
+            String(params.taskId),
+          ];
+          if (params.title) {
+            args.push("--title", String(params.title));
+          }
+          if (params.summary) {
+            args.push("--body", String(params.summary));
+          }
+          const payload = await runCliJson<Record<string, unknown>>(environment, args, ctx.cwd);
+          return {
+            content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+            details: payload,
+          };
+        }
+      }
+    },
+    renderCall(args, theme: Theme) {
+      return new Text(
+        `${theme.fg("toolTitle", theme.bold("project task "))}${theme.fg("muted", String(args.action || "show"))}`,
+        0,
+        0,
+      );
+    },
+    renderResult(result, _options, _theme) {
+      const text = result.content[0];
+      return new Text(text?.type === "text" ? text.text : "", 0, 0);
+    },
+  });
+
+  pi.registerCommand("tasks", {
+    description: "Browse project-plan sections, features, and tasks",
+    handler: async(args, ctx) => {
+      await tasksCommandHandler(pi, ctx, args);
+    },
+  });
+}