@brainervirus/workit-core 0.6.1 → 0.7.0

package/src/core/logger.ts

@@ -0,0 +1,321 @@
+import { appendFileSync, mkdirSync, readdirSync, unlinkSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// Secret-safe structured logger (DG-01-DG-03, DG-05, DG-10). Host-neutral:
+// node: builtins only. Never logs prompts, messages, content, raw tool
+// arguments/results, credentials, tokens, authorization headers, issue data,
+// URL queries, home prefixes, or unbounded stacks. Every record is bounded,
+// redacted, rate-limited JSONL under a daily filename.
+
+export type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | JsonValue[]
+  | { [key: string]: JsonValue };
+
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+export type LogEvent = {
+  level: LogLevel;
+  time: string;
+  message: string;
+  context: Record<string, JsonValue>;
+};
+
+export type LogSink = (event: LogEvent) => void;
+
+export type LoggerOptions = {
+  stateDir?: string;
+  now?: () => Date;
+  appLog?: LogSink;
+  stderr?: LogSink;
+  maxRate?: number;
+  rateWindowMs?: number;
+  maxFieldLength?: number;
+  maxStackLines?: number;
+};
+
+export type Logger = {
+  debug: (message: string, context?: Record<string, unknown>) => void;
+  info: (message: string, context?: Record<string, unknown>) => void;
+  warn: (message: string, context?: Record<string, unknown>) => void;
+  error: (message: string, context?: Record<string, unknown>) => void;
+  guard: <T>(name: string, fn: () => T) => T | undefined;
+};
+
+export const REDACTED = "[REDACTED]";
+
+const DEFAULT_MAX_RATE = 20;
+const DEFAULT_RATE_WINDOW_MS = 1000;
+const DEFAULT_MAX_FIELD_LENGTH = 200;
+const DEFAULT_MAX_STACK_LINES = 30;
+
+const DAY_FILE = /^workit-\d{4}-\d{2}-\d{2}\.jsonl$/;
+const RETAINED_DAYS = 7;
+
+// Home prefixes, URL queries, and inline secret values are redacted inside any
+// string. Key names drive the rest: a field whose name contains a secret or
+// content word is fully replaced, a stack/trace field is line-bounded.
+const SECRET_VALUE = /\b(?:Bearer|Basic|Digest|Token)\s+\S+/gi;
+// Case-insensitive: `Authorization: abc`, `Api-Token=xyz`, `Bearer`-style
+// headers are redacted regardless of casing (D2). The alternation is the same
+// secret vocabulary as SENSITIVE_WORDS, so the over-redaction risk is limited
+// to values next to a secret-ish key — acceptable for a security logger.
+const KEY_EQ_VALUE =
+  /\b([A-Za-z0-9_-]*(?:token|secret|password|passwd|apikey|api[_-]?key|authorization|credential|bearer)[A-Za-z0-9_-]*)([:=]\s*).+/gi;
+const URL_QUERY = /(https?:\/\/[^?#\s]+)\?[^#\s]*/g;
+
+// Split camelCase AND acronym+word compounds (APIToken -> api|token, so the
+// "token" word lands in SENSITIVE_WORDS instead of the whole lowercase
+// compound "apitoken" leaking past it) (D1).
+const splitKey = (key: string): string[] =>
+  key
+    .split(/[_-]+|(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])/)
+    .map((word) => word.toLowerCase());
+
+const SENSITIVE_WORDS = new Set([
+  "token",
+  "secret",
+  "password",
+  "passwd",
+  "authorization",
+  "credential",
+  "credentials",
+  "cookie",
+  "api",
+  "apikey",
+  "apitoken",
+  "accesstoken",
+  "clientsecret",
+  "refreshtoken",
+  "key",
+  "bearer",
+  "prompt",
+  "message",
+  "messages",
+  "content",
+  "body",
+  "args",
+  "argument",
+  "result",
+  "results",
+  "output",
+  "issue",
+  "description",
+  "summary",
+  "payload",
+  "script",
+  "command",
+  "text",
+  "query",
+]);
+
+const STACK_WORDS = new Set(["stack", "stacktrace", "trace"]);
+
+const escapeRegExp = (value: string): string => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+export const resolveStateDir = (): string => {
+  const override = process.env.WORKFLOW_TOOLKIT_STATE;
+  if (override) return override;
+  const home = os.homedir();
+  if (process.env.XDG_STATE_HOME) return path.join(process.env.XDG_STATE_HOME, "workit");
+  switch (os.platform()) {
+    case "darwin":
+      return path.join(home, "Library", "Application Support", "workit");
+    case "win32":
+      return path.join(process.env.LOCALAPPDATA ?? path.join(home, "AppData", "Local"), "workit");
+    default:
+      return path.join(process.env.HOME ?? home, ".local", "state", "workit");
+  }
+};
+
+type RedactOptions = {
+  maxFieldLength: number;
+  maxStackLines: number;
+};
+
+// The separator lookahead accepts both / and \ so home-relative Windows paths
+// (C:\Users\x\repo) redact too — os.homedir() uses backslashes there.
+const homePattern = new RegExp(
+  `${escapeRegExp(os.homedir())}(?=[/\\\\]|$)|\\$HOME(?=[/\\\\]|$)`,
+  "g",
+);
+
+const applyPatterns = (value: string): string => {
+  let out = value;
+  out = out.replace(SECRET_VALUE, REDACTED);
+  out = out.replace(KEY_EQ_VALUE, "$1$2[REDACTED]");
+  out = out.replace(URL_QUERY, "$1?[REDACTED]");
+  out = out.replace(homePattern, "~");
+  // win32 paths keep backslashes after the ~ substitution (~\repo); normalize
+  // separators so logged paths are portable and match the shell-shaped ~/
+  // form. Other platforms are untouched.
+  if (process.platform === "win32") out = out.replace(/\\/g, "/");
+  return out;
+};
+
+/**
+ * Pattern-only redaction: strips secret value patterns from a string while
+ * preserving its full text — no field-length truncation. The receiver owns its
+ * own size bound (e.g. an MCP error string must stay intact for the client).
+ */
+export const redactSecrets = (value: string): string => applyPatterns(value);
+
+const redactString = (value: string, options: RedactOptions): string => {
+  const out = applyPatterns(value);
+  if (out.length > options.maxFieldLength) {
+    return `${out.slice(0, options.maxFieldLength)}…`;
+  }
+  return out;
+};
+
+const boundStack = (value: unknown, options: RedactOptions): JsonValue => {
+  if (typeof value !== "string") return redact(value, options);
+  const lines = value.split("\n");
+  const kept = lines.slice(0, options.maxStackLines).map(applyPatterns);
+  const dropped = lines.length - kept.length;
+  const body = dropped > 0 ? [...kept, `    ... ${dropped} more`] : kept;
+  return body.join("\n");
+};
+
+export const redact = (value: unknown, options: RedactOptions = DEFAULT_OPTIONS): JsonValue => {
+  if (value === null || value === undefined) return null;
+  if (typeof value === "boolean" || typeof value === "number") return value;
+  if (typeof value === "string") return redactString(value, options);
+  if (value instanceof Date) return value.toISOString();
+  if (Array.isArray(value)) return value.map((entry) => redact(entry, options));
+  if (typeof value === "object") {
+    const out: Record<string, JsonValue> = {};
+    for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+      const words = splitKey(key);
+      if (words.some((word) => STACK_WORDS.has(word))) out[key] = boundStack(entry, options);
+      else if (words.some((word) => SENSITIVE_WORDS.has(word))) out[key] = REDACTED;
+      else out[key] = redact(entry, options);
+    }
+    return out;
+  }
+  return null;
+};
+
+const DEFAULT_OPTIONS: RedactOptions = {
+  maxFieldLength: DEFAULT_MAX_FIELD_LENGTH,
+  maxStackLines: DEFAULT_MAX_STACK_LINES,
+};
+
+const dailyFileName = (date: Date): string => {
+  const y = date.getFullYear();
+  const m = String(date.getMonth() + 1).padStart(2, "0");
+  const d = String(date.getDate()).padStart(2, "0");
+  return `workit-${y}-${m}-${d}.jsonl`;
+};
+
+const pruneOldFiles = (dir: string): void => {
+  try {
+    const files = readdirSync(dir)
+      .filter((name) => DAY_FILE.test(name))
+      .sort()
+      .reverse();
+    for (const file of files.slice(RETAINED_DAYS)) {
+      try {
+        unlinkSync(path.join(dir, file));
+      } catch {
+        // a concurrent prune may already have removed it
+      }
+    }
+  } catch {
+    // logging must never break the host
+  }
+};
+
+export const createLogger = (options: LoggerOptions = {}): Logger => {
+  const stateDir = options.stateDir ?? resolveStateDir();
+  const logDir = path.join(stateDir, "logs");
+  const now = options.now ?? (() => new Date());
+  const maxRate = options.maxRate ?? DEFAULT_MAX_RATE;
+  const rateWindowMs = options.rateWindowMs ?? DEFAULT_RATE_WINDOW_MS;
+  const redactOptions: RedactOptions = {
+    maxFieldLength: options.maxFieldLength ?? DEFAULT_MAX_FIELD_LENGTH,
+    maxStackLines: options.maxStackLines ?? DEFAULT_MAX_STACK_LINES,
+  };
+
+  let windowStart = 0;
+  const windowCounts: Record<LogLevel, number> = { debug: 0, info: 0, warn: 0, error: 0 };
+
+  const emit = (level: LogLevel, message: string, context?: Record<string, unknown>): void => {
+    const date = now();
+    const elapsed = date.getTime() - windowStart;
+    if (elapsed >= rateWindowMs || windowStart === 0) {
+      windowStart = date.getTime();
+      windowCounts.debug = 0;
+      windowCounts.info = 0;
+      windowCounts.warn = 0;
+      windowCounts.error = 0;
+    }
+    windowCounts[level] += 1;
+    if (windowCounts[level] > maxRate) return;
+
+    // ponytail: per-level budget so an info flood can't starve warn/error
+    // canaries; shared-token budget would need cross-level prioritization.
+    let event: LogEvent | null = null;
+    try {
+      event = {
+        level,
+        time: date.toISOString(),
+        message: redactString(message, redactOptions),
+        context: redact(context ?? {}, redactOptions) as Record<string, JsonValue>,
+      };
+      const line = `${JSON.stringify(event)}\n`;
+      mkdirSync(logDir, { recursive: true, mode: 0o700 });
+      appendFileSync(path.join(logDir, dailyFileName(date)), line, { mode: 0o600 });
+      pruneOldFiles(logDir);
+    } catch {
+      // Serialization (e.g. a circular context) must never throw into the
+      // caller: record a bounded failure event instead.
+      try {
+        event = {
+          level,
+          time: date.toISOString(),
+          message: redactString(message, redactOptions),
+          context: { redaction_failed: true },
+        };
+        mkdirSync(logDir, { recursive: true, mode: 0o700 });
+        appendFileSync(path.join(logDir, dailyFileName(date)), `${JSON.stringify(event)}\n`, {
+          mode: 0o600,
+        });
+      } catch {
+        // logging must never break the host
+      }
+    }
+
+    for (const sink of [options.appLog, options.stderr]) {
+      if (!sink) continue;
+      if (!event) continue;
+      try {
+        sink(event);
+      } catch {
+        // a broken sink must not break the caller
+      }
+    }
+  };
+
+  return {
+    debug: (message, context) => emit("debug", message, context),
+    info: (message, context) => emit("info", message, context),
+    warn: (message, context) => emit("warn", message, context),
+    error: (message, context) => emit("error", message, context),
+    guard: <T>(name: string, fn: () => T): T | undefined => {
+      try {
+        return fn();
+      } catch (err) {
+        emit("warn", "detector_failed", {
+          detector: name,
+          error: err instanceof Error ? err.message : String(err),
+        });
+        return undefined;
+      }
+    },
+  };
+};

package/src/core/package-root.ts

@@ -0,0 +1,28 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Package-local asset root. Core modules resolve their static assets relative to
+// their own package root (templates/, commands/, skills/, hygiene/). In the
+// monorepo the source package keeps assets at the package root; packaged
+// adapters ship the same content under an explicit `assets/` directory.
+//
+// The walk finds the nearest ancestor directory that owns a package.json, which
+// is the package root for both the monorepo source (packages/<pkg>/src/core/…)
+// and a bundled adapter entry (packages/<pkg>/dist/….js).
+export const packageRoot = (): string => {
+  let dir = path.dirname(fileURLToPath(import.meta.url));
+  while (true) {
+    const parent = path.dirname(dir);
+    // ponytail: stop at the filesystem root even without an ancestor package.json,
+    // so the upward walk can never loop forever.
+    if (existsSync(path.join(dir, "package.json")) || parent === dir) return dir;
+    dir = parent;
+  }
+};
+
+export const assetRoot = (): string => {
+  const root = packageRoot();
+  const assets = path.join(root, "assets");
+  return existsSync(assets) ? assets : root;
+};

package/src/core/ports/init-toolkit-status.ts

@@ -1,4 +1,4 @@
 // CLI port of scripts/init/toolkit-status.sh.
 import { toolkitStatusData } from "../init";
 
-console.log(JSON.stringify(toolkitStatusData(), null, 2));
+console.log(JSON.stringify(await toolkitStatusData(), null, 2));

package/src/core/ports/vcs-verify-token.ts

@@ -1,4 +1,4 @@
 // CLI port of scripts/vcs/verify-token.sh — soft-fail JSON, exit 0.
 import { vcsVerifyToken } from "../vcs-config";
 
-console.log(JSON.stringify(vcsVerifyToken()));
+console.log(JSON.stringify(await vcsVerifyToken()));

package/src/core/ports/youtrack-api.ts

@@ -11,7 +11,7 @@ if (cmd === "log-time" || cmd === "post-comment") {
     process.exit(1);
   }
 }
