pi-deck 0.1.5 → 0.1.6

package/README.md

@@ -95,6 +95,41 @@ The script will: check for a clean working tree on `main`, bump the version in a
 
 The published package includes a bundled server (`dist/server.js`) and the pre-built client SPA (`packages/client/dist/`). Workspace dependencies are inlined by esbuild; only runtime dependencies (`express`, `better-sqlite3`, etc.) are installed by npm.
 
+## Job Management
+
+Pi-deck integrates with Pi's job management system. Jobs are markdown files with YAML frontmatter that track work through phases (backlog → planning → ready → executing → review → complete).
+
+### Configurable Job Locations
+
+By default, jobs are stored in two locations:
+- `~/.pi/agent/jobs/<workspace-name>/` (primary)
+- `<workspace>/.pi/jobs/` (local)
+
+You can configure custom job directories by creating a `.pi/jobs.json` file in your workspace root:
+
+```json
+{
+  "locations": [
+    "~/.pi/agent/jobs/pi-deck",
+    ".pi/jobs",
+    "./custom-jobs-folder",
+    "/absolute/path/to/jobs"
+  ],
+  "defaultLocation": "~/.pi/agent/jobs/pi-deck"
+}
+```
+
+**Configuration options:**
+- `locations` (required): Array of directory paths to scan for jobs. Supports:
+  - Relative paths (resolved from workspace root): `"./jobs"`, `".pi/jobs"`
+  - Absolute paths: `"/Users/you/projects/jobs"`
+  - Home directory expansion: `"~/.pi/agent/jobs"`
+- `defaultLocation` (optional): Where new jobs are created. If not specified, uses the first location in `locations`.
+
+The configuration file is optional — without it, the default two-location behavior is preserved for backward compatibility.
+
+See `.pi/jobs.json.example` for a template.
+
 ## Configuration
 
 Create a config file at `~/.config/pi-deck/config.json`:

package/dist/server.js

