@pstdio/sdk 0.2.1 → 0.3.0

package/dist/plugins/helpers/index.d.ts

@@ -7,6 +7,7 @@ export { followupSession } from "./followup-session";
 export { getAttemptsForTicket } from "./get-attempts-for-ticket";
 export { removeAllWorktreesForTicket } from "./remove-all-worktrees-for-ticket";
 export { runCommand } from "./run-command";
+export { type SaveTicketInput, type SaveTicketResult, saveTicket } from "./save-ticket";
 export { setTicketStatus } from "./set-ticket-status";
 export { setWorkspaceAttemptStatus } from "./set-workspace-attempt-status";
 export { type PullTicketsInput, type PullTicketsResult, pullTickets } from "./ticket-pull";

package/dist/plugins/helpers/save-ticket.d.ts

@@ -0,0 +1,14 @@
+import type { PluginHelperContext } from "./context";
+type SaveTicketInput = {
+    rootPath: string;
+    ticketId?: string;
+    status?: string;
+    tags?: string[];
+    log?: (message: string) => void;
+};
+type SaveTicketResult = {
+    ticketShorthand: string;
+    uploadedFileCount: number;
+};
+export declare const saveTicket: (ctx: PluginHelperContext, input: SaveTicketInput) => Promise<SaveTicketResult>;
+export type { SaveTicketInput, SaveTicketResult };

package/dist/plugins/index.d.ts

@@ -1,5 +1,5 @@
 export { renderPrompt } from "../prompts";
 export { definePlugin } from "./define-plugin";
-export { bootstrapWorktree, createAttempt, createSession, createWorkspace, findTicketByRef, findWorkspaceByRef, followupSession, getAttemptsForTicket, type PullTicketsInput, type PullTicketsResult, pullTickets, removeAllWorktreesForTicket, runCommand, setTicketStatus, setWorkspaceAttemptStatus, updateTicketWhenAllAttemptsMatch, workspacesForTicket, } from "./helpers";
+export { bootstrapWorktree, createAttempt, createSession, createWorkspace, findTicketByRef, findWorkspaceByRef, followupSession, getAttemptsForTicket, type PullTicketsInput, type PullTicketsResult, pullTickets, removeAllWorktreesForTicket, runCommand, type SaveTicketInput, type SaveTicketResult, saveTicket, setTicketStatus, setWorkspaceAttemptStatus, updateTicketWhenAllAttemptsMatch, workspacesForTicket, } from "./helpers";
 export type { HookResponse, PluginHooks, PostHookReturn, PostPluginHooks, PreHookReturn, PrePluginHooks, } from "./hooks";
-export type { ActionDefinition, ActionDescriptor, ActionInput, ActionParamDef, ActionParamValue, ActionPlacement, ActionTargetMap, ActionTriggerContext, ActionTriggerResult, AgentActionParam, AgentParamValue, LongTextActionParam, PluginDefinition, RepoActionParam, RepoParamValue, SelectActionParam, TargetType, TemplateSelectActionParam, TextActionParam, } from "./types";
+export type { ActionDefinition, ActionDescriptor, ActionInput, ActionParamDef, ActionParamValue, ActionPlacement, ActionTargetMap, ActionTriggerContext, ActionTriggerResult, AgentActionParam, AgentParamValue, LongTextActionParam, PluginDefinition, RepoActionParam, RepoParamValue, ScheduleDefinition, ScheduledTriggerContext, SelectActionParam, TargetType, TemplateSelectActionParam, TextActionParam, } from "./types";

package/dist/plugins/index.js

@@ -9,8 +9,16 @@ var assertActionTriggers = (plugin) => {
     }
   }
 };
+var assertScheduleHandlers = (plugin) => {
+  for (const schedule of plugin.schedules ?? []) {
+    if (typeof schedule.handler !== "function") {
+      throw new Error(`Schedule "${schedule.name}" is missing handler(ctx)`);
+    }
+  }
+};
 var definePlugin = (plugin) => {
   assertActionTriggers(plugin);
+  assertScheduleHandlers(plugin);
   return plugin;
 };
 // src/plugins/helpers/context.ts
