@brainervirus/workit-core 0.4.0

package/src/core/git.ts

@@ -0,0 +1,56 @@
+import { execFileSync } from "node:child_process";
+
+const run = (cwd: string, args: string[]): { stdout: string; stderr: string; exitCode: number } => {
+  try {
+    const stdout = execFileSync("git", args, { cwd, encoding: "utf8" });
+    return { stdout: stdout.trimEnd(), stderr: "", exitCode: 0 };
+  } catch (error) {
+    const e = error as { stdout?: string; stderr?: string; status?: number };
+    return {
+      stdout: (e.stdout ?? "").trimEnd(),
+      stderr: (e.stderr ?? "").trimEnd(),
+      exitCode: e.status ?? 1,
+    };
+  }
+};
+
+export const gitContext = (workspaceRoot: string, paths: string[] = []) => {
+  const cwd = workspaceRoot;
+  const branch = run(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]).stdout || "unknown";
+  const status_short = run(cwd, ["status", "--porcelain"]).stdout;
+
+  const staged: string[] = [];
+  const unstaged: string[] = [];
+  const untracked: string[] = [];
+
+  for (const line of status_short.split("\n").filter(Boolean)) {
+    const code = line.slice(0, 2);
+    const file = line.slice(3);
+    if (code === "??") {
+      untracked.push(file);
+    } else {
+      if (code[0] !== " " && code[0] !== "?") staged.push(file);
+      if (code[1] !== " " && code[1] !== "?") unstaged.push(file);
+    }
+  }
+
+  const pathArgs = paths.length ? ["--", ...paths] : [];
+  const diff_stat = run(cwd, ["diff", "--stat", ...pathArgs]).stdout;
+  const cached_stat = run(cwd, ["diff", "--cached", "--stat", ...pathArgs]).stdout;
+
+  const stagedSet = new Set(staged);
+  const unstagedSet = new Set(unstaged);
+  const partial_staged = [...stagedSet].filter((f) => unstagedSet.has(f));
+
+  return {
+    workspace_root: cwd,
+    branch,
+    status_short,
+    staged,
+    unstaged,
+    untracked,
+    diff_stat: [diff_stat, cached_stat].filter(Boolean).join("\n"),
+    partial_staged: partial_staged.length > 0,
+    partial_staged_files: partial_staged,
+  };
+};

package/src/core/gitignore.ts

@@ -0,0 +1,43 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+export const GITIGNORE_ENTRIES = [
+  "# workit: SDD working state (never commit)",
+  "docs/*/sdd/",
+  "",
+  "# OS / editor cruft",
+  ".DS_Store",
+  "Thumbs.db",
+  "*.swp",
+  ".idea/",
+  ".vscode/",
+  ".env",
+  "node_modules/",
+  "dist/",
+  "*.log",
+  ".cache/",
+];
+
+export const ensureProjectGitignore = (
+  workspaceRoot: string,
+  confirmed: boolean,
+): { ok: true; path: string; added: string[] } | { ok: false; error: string } => {
+  if (!confirmed) return { ok: false, error: "confirmed: true required" };
+  const file = path.join(workspaceRoot, ".gitignore");
+  const existing = existsSync(file) ? readFileSync(file, "utf8") : "";
+  const existingLines = new Set(existing.split("\n").map((l) => l.trim()).filter(Boolean));
+  const added: string[] = [];
+  const append: string[] = [];
+  for (const entry of GITIGNORE_ENTRIES) {
+    if (entry.trim() === "" || existingLines.has(entry.trim())) continue;
+    append.push(entry);
+    added.push(entry);
+  }
+  if (append.length) {
+    const separator = existing && !existing.endsWith("\n") ? "\n" : "";
+    writeFileSync(file, existing + separator + (existing ? "\n" : "") + append.join("\n") + "\n", "utf8");
+  } else if (!existsSync(file)) {
+    writeFileSync(file, "", "utf8");
+  }
+  return { ok: true, path: file, added };
+};

package/src/core/handoff-context.ts

