@brainervirus/workit-core 0.6.0 → 0.6.1

package/src/tools/sdd.ts

@@ -5,15 +5,12 @@ import { fail, ok, resolveGitRevision, resolveInside } from "../core";
 import { resolveBranch, docsBranch } from "../core/branch";
 import { docsValidate } from "../core/docs-validate";
 import { parsePlanTasks, resolveHandoffBranch } from "../core/plan-tasks";
-import {
-  sddAppendProgress, sddContext, sddReviewPackage, sddTaskBrief,
-} from "../core/sdd";
+import { sddAppendProgress, sddContext, sddReviewPackage, sddTaskBrief } from "../core/sdd";
 import { WorkflowStateStore } from "../state";
 
 const output = (value: unknown) => JSON.stringify(value, null, 2);
-const requireConfirmed = (confirmed: boolean) => confirmed === true
-  ? null
-  : output(fail("confirmed: true required"));
+const requireConfirmed = (confirmed: boolean) =>
+  confirmed === true ? null : output(fail("confirmed: true required"));
 
 const relativePath = (root: string, candidate: string) => {
   if (path.isAbsolute(candidate)) throw new Error("path must be repository-relative");
@@ -49,89 +46,109 @@ const planPaths = (root: string, planPath: string, suppliedSpecPath?: string) =>
 };
 
 export function createSddTools(state: WorkflowStateStore) {
-  const record = (context: ToolContext, data: Record<string, unknown>) => state.set(context.sessionID, {
-    spec: String(data.spec_path ?? ""),
-    plan: String(data.plan_path ?? ""),
-    sdd: String(data.sdd_dir ?? ""),
-  });
+  const record = (context: ToolContext, data: Record<string, unknown>) =>
+    state.set(context.sessionID, {
+      spec: String(data.spec_path ?? ""),
+      plan: String(data.plan_path ?? ""),
+      sdd: String(data.sdd_dir ?? ""),
+    });
 
   return {
     workflow_docs_branch: tool({
-      description: "Resolve branch for spec/plan authors: keep current feature|bugfix or create from develop",
+      description:
+        "Resolve branch for spec/plan authors: keep current feature|bugfix or create from the configured base",
       args: {
         plan_path: tool.schema.string().optional(),
         kind: tool.schema.enum(["feature", "bugfix"]).optional(),
       },
-      execute: async ({ plan_path, kind }, context) => invoke(() => {
-        if (plan_path) relativePath(context.directory, plan_path);
-        return docsBranch({
-          plan_path,
-          kind,
-          workspace_root: context.directory,
-        }) as Record<string, unknown>;
-      }),
+      execute: async ({ plan_path, kind }, context) =>
+        invoke(() => {
+          if (plan_path) relativePath(context.directory, plan_path);
+          return docsBranch({
+            plan_path,
+            kind,
+            workspace_root: context.directory,
+          }) as Record<string, unknown>;
+        }),
     }),
     workflow_docs_validate: tool({
-      description: "Hard-fail validate spec/plan headers, link, branch, task order; returns quality findings (hard/warning)",
+      description:
+        "Hard-fail validate spec/plan headers, link, branch, task order; returns quality findings (hard/warning)",
       args: {
         spec_path: tool.schema.string(),
         plan_path: tool.schema.string(),
       },
-      execute: async ({ spec_path, plan_path }, context) => invoke(() => {
-        relativePath(context.directory, spec_path);
-        relativePath(context.directory, plan_path);
-        const result = docsValidate({
-          spec_path,
-          plan_path,
-          workspace_root: context.directory,
-        }) as Record<string, unknown>;
-        if (result.error) return result;
-        if (result.ok === false) return result;
-        return result;
-      }),
+      execute: async ({ spec_path, plan_path }, context) =>
+        invoke(() => {
+          relativePath(context.directory, spec_path);
+          relativePath(context.directory, plan_path);
+          const result = docsValidate({
+            spec_path,
+            plan_path,
+            workspace_root: context.directory,
+          }) as Record<string, unknown>;
+          if (result.error) return result;
+          if (result.ok === false) return result;
+          return result;
+        }),
     }),
     workflow_plan_tasks: tool({
       description: "Parse top-level tasks from a workflow plan",
       args: { plan_path: tool.schema.string(), spec_path: tool.schema.string().optional() },
-      execute: async ({ plan_path, spec_path }, context) => invoke(() => {
-        relativePath(context.directory, plan_path);
-        const paths = planPaths(context.directory, plan_path, spec_path);
-        const parsed = parsePlanTasks(plan_path, context.directory) as Record<string, unknown>;
-        if (parsed.error) return parsed;
-        const branch = paths.spec_path
-          ? resolveHandoffBranch(paths.spec_path, plan_path, context.directory) as Record<string, unknown>
-          : {};
-        if (branch.error) return branch;
-        const data = { ...parsed, ...paths, ...branch };
-        record(context, data);
-        return data;
-      }),
+      execute: async ({ plan_path, spec_path }, context) =>
+        invoke(() => {
+          relativePath(context.directory, plan_path);
+          const paths = planPaths(context.directory, plan_path, spec_path);
+          const parsed = parsePlanTasks(plan_path, context.directory) as Record<string, unknown>;
+          if (parsed.error) return parsed;
+          const branch = paths.spec_path
+            ? (resolveHandoffBranch(paths.spec_path, plan_path, context.directory) as Record<
+                string,
+                unknown
+              >)
+            : {};
+          if (branch.error) return branch;
+          const data = { ...parsed, ...paths, ...branch };
+          record(context, data);
+          return data;
+        }),
     }),
     workflow_resolve_branch: tool({
       description: "Resolve a branch from repository spec and plan metadata",
       args: { spec_path: tool.schema.string(), plan_path: tool.schema.string() },
-      execute: async ({ spec_path, plan_path }, context) => invoke(() => {
-        relativePath(context.directory, spec_path);
-        relativePath(context.directory, plan_path);
-        return resolveBranch({ spec_path, plan_path, workspace_root: context.directory });
-      }),
+      execute: async ({ spec_path, plan_path }, context) =>
+        invoke(() => {
+          relativePath(context.directory, spec_path);
+          relativePath(context.directory, plan_path);
+          return resolveBranch({ spec_path, plan_path, workspace_root: context.directory });
+        }),
     }),
     workflow_sdd_context: tool({
       description: "Resolve the SDD workspace and progress ledger",
       args: { plan_path: tool.schema.string() },
-      execute: async ({ plan_path }, context) => invoke(() => {
-        relativePath(context.directory, plan_path);
-        const parsed = sddContext({ slug: undefined, plan_path, workspace_root: context.directory }) as Record<string, unknown>;
-        if (parsed.error) return parsed;
-        const todos = Array.isArray(parsed.todos)
-          ? parsed.todos.map((todo: Record<string, unknown>) => todo.status === "in_progress"
-            ? { ...todo, status: "pending" }
-            : todo)
-          : [];
-        const data = { ...parsed, todos, ...planPaths(context.directory, plan_path), sdd_dir: parsed.sdd_dir };
-        record(context, data);
-        return data;
-      }),
+      execute: async ({ plan_path }, context) =>
+        invoke(() => {
+          relativePath(context.directory, plan_path);
+          const parsed = sddContext({
+            slug: undefined,
+            plan_path,
+            workspace_root: context.directory,
+          }) as Record<string, unknown>;
+          if (parsed.error) return parsed;
+          const todos = Array.isArray(parsed.todos)
+            ? parsed.todos.map((todo: Record<string, unknown>) =>
+                todo.status === "in_progress" ? { ...todo, status: "pending" } : todo,
+              )
+            : [];
+          const data = {
+            ...parsed,
+            todos,
+            ...planPaths(context.directory, plan_path),
+            sdd_dir: parsed.sdd_dir,
+          };
+          record(context, data);
+          return data;
+        }),
     }),
     workflow_sdd_task_brief: tool({
       description: "Write a confirmed task brief",
@@ -146,7 +163,12 @@ export function createSddTools(state: WorkflowStateStore) {
         if (rejected) return rejected;
         return invoke(() => {
           relativePath(context.directory, sdd_dir);
-          return sddTaskBrief({ sdd_dir, task_id, section_text, workspace_root: context.directory });
+          return sddTaskBrief({
+            sdd_dir,
+            task_id,
+            section_text,
+            workspace_root: context.directory,
+          });
         });
       },
     }),
@@ -165,7 +187,12 @@ export function createSddTools(state: WorkflowStateStore) {
           relativePath(context.directory, sdd_dir);
           resolveGitRevision(context.directory, base_sha);
           resolveGitRevision(context.directory, head_sha);
-          return sddReviewPackage({ sdd_dir, base_sha, head_sha, workspace_root: context.directory });
+          return sddReviewPackage({
+            sdd_dir,
+            base_sha,
+            head_sha,
+            workspace_root: context.directory,
+          });
         });
       },
     }),