@@ -177,7 +185,7 @@ var runCommand = async (cwd, command, options = {}) => {
   try {
     proc = Bun.spawn([cmd, ...args], {
       cwd,
-      env: options.env,
+      env: options.env ?? { ...process.env },
       stdin: "ignore",
       stdout: stdio,
       stderr: stdio
@@ -194,6 +202,251 @@ var runCommand = async (cwd, command, options = {}) => {
     stderr: stderr.trim()
   };
 };
+// src/plugins/helpers/save-ticket.ts
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, isAbsolute, join, relative, resolve } from "node:path";
+var TICKETS_DIR = join(".pstdio", "tickets");
+var TICKET_FILES_DIR = "files";
+var TICKET_ARTIFACTS_DIR = "artifacts";
+var MAX_DISPLAY_TITLE_LENGTH = 50;
+var ACTIONABLE_FRONTMATTER_KEYS = ["blocked_reason", "parent_id", "status"];
+var resolveTicketDir = (rootPath, shorthand) => {
+  const exactDir = join(rootPath, TICKETS_DIR, shorthand);
+  if (!existsSync(exactDir))
+    return null;
+  if (!statSync(exactDir).isDirectory()) {
+    throw new Error(`Invalid ticket path for ${shorthand}: .pstdio/tickets/${shorthand} is not a directory.`);
+  }
+  return exactDir;
+};
+var readTicketFile = (rootPath, shorthand) => {
+  const dir = resolveTicketDir(rootPath, shorthand);
+  if (!dir)
+    return null;
+  const filePath = join(dir, "ticket.md");
+  if (!existsSync(filePath))
+    return null;
+  return readFileSync(filePath, "utf8");
+};
+var writeTicketFile = (rootPath, shorthand, content) => {
+  const dir = resolveTicketDir(rootPath, shorthand) ?? join(rootPath, TICKETS_DIR, shorthand);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "ticket.md"), content);
+};
+var walkFiles = (baseDir, currentDir, files) => {
+  const entries = readdirSync(currentDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = join(currentDir, entry.name);
+    if (entry.isDirectory()) {
+      walkFiles(baseDir, fullPath, files);
+      continue;
+    }
+    if (!entry.isFile())
+      continue;
+    files.push(relative(baseDir, fullPath).split("\\").join("/"));
+  }
+};
+var listDirFiles = (rootPath, shorthand, subDir) => {
+  const dir = resolveTicketDir(rootPath, shorthand);
+  if (!dir)
+    return [];
+  const baseDir = join(dir, subDir);
+  if (!existsSync(baseDir))
+    return [];
+  const files = [];
+  walkFiles(baseDir, baseDir, files);
+  files.sort();
+  return files;
+};
+var readSafe = (rootPath, shorthand, subDir, requestedPath) => {
+  const ticketDir = resolveTicketDir(rootPath, shorthand);
+  if (!ticketDir)
+    throw new Error(`Ticket directory not found: ${shorthand}`);
+  const baseDir = join(ticketDir, subDir);
+  const target = resolve(baseDir, requestedPath);
+  const rel = relative(baseDir, target);
+  if (isAbsolute(rel) || rel.startsWith("..")) {
+    throw new Error(`Path resolves outside ticket ${subDir} directory: ${requestedPath}`);
+  }
+  return readFileSync(target);
+};
+var findFrontmatterClosingIndex = (content) => {
+  if (!content.startsWith("---"))
+    return -1;
+  return content.indexOf("---", 3);
+};
+var stripFrontmatter = (content) => {
+  const closing = findFrontmatterClosingIndex(content);
+  if (closing === -1)
+    return content;
+  return content.slice(closing + 3);
+};
+var parseFrontmatter = (content) => {
+  const closing = findFrontmatterClosingIndex(content);
+  if (closing === -1)
+    return {};
+  const block = content.slice(3, closing).trim();
+  const result = {};
+  for (const line of block.split(`
+`)) {
+    const colonIndex = line.indexOf(":");
+    if (colonIndex === -1)
+      continue;
+    const key = line.slice(0, colonIndex).trim();
+    const raw = line.slice(colonIndex + 1).trim().replace(/^["']|["']$/g, "");
+    if (!raw)
+      continue;
+    if (ACTIONABLE_FRONTMATTER_KEYS.includes(key)) {
+      result[key] = raw;
+    }
+  }
+  return result;
+};
+var frontmatterLines = (content) => {
+  const closing = findFrontmatterClosingIndex(content);
+  if (closing === -1)
+    return [];
+  const block = content.slice(3, closing).trim();
+  if (!block)
+    return [];
+  return block.split(`
+`);
+};
+var frontmatterKey = (line) => {
+  const colon = line.indexOf(":");
+  if (colon === -1)
+    return null;
+  return line.slice(0, colon).trim();
+};
+var applyFrontmatter = (frontmatter, content) => {
+  const body = stripFrontmatter(content).replace(/^\n+/, "");
+  if (!body)
+    return frontmatter;
+  return `${frontmatter}
+
+${body}`;
+};
+var applyFrontmatterValues = (frontmatter, content) => {
+  if (findFrontmatterClosingIndex(content) === -1)
+    return applyFrontmatter(frontmatter, content);
+  const overrides = new Map;
+  const overrideOrder = [];
+  for (const line of frontmatterLines(frontmatter)) {
+    const key = frontmatterKey(line);
+    if (!key)
+      continue;
+    overrides.set(key, line);
+    overrideOrder.push(key);
+  }
+  const existing = frontmatterLines(content);
+  const merged = existing.map((line) => {
+    const key = frontmatterKey(line);
+    if (!key || !overrides.has(key))
+      return line;
+    return overrides.get(key);
+  });
+  for (const key of overrideOrder) {
+    if (existing.some((line2) => frontmatterKey(line2) === key))
+      continue;
+    const line = overrides.get(key);
+    if (line)
+      merged.push(line);
+  }
+  return applyFrontmatter(["---", ...merged, "---"].join(`
+`), content);
+};
+var markLocalTicketAsSaved = (content) => applyFrontmatterValues(["---", "draft: false", "---"].join(`
+`), content);
+var stripMarkdownFormatting = (text) => text.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/\*\*([^*]*)\*\*/g, "$1").replace(/\*([^*]*)\*/g, "$1").replace(/`([^`]*)`/g, "$1");
+var slugify = (text, maxLength) => text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, maxLength).replace(/-+$/, "");
+var firstHeadingOrLine = (content) => {
+  const lines = content.split(`
+`);
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("# "))
+      return trimmed.slice(2).trim();
+  }
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.length > 0)
+      return trimmed;
+  }
+  return null;
+};
+var extractDisplayTitle = (content) => {
+  const raw = firstHeadingOrLine(stripFrontmatter(content)) ?? "untitled";
+  return slugify(stripMarkdownFormatting(raw), MAX_DISPLAY_TITLE_LENGTH);
+};
+var resolveStatusId = async (ctx, statusName) => {
+  const statuses = await ctx.client.statuses.list(ctx.projectId);
+  const found = statuses.find((status) => status.name === statusName);
+  if (!found)
+    throw new Error(`Status not found: ${statusName}`);
+  return found.id;
+};
+var resolveTagIds = async (ctx, tagNames) => {
+  const tags = await ctx.client.tags.list(ctx.projectId);
+  const options = tags.flatMap((tag) => tag.options);
+  return tagNames.map((name) => {
+    const found = options.find((option) => option.name === name);
+    if (!found)
+      throw new Error(`Tag option not found: ${name}`);
+    return found.id;
+  });
+};
+var saveTicket = async (ctx, input) => {
+  const log = input.log ?? (() => {});
+  const ticket = await findTicketByRef(ctx, { ticketId: input.ticketId });
+  if (!ticket)
+    throw new Error(`Ticket not found: ${input.ticketId ?? "<none>"}`);
+  const shorthand = ticket.shorthand;
+  const content = readTicketFile(input.rootPath, shorthand);
+  if (content === null)
+    throw new Error(`Local ticket not found: .pstdio/tickets/${shorthand}/ticket.md`);
+  const frontmatter = parseFrontmatter(content);
+  const statusName = input.status ?? frontmatter.status;
+  const statusId = statusName ? await resolveStatusId(ctx, statusName) : undefined;
+  const tagIds = input.tags?.length ? await resolveTagIds(ctx, input.tags) : undefined;
+  const body = stripFrontmatter(content).replace(/^\n+/, "");
+  const uploaded = await ctx.client.tickets.uploadFile(ticket.id, {
+    file_name: "ticket.md",
+    content_base64: Buffer.from(body).toString("base64"),
+    mime_type: "text/markdown"
+  });
+  await ctx.client.tickets.update(ticket.id, {
+    blocked_reason: frontmatter.blocked_reason,
+    file_id: uploaded.id,
+    display_title: extractDisplayTitle(body),
+    draft: false,
+    parent_id: frontmatter.parent_id,
+    tag_ids: tagIds,
+    status_id: statusId
+  });
+  let uploadedFileCount = 0;
+  for (const fileName of listDirFiles(input.rootPath, shorthand, TICKET_FILES_DIR)) {
+    const data = readSafe(input.rootPath, shorthand, TICKET_FILES_DIR, fileName);
+    await ctx.client.tickets.uploadFile(ticket.id, {
+      file_name: fileName,
+      content_base64: data.toString("base64")
+    });
+    uploadedFileCount++;
+  }
+  for (const relativePath of listDirFiles(input.rootPath, shorthand, TICKET_ARTIFACTS_DIR)) {
+    const data = readSafe(input.rootPath, shorthand, TICKET_ARTIFACTS_DIR, relativePath);
+    await ctx.client.tickets.uploadFile(ticket.id, {
+      file_name: basename(relativePath),
+      relative_path: relativePath,
+      content_base64: data.toString("base64")
+    });
+    uploadedFileCount++;
+  }
+  writeTicketFile(input.rootPath, shorthand, markLocalTicketAsSaved(content));
+  log(`Saved ticket ${shorthand}`);
+  if (uploadedFileCount > 0)
+    log(`Uploaded ${uploadedFileCount} ticket files`);
+  return { ticketShorthand: shorthand, uploadedFileCount };
+};
 // src/plugins/helpers/set-ticket-status.ts
 var setTicketStatus = async (ctx, input) => {
   const [ticket, statuses] = await Promise.all([
@@ -221,10 +474,10 @@ var setWorkspaceAttemptStatus = async (ctx, input) => {
   return true;
 };
 // src/plugins/helpers/ticket-pull.ts
-import { existsSync, mkdirSync, statSync, writeFileSync } from "node:fs";
-import { dirname, isAbsolute, join, relative, resolve } from "node:path";
-var TICKETS_DIR = join(".pstdio", "tickets");
-var TICKET_FILES_DIR = "files";
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, statSync as statSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { dirname, isAbsolute as isAbsolute2, join as join2, relative as relative2, resolve as resolve2 } from "node:path";
+var TICKETS_DIR2 = join2(".pstdio", "tickets");
+var TICKET_FILES_DIR2 = "files";
 var escapeYamlScalar = (value) => value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\n/g, "\\n");
 var buildTicketFrontmatter = (fields) => {
   const lines = ["---"];
@@ -251,7 +504,7 @@ var buildTicketFrontmatter = (fields) => {
   return lines.join(`
 `);
 };
-var stripFrontmatter = (content) => {
+var stripFrontmatter2 = (content) => {
   if (!content.startsWith("---"))
     return content;
   const closingIndex = content.indexOf("---", 3);
@@ -259,54 +512,54 @@ var stripFrontmatter = (content) => {
     return content;
   return content.slice(closingIndex + 3);
 };
-var applyFrontmatter = (frontmatter, content) => {
-  const body = stripFrontmatter(content).replace(/^\n+/, "");
+var applyFrontmatter2 = (frontmatter, content) => {
+  const body = stripFrontmatter2(content).replace(/^\n+/, "");
   if (!body)
     return frontmatter;
   return `${frontmatter}
 
 ${body}`;
 };
-var toRelativeFilePath = (baseDir, absolutePath) => relative(baseDir, absolutePath).split("\\").join("/");
-var resolveTicketDir = (rootPath, shorthand) => {
-  const exactDir = join(rootPath, TICKETS_DIR, shorthand);
-  if (!existsSync(exactDir))
+var toRelativeFilePath = (baseDir, absolutePath) => relative2(baseDir, absolutePath).split("\\").join("/");
+var resolveTicketDir2 = (rootPath, shorthand) => {
+  const exactDir = join2(rootPath, TICKETS_DIR2, shorthand);
+  if (!existsSync2(exactDir))
     return null;
-  if (!statSync(exactDir).isDirectory()) {
+  if (!statSync2(exactDir).isDirectory()) {
     throw new Error(`Invalid ticket path for ${shorthand}: .pstdio/tickets/${shorthand} is not a directory.`);
   }
   return exactDir;
 };
-var writeTicketFile = (rootPath, shorthand, content, overwrite = true) => {
-  const existingDir = resolveTicketDir(rootPath, shorthand);
-  const dir = existingDir ?? join(rootPath, TICKETS_DIR, shorthand);
-  const filePath = join(dir, "ticket.md");
-  if (!overwrite && existsSync(filePath)) {
+var writeTicketFile2 = (rootPath, shorthand, content, overwrite = true) => {
+  const existingDir = resolveTicketDir2(rootPath, shorthand);
+  const dir = existingDir ?? join2(rootPath, TICKETS_DIR2, shorthand);
+  const filePath = join2(dir, "ticket.md");
+  if (!overwrite && existsSync2(filePath)) {
     throw new Error(`Local file already exists: ${toRelativeFilePath(rootPath, filePath)}. Use force to overwrite.`);
   }
-  mkdirSync(dir, { recursive: true });
-  writeFileSync(filePath, content);
+  mkdirSync2(dir, { recursive: true });
+  writeFileSync2(filePath, content);
   return filePath;
 };
 var resolveTicketAttachmentPath = (rootPath, shorthand, fileName) => {
-  const ticketDir = resolveTicketDir(rootPath, shorthand);
+  const ticketDir = resolveTicketDir2(rootPath, shorthand);
   if (!ticketDir)
     throw new Error(`Ticket directory not found for ${shorthand}`);
-  const filesDir = join(ticketDir, TICKET_FILES_DIR);
-  const targetPath = resolve(filesDir, fileName);
-  const rel = relative(filesDir, targetPath);
-  if (isAbsolute(rel) || rel.startsWith("..")) {
+  const filesDir = join2(ticketDir, TICKET_FILES_DIR2);
+  const targetPath = resolve2(filesDir, fileName);
+  const rel = relative2(filesDir, targetPath);
+  if (isAbsolute2(rel) || rel.startsWith("..")) {
     throw new Error(`Ticket file path resolves outside ticket files directory: ${fileName}`);
   }
   return targetPath;
 };
 var writeTicketAttachment = (rootPath, shorthand, fileName, content, overwrite = false) => {
   const filePath = resolveTicketAttachmentPath(rootPath, shorthand, fileName);
-  if (!overwrite && existsSync(filePath)) {
+  if (!overwrite && existsSync2(filePath)) {
     throw new Error(`Local file already exists: ${toRelativeFilePath(rootPath, filePath)}. Use force to overwrite.`);
   }
-  mkdirSync(dirname(filePath), { recursive: true });
-  writeFileSync(filePath, content);
+  mkdirSync2(dirname(filePath), { recursive: true });
+  writeFileSync2(filePath, content);
   return filePath;
 };
 var isNotFoundError = (error) => typeof error === "object" && error !== null && ("status" in error) && error.status === 404;
@@ -371,8 +624,8 @@ var pullSingleTicket = async (ctx, rootPath, ticketListItem, force, log) => {
     blocked_reason: ticket.blocked_reason,
     tag_names: ticketListItem.tag_names ?? []
   });
-  const content = applyFrontmatter(frontmatter, ticket.content ?? "");
-  const filePath = writeTicketFile(rootPath, ticketListItem.shorthand, content, force);
+  const content = applyFrontmatter2(frontmatter, ticket.content ?? "");
+  const filePath = writeTicketFile2(rootPath, ticketListItem.shorthand, content, force);
   const ticketDir = filePath.replace(/\/ticket\.md$/, "").replace(`${rootPath}/`, "");
   const files = await ctx.client.tickets.listFiles(ticket.id);
   const attachments = files.filter((file) => file.id !== ticket.file_id);
@@ -424,24 +677,24 @@ var updateTicketWhenAllAttemptsMatch = async (ctx, input) => {
   return result.updated;
 };
 // src/plugins/helpers/worktree-bootstrap.ts
-import { cpSync, existsSync as existsSync2, mkdirSync as mkdirSync2 } from "node:fs";
-import { join as join2 } from "node:path";
+import { cpSync, existsSync as existsSync3, mkdirSync as mkdirSync3 } from "node:fs";
+import { join as join3 } from "node:path";
 var AGENT_DIRS = [".claude", ".opencode", ".agents"];
 var bootstrapWorktree = async (ctx, input) => {
   const { repoPath, worktreePath, ticketId } = input;
-  const repoConfig = join2(repoPath, ".pstdio", "config.json");
-  const worktreeConfigDir = join2(worktreePath, ".pstdio");
-  const worktreeConfig = join2(worktreeConfigDir, "config.json");
-  if (existsSync2(repoConfig)) {
-    mkdirSync2(worktreeConfigDir, { recursive: true });
+  const repoConfig = join3(repoPath, ".pstdio", "config.json");
+  const worktreeConfigDir = join3(worktreePath, ".pstdio");
+  const worktreeConfig = join3(worktreeConfigDir, "config.json");
+  if (existsSync3(repoConfig)) {
+    mkdirSync3(worktreeConfigDir, { recursive: true });
     cpSync(repoConfig, worktreeConfig);
   }
   for (const agentDir of AGENT_DIRS) {
-    const fromDir = join2(repoPath, agentDir);
-    const toDir = join2(worktreePath, agentDir);
-    if (!existsSync2(fromDir))
+    const fromDir = join3(repoPath, agentDir);
+    const toDir = join3(worktreePath, agentDir);
+    if (!existsSync3(fromDir))
       continue;
-    mkdirSync2(toDir, { recursive: true });
+    mkdirSync3(toDir, { recursive: true });
     cpSync(fromDir, toDir, { recursive: true });
   }
   if (!ticketId)
@@ -453,6 +706,7 @@ export {
   updateTicketWhenAllAttemptsMatch,
   setWorkspaceAttemptStatus,
   setTicketStatus,
+  saveTicket,
   runCommand,
   renderPrompt,
   removeAllWorktreesForTicket,

package/dist/plugins/types.d.ts

@@ -86,9 +86,27 @@ export type ActionDescriptor = {
 export type ActionDefinition = ActionDescriptor & {
     trigger: ActionTrigger;
 };
+export type ScheduledTriggerContext = {
+    client: PstdioClient;
+    projectId: string;
+    trigger: {
+        type: "schedule";
+    };
+    scheduleName: string;
+    scheduledFor: string;
+    runId: string;
+};
+type ScheduleHandler = (ctx: ScheduledTriggerContext) => void | Promise<void>;
+export type ScheduleDefinition = {
+    name: string;
+    cron: string;
+    timeoutMs?: number;
+    handler: ScheduleHandler;
+};
 export type PluginDefinition = {
     key?: string;
     actions?: ActionInput[];
     hooks?: PluginHooks;
+    schedules?: ScheduleDefinition[];
 };
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pstdio/sdk",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/pufflyai/prompt-studio"