@@ -0,0 +1,115 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { docsValidate } from "./docs-validate";
+import { resolveBranch } from "./branch";
+import { parseTasksFromPlan } from "./docs-validate";
+
+const DOC_RE = /docs\/([A-Za-z0-9][A-Za-z0-9._-]*)\/(spec|plan)\.md/g;
+
+const listMd = (dir: string): string[] => {
+  try {
+    return readdirSync(dir)
+      .filter((f) => f.endsWith(".md"))
+      .sort();
+  } catch {
+    return [];
+  }
+};
+
+type Resolved = { spec: string; plan: string; source: string } | { error: string };
+
+const extractMessagePaths = (message: string): string[] =>
+  [...new Set(message.match(DOC_RE) ?? [])].sort();
+
+const resolveFromMessagePaths = (root: string, message: string): Resolved => {
+  const paths = extractMessagePaths(message);
+  if (paths.length === 0) return { error: "no paths" };
+  const slugs = [...new Set(paths.map((p) => p.split("/")[1]))];
+  if (slugs.length !== 1) return { error: "multiple features in message — use exactly one docs/<slug>/ pair" };
+  const slug = slugs[0];
+  const plan = `docs/${slug}/plan.md`;
+  const spec = `docs/${slug}/spec.md`;
+  if (!existsSync(path.join(root, plan)) || !existsSync(path.join(root, spec))) {
+    return { error: `docs/${slug}/ must contain both plan.md and spec.md` };
+  }
+  return { spec, plan, source: "message_paths" };
+};
+
+const resolveActivePair = (root: string): Resolved => {
+  const docsDir = path.join(root, "docs");
+  let best: { score: number; spec: string; plan: string; source: string } | null = null;
+  let entries: string[] = [];
+  try {
+    entries = readdirSync(docsDir);
+  } catch {
+    return { error: "no pair" };
+  }
+  for (const slug of entries) {
+    if (slug.startsWith(".")) continue;
+    const plan = path.join("docs", slug, "plan.md");
+    const spec = path.join("docs", slug, "spec.md");
+    if (!existsSync(path.join(root, plan)) || !existsSync(path.join(root, spec))) continue;
+    const score = Math.max(statSync(path.join(root, spec)).mtimeMs, statSync(path.join(root, plan)).mtimeMs);
+    if (best === null || score > best.score || (score === best.score && slug < best.spec.split("/")[1])) {
+      best = { score, spec, plan, source: "active_pair" };
+    }
+  }
+  if (best === null) return { error: "no pair" };
+  return { spec: best.spec, plan: best.plan, source: best.source };
+};
+
+export const resolveWorkflowPaths = (root: string, message: string): Resolved => {
+  const fromMessage = resolveFromMessagePaths(root, message);
+  if (!("error" in fromMessage)) return fromMessage;
+  if (fromMessage.error !== "no paths") return fromMessage;
+  const active = resolveActivePair(root);
+  if (!("error" in active)) return active;
+
+  const docsDir = path.join(root, "docs");
+  if (!existsSync(docsDir) || listMd(docsDir).length === 0) {
+    return { error: "no docs/<slug>/ features found under docs/" };
+  }
+  return { error: "could not resolve spec and plan — mention docs/<slug>/plan.md or create docs/<slug>/{spec.md,plan.md}" };
+};
+
+export const buildHandoffContract = ({
+  root,
+  spec,
+  plan,
+  templatePath,
+}: {
+  root: string;
+  spec: string;
+  plan: string;
+  templatePath: string;
+}): { prompt: string } | { error: string } => {
+  const validated = docsValidate({ spec_path: spec, plan_path: plan, workspace_root: root });
+  if (validated.ok === false) {
+    return { error: `docs validation failed\n${JSON.stringify({ ok: false, errors: validated.errors })}` };
+  }
+  const branchResolved = resolveBranch({ spec_path: spec, plan_path: plan, workspace_root: root });
+  if ("error" in branchResolved) return { error: branchResolved.error as string };
+  const branch = branchResolved.branch;
+  const slug = path.basename(path.dirname(plan));
+  const sddDir = `docs/${slug}/sdd`;
+
+  const planText = readFileSync(path.join(root, plan), "utf8");
+  const tasks = parseTasksFromPlan(planText);
+  const taskList = tasks.map((t) => `- Task ${t.id}: ${t.title}`).join("\n");
+
+  let contract: string;
+  try {
+    contract = readFileSync(templatePath, "utf8");
+  } catch {
+    return { error: "missing template templates/execution-contract.md" };
+  }
+  contract = contract
+    .replace(/<SPEC_PATH>/g, spec)
+    .replace(/<PLAN_PATH>/g, plan)
+    .replace(/<BRANCH>/g, branch)
+    .replace(/<SLUG>/g, slug)
+    .replace(/<SDD_DIR>/g, sddDir)
+    .replace(/<TASK_LIST>/g, taskList);
+
+  return { prompt: contract };
+};