package/src/tools/youtrack.ts

@@ -17,7 +17,7 @@ import {
 
 const ISSUE_RE = /^[A-Z]+-\d+$/;
 const output = (value: unknown) => JSON.stringify(value, null, 2);
-const message = (error: unknown) => error instanceof Error ? error.message : String(error);
+const message = (error: unknown) => (error instanceof Error ? error.message : String(error));
 
 // Both override names point at the config dir itself, same precedence as
 // src/core/config.ts and scripts/init/status.sh: WORKFLOW_TOOLKIT_CONFIG → WORKFLOW_TOOLKIT_CONFIG_DIR → XDG.
@@ -26,9 +26,9 @@ export const configPath = (env: NodeJS.ProcessEnv = process.env, home = os.homed
   path.join(
     env === process.env
       ? configDir()
-      : env.WORKFLOW_TOOLKIT_CONFIG
-        ?? env.WORKFLOW_TOOLKIT_CONFIG_DIR
-        ?? path.join(env.XDG_CONFIG_HOME || path.join(home, ".config"), "workit"),
+      : (env.WORKFLOW_TOOLKIT_CONFIG ??
+          env.WORKFLOW_TOOLKIT_CONFIG_DIR ??
+          path.join(env.XDG_CONFIG_HOME || path.join(home, ".config"), "workit")),
     "youtrack.json",
   );
 
@@ -37,7 +37,8 @@ export function readCredentials(env: NodeJS.ProcessEnv = process.env, home = os.
   const config = JSON.parse(readFileSync(resolvedConfig, "utf8")) as { tokenFile?: string };
   const tokenFile = config.tokenFile ?? "youtrack.token";
   const tokenPath = path.resolve(path.dirname(resolvedConfig), tokenFile.replace(/^~(?=\/)/, home));
-  if (process.platform !== "win32" && (statSync(tokenPath).mode & 0o777) !== 0o600) throw new Error("youtrack.token mode must be 0600");
+  if (process.platform !== "win32" && (statSync(tokenPath).mode & 0o777) !== 0o600)
+    throw new Error("youtrack.token mode must be 0600");
   const token = readFileSync(tokenPath, "utf8").trim();
   if (!token) throw new Error("youtrack.token is empty");
   return { configPath: resolvedConfig, token };
@@ -69,9 +70,13 @@ const defaultOperations: YouTrackOperations = {
   verifyToken: () => unwrap(verifyYouTrackToken()),
   context: (input) => legacyContext(input as never),
   parseDuration: (text, workspaceRoot) => legacyParseDuration(text, workspaceRoot),
-  postComment: (issueId, markdown, workspaceRoot) => legacyPostUpdate({
-    confirmed: true, issueId, markdown, workspace_root: workspaceRoot,
-  } as never),
+  postComment: (issueId, markdown, workspaceRoot) =>
+    legacyPostUpdate({
+      confirmed: true,
+      issueId,
+      markdown,
+      workspace_root: workspaceRoot,
+    } as never),
   logTime: (input) => legacyLogTime(input as never),
 };
 
@@ -116,15 +121,26 @@ export async function postUpdate(
   if (input.minutes != null && input.minutes <= 0) return fail("minutes must be positive");
 
   try {
-    const comment = await operations.postComment(input.issueId, input.markdown, input.workspace_root);
-    if (notApplied(comment)) return fail(comment.error, {
-      issueId: input.issueId, postedComment: false, loggedMinutes: 0,
-      outcome: "not_applied", retry: "workflow_youtrack_post",
-    });
+    const comment = await operations.postComment(
+      input.issueId,
+      input.markdown,
+      input.workspace_root,
+    );
+    if (notApplied(comment))
+      return fail(comment.error, {
+        issueId: input.issueId,
+        postedComment: false,
+        loggedMinutes: 0,
+        outcome: "not_applied",
+        retry: "workflow_youtrack_post",
+      });
     unwrap(comment);
   } catch (error) {
     return fail(message(error), {
-      issueId: input.issueId, postedComment: false, loggedMinutes: 0, outcome: "unknown",
+      issueId: input.issueId,
+      postedComment: false,
+      loggedMinutes: 0,
+      outcome: "unknown",
       instructions: "Check YouTrack comments manually; do not retry while the outcome is unknown.",
     });
   }
@@ -137,15 +153,23 @@ export async function postUpdate(
         text: "workit update",
         workspace_root: input.workspace_root,
       });
-      if (notApplied(time)) return fail(time.error, {
-        issueId: input.issueId, postedComment: true, loggedMinutes: 0,
-        outcome: "not_applied", retry: "workflow_youtrack_log_time",
-      });
+      if (notApplied(time))
+        return fail(time.error, {
+          issueId: input.issueId,
+          postedComment: true,
+          loggedMinutes: 0,
+          outcome: "not_applied",
+          retry: "workflow_youtrack_log_time",
+        });
       unwrap(time);
     } catch (error) {
       return fail(message(error), {
-        issueId: input.issueId, postedComment: true, loggedMinutes: 0, outcome: "unknown",
-        instructions: "Check YouTrack time entries manually; do not retry while the outcome is unknown.",
+        issueId: input.issueId,
+        postedComment: true,
+        loggedMinutes: 0,
+        outcome: "unknown",
+        instructions:
+          "Check YouTrack time entries manually; do not retry while the outcome is unknown.",
       });
     }
   }
@@ -163,15 +187,21 @@ export async function logTimeUpdate(
 ): Promise<Result<Record<string, unknown>>> {
   try {
     const value = await operation.logTime(input);
-    if (notApplied(value)) return fail(value.error, {
-      issueId: input.issueId, loggedMinutes: 0, outcome: "not_applied",
-      retry: "workflow_youtrack_log_time",
-    });
+    if (notApplied(value))
+      return fail(value.error, {
+        issueId: input.issueId,
+        loggedMinutes: 0,
+        outcome: "not_applied",
+        retry: "workflow_youtrack_log_time",
+      });
     return ok(unwrap(value));
   } catch (error) {
     return fail(message(error), {
-      issueId: input.issueId, loggedMinutes: 0, outcome: "unknown",
-      instructions: "Check YouTrack time entries manually; do not retry while the outcome is unknown.",
+      issueId: input.issueId,
+      loggedMinutes: 0,
+      outcome: "unknown",
+      instructions:
+        "Check YouTrack time entries manually; do not retry while the outcome is unknown.",
     });
   }
 }
@@ -182,10 +212,13 @@ export function normalizeContext(value: LegacyValue, mode?: string): LegacyValue
   const issue = String(config?.meetingIssue || "IRPT-12");
   const { meetingIssues: _meetingIssues, ...singleMeetingConfig } = config ?? {};
   const options = Array.isArray(value.meetingOptions)
-    ? value.meetingOptions as Array<Record<string, unknown>>
+    ? (value.meetingOptions as Array<Record<string, unknown>>)
     : [];
   const selected = options.find((option) => option.issue === issue) ?? {
-    key: "general", issue, label: issue, workItemText: "Reuniones",
+    key: "general",
+    issue,
+    label: issue,
+    workItemText: "Reuniones",
   };
   return {
     ...value,
@@ -220,9 +253,8 @@ const configGap = () => {
   const { missing } = describeConfigGaps(["youtrack_json", "youtrack_token"]);
   return missing.length > 0 ? output(fail(configGuardError(missing))) : null;
 };
-const requireConfirmed = (confirmed: boolean) => confirmed === true
-  ? null
-  : output(fail("confirmed: true required"));
+const requireConfirmed = (confirmed: boolean) =>
+  confirmed === true ? null : output(fail("confirmed: true required"));
 
 const rejectedTimeInput = (issueId: string, minutes: number) => {
   const error = !ISSUE_RE.test(issueId)
@@ -230,11 +262,17 @@ const rejectedTimeInput = (issueId: string, minutes: number) => {
     : !Number.isFinite(minutes) || minutes <= 0
       ? "minutes must be positive"
       : null;
-  return error ? output(fail(error, {
-    issueId, loggedMinutes: 0, outcome: "not_applied",
-    retry: "workflow_youtrack_log_time",
-    instructions: "Correct the invalid input, then retry workflow_youtrack_log_time once.",
-  })) : null;
+  return error
+    ? output(
+        fail(error, {
+          issueId,
+          loggedMinutes: 0,
+          outcome: "not_applied",
+          retry: "workflow_youtrack_log_time",
+          instructions: "Correct the invalid input, then retry workflow_youtrack_log_time once.",
+        }),
+      )
+    : null;
 };
 
 export function createYouTrackTools(operations: YouTrackOperations = defaultOperations) {
@@ -244,7 +282,9 @@ export function createYouTrackTools(operations: YouTrackOperations = defaultOper
       args: {},
       execute: async () => {
         let token = "";
-        try { token = credentials().token; } catch (error) {
+        try {
+          token = credentials().token;
+        } catch (error) {
           const gap = configGap();
           if (gap) return gap;
           return output(fail(message(error)));
@@ -258,7 +298,8 @@ export function createYouTrackTools(operations: YouTrackOperations = defaultOper
       execute: async ({ issue_ref }) => invoke(() => parseIssueRef(issue_ref)),
     }),
     workflow_youtrack_context: tool({
-      description: "Load YouTrack context for the configured meeting issue or an existing task issue",
+      description:
+        "Load YouTrack context for the configured meeting issue or an existing task issue",
       args: {
         mode: tool.schema.enum(["meetings", "task"]).optional(),
         issue_id: tool.schema.string().optional(),
@@ -275,23 +316,37 @@ export function createYouTrackTools(operations: YouTrackOperations = defaultOper
           }
         } catch (error) {
           const detail = message(error);
-          return output(fail(detail.includes("repository-relative") ? detail : `path must be repository-relative: ${detail}`));
+          return output(
+            fail(
+              detail.includes("repository-relative")
+                ? detail
+                : `path must be repository-relative: ${detail}`,
+            ),
+          );
         }
         let token = "";
-        try { token = credentials().token; } catch (error) {
+        try {
+          token = credentials().token;
+        } catch (error) {
           const gap = configGap();
           if (gap) return gap;
           return output(fail(message(error)));
         }
-        return invoke(async () => normalizeContext(
-          await operations.context({ ...input, workspace_root: context.directory }), input.mode,
-        ), token);
+        return invoke(
+          async () =>
+            normalizeContext(
+              await operations.context({ ...input, workspace_root: context.directory }),
+              input.mode,
+            ),
+          token,
+        );
       },
     }),
     workflow_youtrack_parse_duration: tool({
       description: "Parse duration text into integer minutes",
       args: { text: tool.schema.string() },
-      execute: async ({ text }, context) => invoke(() => operations.parseDuration(text, context.directory)),
+      execute: async ({ text }, context) =>
+        invoke(() => operations.parseDuration(text, context.directory)),
     }),
     workflow_youtrack_draft: tool({
       description: "Build an es-CL update comment without posting it",
@@ -302,10 +357,12 @@ export function createYouTrackTools(operations: YouTrackOperations = defaultOper
         projectName: tool.schema.string().optional(),
         includeProjectOpener: tool.schema.boolean().optional(),
         includeFacts: tool.schema.boolean().optional(),
-        facts: tool.schema.object({
-          progress_excerpt: tool.schema.array(tool.schema.string()).optional(),
-          git_commits: tool.schema.array(tool.schema.string()).optional(),
-        }).optional(),
+        facts: tool.schema
+          .object({
+            progress_excerpt: tool.schema.array(tool.schema.string()).optional(),
+            git_commits: tool.schema.array(tool.schema.string()).optional(),
+          })
+          .optional(),
       },
       execute: async (input) => invoke(() => legacyBuildDraft(input as never)),
     }),
@@ -324,13 +381,16 @@ export function createYouTrackTools(operations: YouTrackOperations = defaultOper
         const invalid = rejectedTimeInput(input.issueId, input.minutes);
         if (invalid) return invalid;
         let token = "";
-        try { token = credentials().token; } catch (error) {
+        try {
+          token = credentials().token;
+        } catch (error) {
           const gap = configGap();
           if (gap) return gap;
           return output(fail(message(error)));
         }
         const result = await withWriteFlag(() =>
-          logTimeUpdate({ ...input, workspace_root: context.directory }, operations));
+          logTimeUpdate({ ...input, workspace_root: context.directory }, operations),
+        );
         return output(result.ok ? result : { ...result, error: redact(result.error, token) });
       },
     }),
@@ -346,13 +406,16 @@ export function createYouTrackTools(operations: YouTrackOperations = defaultOper
         const rejected = requireConfirmed(input.confirmed);
         if (rejected) return rejected;
         let token = "";
-        try { token = credentials().token; } catch (error) {
+        try {
+          token = credentials().token;
+        } catch (error) {
           const gap = configGap();
           if (gap) return gap;
           return output(fail(message(error)));
         }
         const result = await withWriteFlag(() =>
-          postUpdate({ ...input, workspace_root: context.directory }, operations));
+          postUpdate({ ...input, workspace_root: context.directory }, operations),
+        );
         return output(result.ok ? result : { ...result, error: redact(result.error, token) });
       },
     }),

package/templates/superpowers-doc-contract.md

@@ -27,7 +27,7 @@ Plans require:
 
 `bugfix/<slug>` is also valid. Never use `main`, `develop`, `master`, or `prod`. Use plain backtick paths. Top-level headings are exactly `### Task N: Title`; steps use `- [ ] **Step N:** ...`; task headings never appear inside fences.
 
-Before writing **Branch:** into a new spec or plan, call `workflow_docs_branch` and write the returned `branch` verbatim. When `action` is `keep`, use the current feature/bugfix branch. When `action` is `create_from_develop`, create the branch only through `workflow_branch_setup` (never branch from `main`/`master`).
+Before writing **Branch:** into a new spec or plan, call `workflow_docs_branch` and write the returned `branch` verbatim. When `action` is `keep`, use the current feature/bugfix branch. When `action` is `create_from_develop` or `create_from_base`, create the branch only through `workflow_branch_setup`; it uses the configured workspace/global target branch.
 
 ## Execution and handoff