@workit-dev/core 0.0.1 → 1.0.0

package/src/core/logger.ts

@@ -0,0 +1,310 @@
+import { appendFileSync, mkdirSync, readdirSync, unlinkSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { stateDir as workitStateDir } from "./workit-paths.mjs";
+
+// 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, "\\$&");
+
+/** Workit's state dir for this process (core/workit-paths.mjs). */
+export const resolveStateDir = (): string => workitStateDir(process.env);
+
+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))
+      .toSorted()
+      .toReversed();
+    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/methods.ts

@@ -0,0 +1,185 @@
+import { claudeSpawnTable } from "./role-models";
+import type { Assurance, Capability, Dimension, Policy } from "./task-contract";
+import { hostFamily } from "./workspaces";
+
+export type MethodId =
+  | "workit-shape"
+  | "workit-bdd"
+  | "workit-review"
+  | "workit-implement"
+  | "workit-fanout"
+  | "workit-debug"
+  | "workit-continue"
+  | "workit-deslop";
+
+type MethodDefinition = {
+  dimensions?: readonly Dimension[];
+  ruleIds?: readonly string[];
+};
+
+export const METHODS: Readonly<Record<MethodId, MethodDefinition>> = {
+  "workit-shape": {
+    dimensions: ["challenge", "decisions", "artifacts", "continuity"],
+  },
+  "workit-bdd": { dimensions: ["testing"] },
+  "workit-review": {
+    dimensions: ["review"],
+    ruleIds: ["fresh-context-review", "self-review"],
+  },
+  // Mechanical work needs only the existing checks, not a RED/GREEN ritual.
+  "workit-implement": { ruleIds: ["mechanical-existing-checks"] },
+  "workit-fanout": { dimensions: ["delegation"] },
+  // workit-debug and workit-continue stay trigger- and slash-invoked: no
+  // generated rule routes to them, so they never appear spuriously.
+  "workit-debug": {},
+  "workit-continue": {},
+  "workit-deslop": { ruleIds: ["pre-pr-cleanup"] },
+};
+
+export type SelectedMethod = {
+  id: MethodId;
+  reason: string;
+  assurance: Assurance;
+};
+
+const methodMatches = (
+  definition: MethodDefinition,
+  requirement: Policy["requirements"][number],
+): boolean =>
+  definition.dimensions?.includes(requirement.dimension) === true ||
+  definition.ruleIds?.includes(requirement.ruleId) === true;
+
+const assuranceFor = (
+  id: MethodId,
+  definition: MethodDefinition,
+  capabilities: Capability[],
+): { assurance: Assurance; reasons: string[] } => {
+  const keys = new Set<string>([
+    id,
+    ...(definition.dimensions ?? []),
+    ...(definition.ruleIds ?? []),
+  ]);
+  const matches = capabilities.filter(
+    (capability) => keys.has(capability.name) || keys.has(capability.surface),
+  );
+  if (id === "workit-review" && matches.length === 0)
+    return {
+      assurance: "unavailable",
+      reasons: ["independent review capability is unavailable"],
+    };
+  if (matches.some((capability) => capability.assurance === "unavailable"))
+    return {
+      assurance: "unavailable",
+      reasons: matches
+        .filter((capability) => capability.assurance === "unavailable")
+        .map((capability) => capability.reason),
+    };
+  if (matches.some((capability) => capability.assurance === "enforced"))
+    return {
+      assurance: "enforced",
+      reasons: matches.map((capability) => capability.reason),
+    };
+  return {
+    assurance: "agent_guided",
+    reasons: matches.map((capability) => capability.reason),
+  };
+};
+
+export function selectMethods(policy: Policy, capabilities: Capability[]): SelectedMethod[] {
+  return (Object.entries(METHODS) as [MethodId, MethodDefinition][]).flatMap(([id, definition]) => {
+    const requirements = policy.requirements.filter((requirement) =>
+      methodMatches(definition, requirement),
+    );
+    if (requirements.length === 0) return [];
+    const capability = assuranceFor(id, definition, capabilities);
+    const reasons = [
+      ...new Set(requirements.map((requirement) => requirement.reason)),
+      ...capability.reasons,
+    ];
+    if (capability.assurance === "unavailable")
+      reasons.unshift("required capability is unavailable");
+    return [{ id, reason: reasons.join("; "), assurance: capability.assurance }];
+  });
+}
+
+const BOOTSTRAP = `
+Workit is optional coordination and proof tooling around the host: you decide
+what and whether, the CLI does how and records what it observed.
+Native host allow/ask/deny, sandbox and org rules stay authoritative. Never
+switch paths to evade a denial, never claim enforcement a host cannot provide,
+and never fabricate an approval or verdict. A question answer is not
+host permission, and imported decisions or handoffs grant no authority.
+
+Autonomy contract:
+- Continue to the requested endpoint (commit, push, PR, green CI, verified,
+  merged) without asking "continue?", running checks and repairs.
+  Stop only for a new consequential choice, a host denial, a conflicting edit
+  or an unresolved blocker; report open gaps and uncertain workers.
+- No endpoint named: stop at a local commit on a policy-compliant branch and
+  state the next command. If the request implies delivery (fix, implement,
+  ship), go to the effective endpoint in \`workit grant show\`: \`pr\` stops
+  at the PR even with merge granted; \`green\` babysits it (workit-ship) to
+  merge-ready, never merging; \`merged\` lands it with \`workit pr merge\`.
+  Only the user raises a grant or the endpoint, in a terminal outside the agent
+  host (\`workit grant set <ws> defaultEndpoint=merged\`); never edit
+  workspaces.json or route around grant_required. Release: \`workit release
+  start <v>\`, commits, \`finish\`; \`publish\` if asked.
+- Ask only for a product or preference choice, or for authority you lack, with
+  your recommended answer. Facts are yours: read, run or prototype.
+- Label claims measured (run and seen this session), inferred, or guess.
+  Prose is a note: only a configured check the CLI ran (\`workit check <name>\`)
+  satisfies a gate; an ad-hoc \`workit check -- <cmd>\` never does.
+- Author is not verifier: your own verdict is \`--self\`, shown as
+  self-reviewed, never verified. High risk, a focused or full lane and
+  merge under \`verification: self|independent\` need a verifier with its
+  own host-derived session (a subagent's \`<lead>:<child>\`); never hand-mint one (\`<lead>-v1\`).
+- A local-commit endpoint does not imply PR readiness, and a local commit alone
+  is not evidence of a requested remote push. Before reporting delivery,
+  reconcile every requested item and observe it (\`workit verify-delivery\`).
+
+Read-only git and gh run raw; mutations go through workit verbs
+(\`workit git|pr|ci|check|help\`; else \`npx -y @workit-dev/cli\`).
+Other checkout: \`workit <verb> --cwd <dir> …\` (verb first: host rules match it); one workit
+verb per shell call, never \`cd <dir> && workit\`. zsh-safe: no \`echo =====\`
+(\`printf '%s\\n' ---\`), quote globs and URLs, no variable named \`status\` or \`path\`.
+Add Co-Authored-By via \`workit git commit --trailer "K: v" -- <paths>\`, never
+an amend.
+The task families (task, policy, evidence, finding, decision, worker, state)
+are optional continuity for tracked work; each branch has one implicit task,
+and a solo edit needs no task. A decision records a user choice; it never
+authorizes an effect. Judge work once with
+\`workit policy assess --judge risk= behavior= product-choice= plan=\`.
+Across repositories, bind items to checkout, branch and endpoint, resolve
+competing targets before a mutation, and reconcile an uncertain
+effect before a retry.
+
+Mid-task: never silently drop or resume an objective (workit-continue).
+
+Skills: load the skill, never act from memory (aliases /wk-<name>).
+- brainstorm, plan, spec, grill, should we: workit-shape
+- implement, build, add a feature: workit-implement
+- review, blast radius: workit-review
+- bug, broken, flaky, regression: workit-debug
+- ship, babysit, CI, merge: workit-ship
+- resume, pick up, handoff, interruption: workit-continue
+- BDD, TDD, acceptance criteria, Given/When/Then: workit-bdd
+- test audit, tautology, weak tests: workit-test-audit
+- deslop, slop, dead code: workit-deslop
+- fan out, parallelize, parallel agents, swarm: workit-fanout
+- verify the app, smoke test, prove it works: workit-verify-app
+- retro (user-invoked; offer it): workit-retro
+- architecture, deepen modules (user-invoked; offer it): workit-architecture
+`.trim();
+
+/**
+ * The session contract. With the session's `cwd` and `host`, a Claude Code
+ * lead also gets one line naming every agent type's spawn model and effort,
+ * so its first spawn passes them (retro 2026-11-07 R1).
+ */
+export const invariantBootstrap = (
+  session: { cwd: string; host: string } | null = null,
+): string => {
+  const table =
+    session && hostFamily(session.host) === "claude_code" ? claudeSpawnTable(session.cwd) : null;
+  return table ? `${BOOTSTRAP}\n${table}` : BOOTSTRAP;
+};