@@ -254,13 +254,16 @@ __export(job_service_exports, {
   extractReviewSection: () => extractReviewSection,
   getActiveJobStates: () => getActiveJobStates,
   getJobDirectories: () => getJobDirectories,
+  getJobLocations: () => getJobLocations,
   getNextPhase: () => getNextPhase,
   getPreviousPhase: () => getPreviousPhase,
+  loadJobConfig: () => loadJobConfig,
   parseJob: () => parseJob,
   parseJobFrontmatter: () => parseJobFrontmatter,
   parseTasks: () => parseTasks,
   promoteJob: () => promoteJob,
   readJob: () => readJob,
+  resolveLocationPath: () => resolveLocationPath,
   setJobSessionId: () => setJobSessionId,
   unarchiveJob: () => unarchiveJob,
   updateJobFrontmatter: () => updateJobFrontmatter,
@@ -271,6 +274,52 @@ import { existsSync as existsSync4, readFileSync as readFileSync3, writeFileSync
 import { join as join4, basename as basename2, resolve as resolve3, dirname as dirname2 } from "path";
 import { homedir as homedir4 } from "os";
 import YAML from "yaml";
+function loadJobConfig(workspacePath) {
+  const configPath = join4(workspacePath, ".pi", "jobs.json");
+  if (!existsSync4(configPath)) {
+    return null;
+  }
+  try {
+    const rawContent = readFileSync3(configPath, "utf-8");
+    const parsed = JSON.parse(rawContent);
+    if (typeof parsed !== "object" || parsed === null) {
+      throw new Error("Configuration must be a JSON object");
+    }
+    if (!Array.isArray(parsed.locations) || parsed.locations.length === 0) {
+      throw new Error('Configuration must have a non-empty "locations" array');
+    }
+    for (const loc of parsed.locations) {
+      if (typeof loc !== "string") {
+        throw new Error(`Location must be a string, got ${typeof loc}`);
+      }
+    }
+    if (parsed.defaultLocation !== void 0 && typeof parsed.defaultLocation !== "string") {
+      throw new Error(`defaultLocation must be a string, got ${typeof parsed.defaultLocation}`);
+    }
+    return {
+      locations: parsed.locations,
+      defaultLocation: parsed.defaultLocation
+    };
+  } catch (err) {
+    if (err instanceof SyntaxError) {
+      throw new Error(`Failed to parse ${configPath}: Invalid JSON`);
+    }
+    throw err;
+  }
+}
+function resolveLocationPath(location, workspacePath) {
+  if (typeof location !== "string") {
+    throw new Error(`Location must be a string, got ${typeof location}`);
+  }
+  let path = location;
+  if (path.startsWith("~/") || path === "~") {
+    path = join4(homedir4(), path.slice(1));
+  }
+  if (!path.startsWith("/")) {
+    path = resolve3(workspacePath, path);
+  }
+  return path;
+}
 function statusToPhase(status) {
   switch (status) {
     case "draft":
@@ -434,6 +483,20 @@ function updateTaskInContent2(content, lineNumber, done) {
   return lines.join("\n");
 }
 function getJobDirectories(workspacePath) {
+  try {
+    const config2 = loadJobConfig(workspacePath);
+    if (config2) {
+      return config2.locations.map((loc) => {
+        const resolvedPath = resolveLocationPath(loc, workspacePath);
+        if (!existsSync4(resolvedPath)) {
+          console.warn(`[JobService] Configured job directory does not exist: ${resolvedPath}`);
+        }
+        return resolvedPath;
+      });
+    }
+  } catch (err) {
+    console.warn(`[JobService] Failed to load job configuration: ${err instanceof Error ? err.message : String(err)}`);
+  }
   const workspaceName = basename2(workspacePath);
   const dirs = [];
   dirs.push(join4(homedir4(), ".pi", "agent", "jobs", workspaceName));
@@ -490,11 +553,53 @@ function writeJob(jobPath, content) {
   writeFileSync2(jobPath, content, "utf-8");
   return parseJob(jobPath, content);
 }
-function createJob(workspacePath, title, description, tags) {
-  const workspaceName = basename2(workspacePath);
-  const jobsDir = join4(homedir4(), ".pi", "agent", "jobs", workspaceName);
-  if (!existsSync4(jobsDir)) {
-    mkdirSync(jobsDir, { recursive: true });
+function createJob(workspacePath, title, description, tags, location) {
+  let config2 = null;
+  let jobsDir;
+  try {
+    config2 = loadJobConfig(workspacePath);
+    if (location) {
+      if (config2) {
+        const resolvedLocation = resolveLocationPath(location, workspacePath);
+        const availableLocations = config2.locations.map((loc) => resolveLocationPath(loc, workspacePath));
+        if (availableLocations.includes(resolvedLocation)) {
+          jobsDir = resolvedLocation;
+        } else {
+          throw new Error(`Location "${location}" is not in the configured job locations`);
+        }
+      } else {
+        const defaultLocs = [
+          join4(homedir4(), ".pi", "agent", "jobs", basename2(workspacePath)),
+          join4(workspacePath, ".pi", "jobs")
+        ];
+        if (defaultLocs.includes(location)) {
+          jobsDir = location;
+        } else {
+          throw new Error(`Location "${location}" is not available (no custom config)`);
+        }
+      }
+    } else if (config2 && config2.defaultLocation) {
+      jobsDir = resolveLocationPath(config2.defaultLocation, workspacePath);
+    } else if (config2 && config2.locations.length > 0) {
+      jobsDir = resolveLocationPath(config2.locations[0], workspacePath);
+    } else {
+      const workspaceName = basename2(workspacePath);
+      jobsDir = join4(homedir4(), ".pi", "agent", "jobs", workspaceName);
+    }
+  } catch (err) {
+    if (err instanceof Error && err.message.includes("not available")) {
+      throw err;
+    }
+    console.warn(`[JobService] Failed to load job config for createJob: ${err instanceof Error ? err.message : String(err)}`);
+    const workspaceName = basename2(workspacePath);
+    jobsDir = join4(homedir4(), ".pi", "agent", "jobs", workspaceName);
+  }
+  try {
+    if (!existsSync4(jobsDir)) {
+      mkdirSync(jobsDir, { recursive: true });
+    }
+  } catch (err) {
+    throw new Error(`Failed to create job directory at ${jobsDir}: ${err instanceof Error ? err.message : String(err)}`);
   }
   const now = /* @__PURE__ */ new Date();
   const dateStr = now.toISOString().slice(0, 10).replace(/-/g, "");
@@ -623,14 +728,22 @@ function discoverArchivedJobs(workspacePath) {
 }
 function buildJobSystemContext(workspacePath) {
   const dirs = getJobDirectories(workspacePath);
+  const config2 = loadJobConfig(workspacePath);
   const primaryDir = dirs[0];
   const jobs = discoverJobs(workspacePath);
   const jobLines = jobs.map((j) => `  - [${j.phase}] "${j.title}" \u2192 ${j.path}`).join("\n");
   const jobListing = jobs.length > 0 ? `
 Current jobs:
 ${jobLines}` : "\nNo jobs exist yet.";
+  const dirListing = dirs.map((d) => `  - ${d}`).join("\n");
   return `<job_system>
-You have access to a job management system. Jobs are markdown files with YAML frontmatter stored in: ${primaryDir}
+You have access to a job management system. Jobs are markdown files with YAML frontmatter.
+
+## Job Locations
+Jobs are stored in the following directories:
+${dirListing}
+
+${config2 ? `Configuration loaded from: .pi/jobs.json` : "Using default job locations (no .pi/jobs.json config)"}
 
 ## Job File Format
 \`\`\`markdown
@@ -660,7 +773,7 @@ What needs to be done.
 
 ## Managing Jobs
 - **Create a job**: Write a new .md file to ${primaryDir} with the frontmatter format above. Use filename format: YYYYMMDD-slug.md
-- **List jobs**: Read files from ${primaryDir}
+- **List jobs**: Read files from any of the job directories
 - **Update phase**: Edit the \`phase\` field in frontmatter. Update \`updated\` timestamp.
 - **Check off tasks**: Change \`- [ ]\` to \`- [x]\` in the job file.
 - **Complete a job**: Set phase to "complete" and add \`completedAt\` to frontmatter.
@@ -675,7 +788,19 @@ function buildPlanningPrompt(jobPath) {
   return `<active_job phase="planning">
 You have a job to plan at: ${jobPath}
 Read the job file. It contains a title and description.
+
+Before creating the plan, you MUST:
+1. Explore the codebase to understand the current implementation
+2. Search for relevant files, functions, and existing patterns
+3. Read documentation and configuration files as needed
+4. Gather context about the architecture and conventions used
+
+Do this research yourself \u2014 DO NOT include research or exploration tasks in the plan. The plan should only contain concrete implementation steps that will be performed after planning is complete.
+
 Your goal is to create a detailed implementation plan. Ask the user clarifying questions if needed, then write a concrete plan with \`- [ ]\` checkbox tasks back into the job file under a "## Plan" section.
+
+Plan tasks should be actionable implementation steps only (e.g., "Add function X", "Update file Y"). Do not include research tasks like "review current implementation" \u2014 you should do that during planning, not put it in the plan.
+
 Group tasks under \`### Phase\` headings. Keep tasks concise and actionable (start with a verb).
 When you're done writing the plan, let the user know so they can review and iterate or mark it as ready.
 </active_job>`;
@@ -699,6 +824,24 @@ function extractReviewSection(content) {
   const trimmed = sectionText.trim();
   return trimmed.length > 0 ? trimmed : null;
 }
+function getJobLocations(workspacePath) {
+  const config2 = loadJobConfig(workspacePath);
+  const dirs = getJobDirectories(workspacePath);
+  let defaultDir;
+  if (config2 && config2.defaultLocation) {
+    defaultDir = resolveLocationPath(config2.defaultLocation, workspacePath);
+  } else if (config2 && config2.locations.length > 0) {
+    defaultDir = resolveLocationPath(config2.locations[0], workspacePath);
+  } else {
+    defaultDir = dirs[0];
+  }
+  return dirs.map((dir) => ({
+    path: dir,
+    isDefault: dir === defaultDir,
+    displayName: dir.startsWith(workspacePath) ? `.${dir.slice(workspacePath.length)}` : dir.replace(homedir4(), "~")
+    // Replace home directory with ~
+  }));
+}
 function buildReviewPrompt(jobPath) {
   const content = readFileSync3(jobPath, "utf-8");
   const reviewSection = extractReviewSection(content);
@@ -1901,7 +2044,9 @@ var PiSession = class extends EventEmitter {
         cacheRead: msg.usage.cacheRead || 0,
         cacheWrite: msg.usage.cacheWrite || 0,
         total: (msg.usage.input || 0) + (msg.usage.output || 0)
-      } : void 0
+      } : void 0,
+      stopReason: msg.stopReason,
+      errorMessage: msg.errorMessage
     };
   }
   convertContent(content) {
@@ -6863,6 +7008,28 @@ Please read the plan file and begin working through the tasks.`;
       syncIntegration.setJobs(message.workspaceId, jobs);
       break;
     }
+    case "getJobLocations": {
+      const workspace = workspaceManager2.getWorkspace(message.workspaceId);
+      if (!workspace)
+        break;
+      try {
+        const locations = getJobLocations(workspace.path);
+        const defaultLocation = locations.find((l) => l.isDefault)?.path || locations[0]?.path;
+        send(ws, {
+          type: "jobLocations",
+          workspaceId: message.workspaceId,
+          locations,
+          defaultLocation
+        });
+      } catch (err) {
+        send(ws, {
+          type: "error",
+          message: `Failed to get job locations: ${err instanceof Error ? err.message : "Unknown error"}`,
+          workspaceId: message.workspaceId
+        });
+      }
+      break;
+    }
     case "getJobContent": {
       const workspace = workspaceManager2.getWorkspace(message.workspaceId);
       if (!workspace)
@@ -6890,7 +7057,7 @@ Please read the plan file and begin working through the tasks.`;
       if (!workspace)
         break;
       try {
-        const { path: jobPath, job } = createJob(workspace.path, message.title, message.description, message.tags);
+        const { path: jobPath, job } = createJob(workspace.path, message.title, message.description, message.tags, message.location);
         broadcastToWorkspace(message.workspaceId, {
           type: "jobSaved",
           workspaceId: message.workspaceId,