-const out = youTrackApi(args, process.env.WORKFLOW_YT_WRITE ?? "");
+const out = await youTrackApi(args, process.env.WORKFLOW_YT_WRITE ?? "");
 if ("error" in out) {
   console.log(JSON.stringify({ ok: false, error: out.error }));
   process.exit(1);

package/src/core/ports/youtrack-verify-token.ts

@@ -1,7 +1,7 @@
 // CLI port of scripts/youtrack/verify-token.sh.
 import { youTrackVerifyToken } from "../youtrack";
 
-const out = youTrackVerifyToken();
+const out = await youTrackVerifyToken();
 if ("error" in out) {
   const payload: Record<string, any> = { ok: false, error: out.error };
   if (out.http_status !== undefined) payload.http_status = out.http_status;

package/src/core/pr-create.ts

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { vcsConfig } from "./vcs-config";
+import { resolveBranchPolicyFor } from "./branch";
 
 // Port of scripts/pr-create.sh — build MR/PR body issue linking + create via glab/gh.
 
@@ -19,6 +20,23 @@ function parseGhIssue(value: string): string {
   return m ? m[1] : String(value).trim().replace(/^#/, "");
 }
 
+// RL-03/CA-25/AR-08: a branch-derived numeric issue id must be a bare number at
+// a segment or dash boundary — and never part of a date segment. Year-first
+// (feature/2024-01-15/x) and day-first (feature/15-01-2024/x) dates are both
+// skipped — a complete date anywhere in a segment (release-2024-01-15,
+// v2-2024-01-15-fix) — so no date digit ever closes an issue. Deliberate
+// numeric issue branches (feature/42-title, feature/2024-fix) keep linking.
+function deriveGhIssueFromBranch(branch: string): string {
+  for (const segment of branch.split("/")) {
+    if (/^\d{4}-\d/.test(segment)) continue; // year-first date-like segment (incl. year-month)
+    if (/\d{4}-\d{1,2}-\d{1,2}/.test(segment)) continue; // complete year-first date anywhere
+    if (/\d{1,2}-\d{1,2}-\d{4}/.test(segment)) continue; // complete day-first date anywhere
+    const m = /(?:^|-)(\d+)(?:-|$)/.exec(segment);
+    if (m) return m[1];
+  }
+  return "";
+}
+
 function buildBody(
   body: string,
   branch: string,
@@ -44,9 +62,7 @@ function buildBody(
     if (!issue && branch) {
       // pure-number issue id (feature/42-title -> 42); digits must be followed by a dash or end-of-string
       // so version tokens (release/1.2.3, backport/8.0.1, lodash-4.17.21, 2024.1) never link
-      // ponytail: known date-style false positive (feature/2024-01-fix -> Closes #2024); accepted — bare 42-title support is deliberate
-      const m = /(?:^|\/|-)(\d+)(?:-|$)/.exec(branch);
-      if (m) issue = m[1];
+      issue = deriveGhIssueFromBranch(branch);
     }
     if (issue) {
       if (ghRelation === "related") {
@@ -66,14 +82,19 @@ const truthy = (v: string | undefined): boolean =>
 
 // Port of python's shutil.which — scan PATH in-process (no `which` binary needed).
 function whichOnPath(tool: string): string | null {
-  for (const dir of (process.env.PATH ?? "").split(":")) {
+  // win32 CLIs/stubs carry .exe/.cmd suffixes (gh.exe, gh.cmd), so probe them
+  // too — accessSync with the bare name would never find them.
+  const names = process.platform === "win32" ? [tool, `${tool}.exe`, `${tool}.cmd`] : [tool];
+  for (const dir of (process.env.PATH ?? "").split(path.delimiter)) {
     if (!dir) continue;
-    const candidate = path.join(dir, tool);
-    try {
-      fs.accessSync(candidate, fs.constants.X_OK);
-      return candidate;
-    } catch {
-      /* keep scanning */
+    for (const name of names) {
+      const candidate = path.join(dir, name);
+      try {
+        fs.accessSync(candidate, fs.constants.X_OK);
+        return candidate;
+      } catch {
+        /* keep scanning */
+      }
     }
   }
   return null;
@@ -108,14 +129,93 @@ export function prBuildBody(env: NodeJS.ProcessEnv, cwd?: string): string {
 /** Port of scripts/pr-create.sh create mode — glab/gh MR/PR creation. */
 export function prCreate(env: NodeJS.ProcessEnv, cwd: string): Record<string, any> {
   const root = process.env.WORKFLOW_WORKSPACE_ROOT ?? repoRoot(cwd);
+  const policy = resolveBranchPolicyFor(root);
   const cfg = vcsConfig("load", root);
   if (!cfg.ok) return { error: cfg.error ?? "vcs config missing" };
-  if (!cfg.tokenReady)
+  // Merge mode finishes the feature locally (git merge + push) — no glab/gh,
+  // no API token, so token readiness is only required for the PR path.
+  if (policy.integration !== "merge" && !cfg.tokenReady)
     return { error: "VCS token not ready — run /wk-init and edit token file locally" };
 
   const provider = cfg.provider as string;
   if (provider !== "gitlab" && provider !== "github")
     return { error: `unsupported provider: ${provider}` };
+
+  // B1/RL-03: WF_PR_TARGET is the one deliberate override knob on the create
+  // surface (resolvePrBranchContext/docsBranch have none). Unlike the config
+  // default — which is authoritative by construction — a caller-supplied
+  // target is validated against the resolved branch policy so a PR can never
+  // be aimed at a protected or disallowed branch.
+  const targetOverride = env.WF_PR_TARGET;
+  const target =
+    targetOverride || String(cfg.defaultTargetBranch ?? policy.defaultTargetBranch ?? "develop");
+  if (targetOverride) {
+    const { allowed, protected: protectedTargets } = policy;
+    if (protectedTargets.has(targetOverride.toLowerCase()))
+      return {
+        error: `PR target ${JSON.stringify(targetOverride)} is a protected branch — override must be an allowed non-protected target`,
+      };
+    if (!allowed.some((r) => r.test(targetOverride)))
+      return {
+        error: `PR target ${JSON.stringify(targetOverride)} is not allowed by the branch policy`,
+      };
+  }
+
+  const title = String(env.WF_PR_TITLE ?? "");
+  const br = spawnSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+    cwd: root,
+    encoding: "utf8",
+  });
+  const branch = br.status === 0 ? (br.stdout ?? "").trim() : "";
+
+  if (policy.integration === "merge") {
+    const finish = (): Record<string, any> => {
+      const merge = spawnSync("git", ["merge", "--no-ff", branch, "-m", title], {
+        cwd: root,
+        encoding: "utf8",
+      });
+      if (merge.status !== 0)
+        return {
+          error: "merge failed",
+          mode: "merge",
+          targetBranch: target,
+          stderr: (merge.stderr ?? "").slice(0, 800),
+        };
+      const push = spawnSync("git", ["push", "origin", target], { cwd: root, encoding: "utf8" });
+      if (push.status !== 0)
+        return {
+          error: "push failed",
+          mode: "merge",
+          targetBranch: target,
+          stderr: (push.stderr ?? "").slice(0, 800),
+        };
+      return {
+        ok: true,
+        mode: "merge",
+        targetBranch: target,
+        merged: true,
+        pushed: true,
+        output: (push.stdout ?? "").trim(),
+      };
+    };
+    const co = spawnSync("git", ["checkout", target], { cwd: root, encoding: "utf8" });
+    if (co.status !== 0)
+      return {
+        error: `cannot checkout target ${target}`,
+        mode: "merge",
+        targetBranch: target,
+        stderr: (co.stderr ?? "").slice(0, 800),
+      };
+    // finish() returns error objects, it never throws, so the best-effort
+    // `git checkout branch` restore below runs on ALL outcomes (success,
+    // merge failure, and push failure) — the tree always returns to the
+    // feature branch. Deliberately not a try/finally: the restore is
+    // best-effort and its own failure is not actionable on this path.
+    const result = finish();
+    spawnSync("git", ["checkout", branch], { cwd: root, encoding: "utf8" }); // best-effort return
+    return result;
+  }
+
   const cli = provider === "gitlab" ? "glab" : "gh";
   const installUrl =
     provider === "gitlab" ? "https://gitlab.com/gitlab-org/cli" : "https://cli.github.com";
@@ -130,16 +230,8 @@ export function prCreate(env: NodeJS.ProcessEnv, cwd: string): Record<string, an
 
   const pr = (cfg.pr ?? {}) as Record<string, any>;
   const token = fs.readFileSync(cfg.tokenPath as string, "utf8").trim();
-  const title = String(env.WF_PR_TITLE ?? "");
   const body = env.WF_PR_BODY ?? "";
   const draft = String(env.WF_PR_DRAFT ?? "false").toLowerCase() === "true";
-  const target = env.WF_PR_TARGET || String(cfg.defaultTargetBranch ?? "develop");
-
-  const br = spawnSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
-    cwd: root,
-    encoding: "utf8",
-  });
-  const branch = br.status === 0 ? (br.stdout ?? "").trim() : "";
 
   let baseUrl = cfg.youtrack_base_url as string | undefined;
   if (!baseUrl) {
@@ -186,12 +278,15 @@ export function prCreate(env: NodeJS.ProcessEnv, cwd: string): Record<string, an
     if (draft) cmd.push("--draft");
     if (push) cmd.push("--push");
     if (skipConfirm) cmd.push("--yes");
-    cmdEnv = { ...process.env, GITLAB_TOKEN: token };
+    // bun's Windows spawn only consults PATH when the env object carries an
+    // explicit PATH key — a spread-only PATH is invisible to the lookup and
+    // uv_spawn fails with ENOENT even though the CLI is on PATH.
+    cmdEnv = { ...process.env, PATH: process.env.PATH ?? "", GITLAB_TOKEN: token };
   } else {
     cmd = ["gh", "pr", "create", "--title", title, "--base", target];
     if (finalBody) cmd.push("--body", finalBody);
     if (draft) cmd.push("--draft");
-    cmdEnv = { ...process.env, GH_TOKEN: token };
+    cmdEnv = { ...process.env, PATH: process.env.PATH ?? "", GH_TOKEN: token };
   }
 
   const result = spawnSync(cmd[0], cmd.slice(1), { cwd: root, encoding: "utf8", env: cmdEnv });