package/src/core/hygiene.ts

@@ -0,0 +1,77 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { changelogUnreleasedStats } from "./changelog";
+
+export type HygieneFile = "CHANGELOG.md" | "README.md" | ".editorconfig" | ".gitattributes" | "LICENSE" | "CONTRIBUTING.md";
+type State = "missing" | "invalid" | "ok" | "skip";
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+const templatesDir = () => path.join(repoRoot, "templates", "hygiene");
+
+const packageJson = (root: string): Record<string, unknown> | null => {
+  if (!existsSync(path.join(root, "package.json"))) return null;
+  try { return JSON.parse(readFileSync(path.join(root, "package.json"), "utf8")); } catch { return null; }
+};
+
+const isOpenSource = (root: string): boolean => {
+  if (existsSync(path.join(root, "LICENSE"))) return true;
+  const pkg = packageJson(root);
+  if (pkg && !pkg.private) return true; // I2: missing `private` = public (npm default)
+  return path.basename(root) === "workflow-toolkit";
+};
+
+const licenseHolder = (root: string): string => {
+  const pkg = packageJson(root);
+  if (pkg) {
+    const author = pkg.author;
+    if (typeof author === "string" && author.trim()) return author.trim();
+    if (author && typeof author === "object") {
+      const name = (author as Record<string, unknown>).name;
+      if (typeof name === "string" && name.trim()) return name.trim();
+    }
+  }
+  return "";
+};
+
+export const hygieneFiles = (root: string): { state: Record<HygieneFile, State>; openSource: boolean } => {
+  const openSource = isOpenSource(root);
+  const state = {} as Record<HygieneFile, State>;
+  for (const file of ["CHANGELOG.md", "README.md", ".editorconfig", ".gitattributes", "LICENSE", "CONTRIBUTING.md"] as HygieneFile[]) {
+    if (file === "LICENSE" || file === "CONTRIBUTING.md") {
+      state[file] = openSource ? (existsSync(path.join(root, file)) ? "ok" : "missing") : "skip";
+      continue;
+    }
+    if (!existsSync(path.join(root, file))) { state[file] = "missing"; continue; }
+    if (file === "CHANGELOG.md") {
+      const stats = changelogUnreleasedStats(root);
+      state[file] = stats.exists && stats.has_unreleased ? "ok" : "invalid";
+      continue;
+    }
+    state[file] = "ok";
+  }
+  return { state, openSource };
+};
+
+export const ensureHygieneFiles = (
+  root: string,
+  opts: { confirmed: boolean; includeOpenSource?: boolean },
+): { ok: true; created: string[] } | { ok: false; error: string } => {
+  if (!opts.confirmed) return { ok: false, error: "confirmed: true required" };
+  const files = ["CHANGELOG.md", "README.md", ".editorconfig", ".gitattributes"] as HygieneFile[];
+  if (opts.includeOpenSource) files.push("LICENSE", "CONTRIBUTING.md");
+  const created: string[] = [];
+  const tplDir = templatesDir();
+  for (const file of files) {
+    if (existsSync(path.join(root, file))) continue;
+    const tpl = path.join(tplDir, file);
+    if (!existsSync(tpl)) continue; // skip missing template, never fail
+    const content = readFileSync(tpl, "utf8")
+      .replace(/<PROJECT>/g, path.basename(root))
+      .replace(/<YEAR>/g, String(new Date().getFullYear()))
+      .replace(/<HOLDER>\s*/g, licenseHolder(root));
+    writeFileSync(path.join(root, file), content, "utf8");
+    created.push(file);
+  }
+  return { ok: true, created };
+};