schub 0.1.0

package/src/index.ts

@@ -0,0 +1,458 @@
+#!/usr/bin/env bun
+import { dirname } from "node:path";
+import { spawnSync } from "bun";
+import { render } from "ink";
+import React from "react";
+import App from "./App";
+import { createChange, resolveChangeRoot } from "./changes";
+import { createTask, findSchubRoot, listTasks, TASK_STATUSES, type TaskStatus } from "./features/tasks";
+import { createProject } from "./project";
+import { applyTerminalPrelude, applyTerminalReset } from "./terminal";
+
+const HELP_TEXT = `schub [command]
+
+Commands:
+  changes create   Create a change proposal
+  project create   Create project docs
+  tasks create     Create task files for a change
+  tasks list       List tasks
+  lint              Run Biome lint checks
+  format            Format files with Biome
+  ui                Launch the interactive dashboard
+`;
+
+const getStartDir = (): string => process.env.SCHUB_CWD ?? process.cwd();
+
+const getWorkspaceRoot = (): string => {
+  const schubDir = findSchubRoot(getStartDir());
+  return schubDir ? dirname(schubDir) : getStartDir();
+};
+
+const resolveSchubDir = (): string | null => findSchubRoot(getStartDir());
+
+const printHelp = (exitCode = 0): void => {
+  process.stdout.write(`${HELP_TEXT}\n`);
+  process.exitCode = exitCode;
+};
+
+const parseStatusFilter = (value: string | undefined): TaskStatus[] => {
+  if (!value) {
+    return [...TASK_STATUSES];
+  }
+
+  const normalized = value
+    .split(",")
+    .map((status) => status.trim().toLowerCase())
+    .filter(Boolean);
+
+  const allowed = new Set(TASK_STATUSES);
+  const invalid = normalized.filter((status) => !allowed.has(status as TaskStatus));
+  if (invalid.length > 0) {
+    throw new Error(`Unknown status filter: ${invalid.join(", ")}`);
+  }
+
+  return normalized as TaskStatus[];
+};
+
+type TaskListOptions = {
+  statuses: TaskStatus[];
+  json: boolean;
+};
+
+const parseTaskListOptions = (args: string[]): TaskListOptions => {
+  let statusValue: string | undefined;
+  let json = false;
+  const unknown: string[] = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--json") {
+      json = true;
+      continue;
+    }
+    if (arg === "--status") {
+      statusValue = args[index + 1];
+      if (!statusValue) {
+        throw new Error("Missing value for --status.");
+      }
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--status=")) {
+      statusValue = arg.slice("--status=".length);
+      continue;
+    }
+    unknown.push(arg);
+  }
+
+  if (unknown.length > 0) {
+    throw new Error(`Unknown option(s): ${unknown.join(", ")}`);
+  }
+
+  return { statuses: parseStatusFilter(statusValue), json };
+};
+
+type ChangeCreateOptions = {
+  changeId?: string;
+  title?: string;
+  input?: string;
+  overwrite: boolean;
+};
+
+type ProjectCreateOptions = {
+  repoRoot?: string;
+  projectName?: string;
+  overwrite: boolean;
+};
+
+const parseChangeCreateOptions = (args: string[]) => {
+  let changeId: string | undefined;
+  let title: string | undefined;
+  let input: string | undefined;
+  let overwrite = false;
+  const unknown: string[] = [];
+
+  const rejectUnsupported = (flag: string) => {
+    throw new Error(`Unsupported option: ${flag}.`);
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--overwrite") {
+      overwrite = true;
+      continue;
+    }
+    if (arg === "--change-id") {
+      changeId = args[index + 1];
+      if (changeId === undefined) {
+        throw new Error("Missing value for --change-id.");
+      }
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--change-id=")) {
+      changeId = arg.slice("--change-id=".length);
+      continue;
+    }
+    if (arg === "--title") {
+      title = args[index + 1];
+      if (title === undefined) {
+        throw new Error("Missing value for --title.");
+      }
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--title=")) {
+      title = arg.slice("--title=".length);
+      continue;
+    }
+    if (arg === "--input") {
+      input = args[index + 1];
+      if (input === undefined) {
+        throw new Error("Missing value for --input.");
+      }
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--input=")) {
+      input = arg.slice("--input=".length);
+      continue;
+    }
+    if (arg === "--schub-root" || arg === "--agent-root") {
+      rejectUnsupported(arg);
+    }
+    if (arg.startsWith("--schub-root=")) {
+      rejectUnsupported("--schub-root");
+    }
+    if (arg.startsWith("--agent-root=")) {
+      rejectUnsupported("--agent-root");
+    }
+    unknown.push(arg);
+  }
+
+  if (unknown.length > 0) {
+    throw new Error(`Unknown option(s): ${unknown.join(", ")}`);
+  }
+
+  const options: ChangeCreateOptions = { changeId, title, input, overwrite };
+  return options;
+};
+
+const parseProjectCreateOptions = (args: string[]) => {
+  let repoRoot: string | undefined;
+  let projectName: string | undefined;
+  let overwrite = false;
+  const unknown: string[] = [];
+
+  const rejectUnsupported = (flag: string) => {
+    throw new Error(`Unsupported option: ${flag}.`);
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--overwrite") {
+      overwrite = true;
+      continue;
+    }
+    if (arg === "--repo-root") {
+      repoRoot = args[index + 1];
+      if (repoRoot === undefined) {
+        throw new Error("Missing value for --repo-root.");
+      }
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--repo-root=")) {
+      repoRoot = arg.slice("--repo-root=".length);
+      continue;
+    }
+    if (arg === "--project-name") {
+      projectName = args[index + 1];
+      if (projectName === undefined) {
+        throw new Error("Missing value for --project-name.");
+      }
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--project-name=")) {
+      projectName = arg.slice("--project-name=".length);
+      continue;
+    }
+    if (arg === "--schub-root" || arg === "--agent-root") {
+      rejectUnsupported(arg);
+    }
+    if (arg.startsWith("--schub-root=")) {
+      rejectUnsupported("--schub-root");
+    }
+    if (arg.startsWith("--agent-root=")) {
+      rejectUnsupported("--agent-root");
+    }
+    unknown.push(arg);
+  }
+
+  if (unknown.length > 0) {
+    throw new Error(`Unknown option(s): ${unknown.join(", ")}`);
+  }
+
+  return { repoRoot, projectName, overwrite };
+};
+
+type TaskCreateOptions = {
+  changeId: string;
+  status?: string;
+  titles: string[];
+  overwrite: boolean;
+};
+
+const parseTaskCreateOptions = (args: string[]) => {
+  let changeId: string | undefined;
+  let status: string | undefined;
+  let overwrite = false;
+  const titles: string[] = [];
+  const unknown: string[] = [];
+
+  const rejectUnsupported = (flag: string) => {
+    throw new Error(`Unsupported option: ${flag}.`);
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--overwrite") {
+      overwrite = true;
+      continue;
+    }
+    if (arg === "--change-id") {
+      changeId = args[index + 1];
+      if (changeId === undefined) {
+        throw new Error("Missing value for --change-id.");
+      }
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--change-id=")) {
+      changeId = arg.slice("--change-id=".length);
+      continue;
+    }
+    if (arg === "--status") {
+      status = args[index + 1];
+      if (status === undefined) {
+        throw new Error("Missing value for --status.");
+      }
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--status=")) {
+      status = arg.slice("--status=".length);
+      continue;
+    }
+    if (arg === "--title") {
+      const title = args[index + 1];
+      if (title === undefined) {
+        throw new Error("Missing value for --title.");
+      }
+      titles.push(title);
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--title=")) {
+      titles.push(arg.slice("--title=".length));
+      continue;
+    }
+    if (arg === "--schub-root" || arg === "--agent-root") {
+      rejectUnsupported(arg);
+    }
+    if (arg.startsWith("--schub-root=")) {
+      rejectUnsupported("--schub-root");
+    }
+    if (arg.startsWith("--agent-root=")) {
+      rejectUnsupported("--agent-root");
+    }
+    unknown.push(arg);
+  }
+
+  if (unknown.length > 0) {
+    throw new Error(`Unknown option(s): ${unknown.join(", ")}`);
+  }
+
+  if (!changeId) {
+    throw new Error("Provide --change-id.");
+  }
+
+  const options: TaskCreateOptions = { changeId, status, titles, overwrite };
+  return options;
+};
+
+const runTasksList = (args: string[]): void => {
+  const schubDir = resolveSchubDir();
+  if (!schubDir) {
+    throw new Error("No .schub directory found.");
+  }
+
+  const options = parseTaskListOptions(args);
+  const tasks = listTasks(schubDir, options.statuses);
+
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(tasks, null, 2)}\n`);
+    return;
+  }
+
+  const lines = tasks.map((task) => `${task.id} ${task.title} (${task.status})`);
+  process.stdout.write(`${lines.join("\n")}\n`);
+};
+
+const runTasksCreate = (args: string[]) => {
+  const options = parseTaskCreateOptions(args);
+  const schubDir = resolveChangeRoot(getStartDir());
+  const created = createTask(schubDir, options);
+
+  for (const taskPath of created) {
+    process.stdout.write(`[OK] Wrote task: ${taskPath}\n`);
+  }
+};
+
+const runBiome = (command: "lint" | "format"): void => {
+  const workspaceRoot = getWorkspaceRoot();
+  const biomeArgs = command === "lint" ? ["lint", "."] : ["format", ".", "--write"];
+  const result = spawnSync({
+    cmd: ["bunx", "@biomejs/biome", ...biomeArgs],
+    cwd: workspaceRoot,
+    env: process.env,
+  });
+
+  if (result.stdout && result.stdout.length > 0) {
+    process.stdout.write(result.stdout);
+  }
+
+  if (result.stderr && result.stderr.length > 0) {
+    process.stderr.write(result.stderr);
+  }
+
+  process.exitCode = result.exitCode ?? 1;
+};
+
+const runChangesCreate = (args: string[]) => {
+  const options = parseChangeCreateOptions(args);
+  const schubDir = resolveChangeRoot(getStartDir());
+  const proposalPath = createChange(schubDir, options);
+  process.stdout.write(`[OK] Wrote proposal: ${proposalPath}\n`);
+};
+
+const runProjectCreate = (args: string[]) => {
+  const options = parseProjectCreateOptions(args);
+  const outputs = createProject(getStartDir(), options);
+
+  for (const output of outputs) {
+    process.stdout.write(`[OK] Wrote ${output}\n`);
+  }
+};
+
+const registerTerminalReset = () => {
+  process.once("exit", () => {
+    applyTerminalReset();
+  });
+};
+
+const runUi = () => {
+  applyTerminalPrelude();
+  registerTerminalReset();
+  render(React.createElement(App));
+};
+
+const runCommand = (): void => {
+  const args = process.argv.slice(2);
+  if (args.length === 0) {
+    runUi();
+    return;
+  }
+
+  if (args.includes("--help") || args.includes("-h")) {
+    printHelp();
+    return;
+  }
+
+  const [primary, secondary, ...rest] = args;
+
+  switch (primary) {
+    case "changes":
+      if (secondary === "create") {
+        runChangesCreate(rest);
+        return;
+      }
+      break;
+    case "project":
+      if (secondary === "create") {
+        runProjectCreate(rest);
+        return;
+      }
+      break;
+    case "tasks":
+      if (secondary === "list") {
+        runTasksList(rest);
+        return;
+      }
+      if (secondary === "create") {
+        runTasksCreate(rest);
+        return;
+      }
+      break;
+    case "lint":
+      runBiome("lint");
+      return;
+    case "format":
+      runBiome("format");
+      return;
+    case "ui":
+      runUi();
+      return;
+  }
+
+  printHelp(1);
+};
+
+try {
+  runCommand();
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`${message}\n`);
+  process.exitCode = 1;
+}

package/src/project.ts

@@ -0,0 +1,96 @@
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+type ProjectCreateOptions = {
+  repoRoot?: string;
+  projectName?: string;
+  overwrite?: boolean;
+};
+
+const TEMPLATE_FILES = {
+  "project-overview.md": "project-overview-template.md",
+  "project-setup.md": "project-setup-template.md",
+  "project-wow.md": "project-wow-template.md",
+};
+
+const TEMPLATES_ROOT = fileURLToPath(new URL("../templates/setup-project", import.meta.url));
+
+const isDirectory = (path: string) => {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+};
+
+const resolveSchubRoot = (startDir: string) => {
+  let current = resolve(startDir);
+  const fallback = join(current, ".schub");
+
+  while (true) {
+    if (basename(current) === ".schub" && isDirectory(current)) {
+      return current;
+    }
+
+    const candidate = join(current, ".schub");
+    if (isDirectory(candidate)) {
+      return candidate;
+    }
+
+    const parent = dirname(current);
+    if (parent === current) {
+      return fallback;
+    }
+    current = parent;
+  }
+};
+
+const readTemplate = (path: string) => {
+  try {
+    return readFileSync(path, "utf8");
+  } catch {
+    throw new Error(`[ERROR] Template not found: ${path}`);
+  }
+};
+
+const writeOutput = (path: string, content: string, overwrite: boolean) => {
+  if (existsSync(path) && !overwrite) {
+    throw new Error(`[ERROR] Refusing to overwrite existing file: ${path}`);
+  }
+
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content, "utf8");
+};
+
+const deriveProjectName = (repoRoot: string) => {
+  const name = basename(repoRoot).trim();
+  return name || "Project";
+};
+
+const resolveRepoRoot = (startDir: string, schubRoot: string, repoRoot?: string) => {
+  if (repoRoot) {
+    return resolve(startDir, repoRoot);
+  }
+
+  return resolve(schubRoot, "..");
+};
+
+export const createProject = (startDir: string, options: ProjectCreateOptions) => {
+  const schubRoot = resolveSchubRoot(startDir);
+  const repoRoot = resolveRepoRoot(startDir, schubRoot, options.repoRoot);
+  const projectName = options.projectName || deriveProjectName(repoRoot);
+  const overwrite = options.overwrite ?? false;
+  const created: string[] = [];
+
+  for (const [outputName, templateName] of Object.entries(TEMPLATE_FILES)) {
+    const templatePath = join(TEMPLATES_ROOT, templateName);
+    const template = readTemplate(templatePath);
+    const rendered = template.split("[Project Name]").join(projectName);
+    const outputPath = join(schubRoot, outputName);
+    writeOutput(outputPath, rendered, overwrite);
+    created.push(outputPath);
+  }
+
+  return created;
+};

package/src/tasks.ts

@@ -0,0 +1,15 @@
+export {
+  buildTaskGraph,
+  findSchubRoot,
+  listTasks,
+  loadTaskDependencies,
+  renderTaskGraphLines,
+  TASK_STATUSES,
+  type TaskDependency,
+  type TaskGraph,
+  type TaskGraphLine,
+  type TaskGraphNode,
+  type TaskInfo,
+  type TaskStatus,
+  trimTaskTitle,
+} from "./features/tasks";

package/src/terminal.ts

@@ -0,0 +1,16 @@
+const CLEAR_SCROLLBACK = "\u001b[3J";
+const CLEAR_SCREEN = "\u001b[2J";
+const CURSOR_HOME = "\u001b[H";
+const BLACK_BACKGROUND = "\u001b[40m";
+const RESET = "\u001b[0m";
+
+export const terminalPrelude = `${CLEAR_SCROLLBACK}${CLEAR_SCREEN}${CURSOR_HOME}${BLACK_BACKGROUND}`;
+export const terminalReset = RESET;
+
+export const applyTerminalPrelude = () => {
+  process.stdout.write(terminalPrelude);
+};
+
+export const applyTerminalReset = () => {
+  process.stdout.write(terminalReset);
+};

package/templates/create-proposal/adr-template.md

@@ -0,0 +1,51 @@
+# ADR: [TITLE]
+
+**Status**: [Proposed | Accepted | Deprecated | Superseded]  
+**Date**: [YYYY-MM-DD]  
+**Related**: [PR link, spec link, plan link, issue link]
+
+> Use ADRs to capture the **WHY**, not the implementation details.
+> Keep it short and specific: context → decision → rationale → consequences.
+
+## Context
+
+[What problem are we solving? What constraints, requirements, or incidents led here?]
+
+## Decision
+
+[What are we choosing to do? Be explicit and testable.]
+
+## Rationale
+
+[Why this decision? Include tradeoffs and decision drivers.]
+
+## Alternatives Considered
+
+1. **[Alternative A]**: [why rejected]
+2. **[Alternative B]**: [why rejected]
+
+## Consequences
+
+### Positive
+
+- [What gets better?]
+
+### Negative / Risks
+
+- [What gets worse or harder?]
+
+## Migration / Rollout Plan
+
+[How do we move from the current state to the decided state? Include any sequencing.]
+
+## Verification & Evidence
+
+_Goal: the decision’s impact is verifiable by an LLM through execution + concrete outputs._
+
+- **Commands to run**: [exact commands]
+- **Expected evidence**: [logs, HTTP responses, screenshots/videos/traces, artifacts]
+- **Where to find artifacts**: [paths, URLs, container/log sources]
+
+## Follow-ups
+
+- [TODO items, owners, deadlines]

package/templates/create-proposal/proposal-template.md

@@ -0,0 +1,51 @@
+# Proposal - {{CHANGE_TITLE}}
+
+**Change ID**: `{{CHANGE_ID}}`
+**Created**: {{DATE}}
+**Status**: Draft
+**Input**: {{INPUT}}
+
+## Summary
+
+[1–3 sentences describing the change and the user-visible outcome.]
+
+## Why
+
+[Problem/opportunity + motivation. What’s broken/missing today? Why now?]
+
+## Goals
+
+- [Outcome 1]
+- [Outcome 2]
+
+### Non-Goals
+
+- [What is explicitly not included]
+
+## User Scenarios & Acceptance
+
+### Scenario 1 — [Title] (Priority: P1)
+
+> **Given** [state], **When** [action], **Then** [outcome]
+
+### Scenario 2 — [Title] (Priority: P2)
+
+> **Given** [state], **When** [action], **Then** [outcome]
+
+## Implementation Outline
+
+1. [Phase 1]
+2. [Phase 2]
+
+## Change Touch Points
+
+- [Exact paths, systems, or components touched]
+
+## Assumptions
+
+- A1: [Assumption]
+- A2: [Assumption]
+
+## Potential Issues
+
+- [List potential issues, conflicts, discrepancies, risks]