itsvertical 0.0.1 → 0.0.3

package/README.md

@@ -2,7 +2,9 @@
 
 **Tickets pile up, scopes get done. Project work isn't linear, it's Vertical.**
 
-Vertical is a file-based project management tool built around the nine-box grid. No accounts, no cloud, no setup. Just a `.vertical` file and your terminal.
+Vertical is a file-based project management tool that organizes work into vertical slices that can each be completed independently. No accounts, no cloud, no setup. Just a `.vertical` file and your terminal.
+
+![Vertical board](app/images/screenshot.png)
 
 ```
 npx itsvertical new my-project.vertical "My Project"
@@ -10,13 +12,13 @@ npx itsvertical new my-project.vertical "My Project"
 
 ## Built for AI agents
 
-Vertical is designed to be used through AI coding agents like [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview). The CLI is the primary interface — every entity is addressed by ID, every command accepts `--json` for structured output, and errors are machine-readable. An agent can create a project, break work into scopes, add tasks, and track progress — all through the command line.
+Vertical is designed to be used through AI coding agents. The CLI is the primary interface — every entity is addressed by ID, every command accepts `--json` for structured output, and errors are machine-readable. An agent can create a project, break work into slices, add tasks, and track progress — all through the command line.
 
 The browser UI (`itsvertical open`) is there for when you want to see the board visually, drag things around, or get a quick overview.
 
 ## How it works
 
-Vertical organizes work into a 3x3 grid of boxes. Each box can hold tasks, and each box can be split into layers (steps). Tasks move between boxes, layers break work into phases, and things get marked done as you go.
+Each slice is a box on the board. Add tasks to a box, and split it into layers when the work has distinct phases — design then build, for example. Slices get completed independently. Layers break the work within a slice into steps.
 
 Everything is saved to a single `.vertical` file. Version it with git, share it with teammates, or let your agent manage it.
 
@@ -32,6 +34,16 @@ Or run directly with npx:
 npx itsvertical new my-project.vertical "My Project"
 ```
 
+### Agent skill
+
+Install the [Vertical skill](https://skills.sh/seasonedcc/vertical/vertical) to teach your AI agent how to use Vertical:
+
+```
+npx skills add seasonedcc/vertical
+```
+
+This gives agents like Claude Code, Cursor, and GitHub Copilot procedural knowledge of all Vertical commands and workflows.
+
 ## Commands
 
 All entities are addressed by ID. Use `itsvertical show` to see IDs. Every command accepts `--json` to output the full board state as JSON (useful for agents).
@@ -44,6 +56,7 @@ itsvertical open <file>                         # Open in the browser UI
 itsvertical show <file>                         # Print the board to the terminal
 itsvertical show <file> --json                  # Output the board as JSON
 itsvertical show <file> --box <slice-id>        # Show only a specific box
+itsvertical show <file> --visual               # Show the board as a visual 3x3 grid with summary
 itsvertical rename <file> <name>                # Rename the project
 ```
 
@@ -82,9 +95,9 @@ itsvertical layer status <file> <layer-id> none # Clear status
 
 `itsvertical open` starts a local server and opens the board in your browser. Click **Save** or press **Ctrl+S** / **Cmd+S** to write changes back to the file.
 
-## The nine-box grid
+## The board
 
-The board is a 3x3 grid. Each box represents a scope of work.
+Each box represents a vertical slice of work.
 
 - **Name boxes** by clicking the title area
 - **Drag boxes** to rearrange them in the grid
@@ -129,7 +142,7 @@ Source at [github.com/seasonedcc/vertical](https://github.com/seasonedcc/vertica
 
 The package has two parts:
 
-- **SPA** (`app/`) — A React app built with Vite. This is the nine-box board UI. Built to `dist/`.
+- **SPA** (`app/`) — A React app built with Vite. The board UI. Built to `dist/`.
 - **CLI** (`cli/`) — A Node.js CLI built with tsup. Starts a local HTTP server that serves the SPA and provides a read/write API for the `.vertical` file. Built to `cli/dist/`.
 
 The CLI and SPA share code: types (`app/state/types.ts`), serialization (`app/file/format.ts`), and project creation (`app/state/initial-state.ts`).

package/cli/dist/index.js

@@ -1219,8 +1219,8 @@ var Promise2 = getNative_default(root_default, "Promise");
 var Promise_default = Promise2;
 
 // node_modules/.pnpm/lodash-es@4.17.23/node_modules/lodash-es/_Set.js
-var Set = getNative_default(root_default, "Set");
-var Set_default = Set;
+var Set2 = getNative_default(root_default, "Set");
+var Set_default = Set2;
 
 // node_modules/.pnpm/lodash-es@4.17.23/node_modules/lodash-es/_getTag.js
 var mapTag2 = "[object Map]";
@@ -1921,10 +1921,306 @@ function fail(message, json) {
   process.exit(1);
 }
 
+// cli/board.ts
+var MIN_COL_WIDTH = 25;
+var MAX_COL_WIDTH = 40;
+var PADDING = 2;
+var ansi = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  dim: "\x1B[2m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m",
+  cyan: "\x1B[36m"
+};
+function style(text, ...codes) {
+  return `${codes.join("")}${text}${ansi.reset}`;
+}
+var ANSI_PATTERN = new RegExp(`${"\x1B"}\\[[0-9;]*m`, "g");
+function stripAnsi(text) {
+  return text.replace(ANSI_PATTERN, "");
+}
+function visibleLength(text) {
+  return stripAnsi(text).length;
+}
+function truncateStyled(text, maxWidth) {
+  if (visibleLength(text) <= maxWidth)
+    return text;
+  let visible = 0;
+  let i = 0;
+  while (i < text.length && visible < maxWidth - 1) {
+    if (text[i] === "\x1B") {
+      const end = text.indexOf("m", i);
+      i = end + 1;
+      continue;
+    }
+    visible++;
+    i++;
+  }
+  return `${text.slice(0, i)}${ansi.reset}\u2026`;
+}
+function padRightStyled(text, width) {
+  const padding = Math.max(0, width - visibleLength(text));
+  return text + " ".repeat(padding);
+}
+function getSliceLayers(state, slice) {
+  return sortBy_default(
+    state.layers.filter((l) => l.sliceId === slice.id),
+    "sorting"
+  );
+}
+function getLayerTasks(state, layer2) {
+  return sortBy_default(
+    state.tasks.filter((t) => t.layerId === layer2.id),
+    "sorting"
+  );
+}
+function getSliceTasks(state, slice) {
+  const layers = getSliceLayers(state, slice);
+  return layers.flatMap((l) => getLayerTasks(state, l));
+}
+function buildCellLines(state, slice, innerWidth) {
+  const lines = [];
+  const layers = getSliceLayers(state, slice);
+  const allTasks = getSliceTasks(state, slice);
+  const hasMultipleLayers = layers.length > 1;
+  const separator = style("\u2504".repeat(innerWidth), ansi.dim);
+  if (slice.name) {
+    lines.push(style(slice.name, ansi.bold, ansi.cyan));
+  }
+  if (allTasks.length === 0) {
+    lines.push(style("(no tasks)", ansi.dim));
+    return lines;
+  }
+  for (let i = 0; i < layers.length; i++) {
+    const layer2 = layers[i];
+    const tasks = getLayerTasks(state, layer2);
+    if (hasMultipleLayers && i > 0) {
+      lines.push(separator);
+    }
+    if (hasMultipleLayers) {
+      const layerName = layer2.name ?? `Layer ${i + 1}`;
+      if (layer2.status === "done") {
+        lines.push(style(`\u2713 ${layerName} (done)`, ansi.green));
+      } else {
+        lines.push(style(layerName, ansi.bold));
+      }
+    }
+    for (const task2 of tasks) {
+      if (task2.done) {
+        lines.push(`  ${style("\u25CF", ansi.green)} ${style(task2.name, ansi.dim)}`);
+      } else {
+        lines.push(`  ${style("\u25CB", ansi.yellow)} ${task2.name}`);
+      }
+    }
+  }
+  return lines;
+}
+function showBoardGrid(state, boxId) {
+  const sortedSlices = sortBy_default(state.slices, "boxNumber");
+  const filteredSlices = boxId ? sortedSlices.filter((s) => s.id === boxId) : sortedSlices;
+  const colWidth = Math.min(
+    MAX_COL_WIDTH,
+    Math.max(
+      MIN_COL_WIDTH,
+      ...filteredSlices.flatMap((slice) => {
+        const layers = getSliceLayers(state, slice);
+        const tasks = getSliceTasks(state, slice);
+        const widths = [
+          slice.name?.length ?? 0,
+          ...layers.map((l) => (l.name?.length ?? 0) + 10),
+          ...tasks.map((t) => t.name.length + 4)
+        ];
+        return widths;
+      }).map((w) => w + PADDING * 2)
+    )
+  );
+  const innerWidth = colWidth - PADDING * 2;
+  const numCols = boxId ? 1 : 3;
+  const cellContents = /* @__PURE__ */ new Map();
+  for (const slice of filteredSlices) {
+    cellContents.set(slice.id, buildCellLines(state, slice, innerWidth));
+  }
+  const rows = [];
+  if (boxId) {
+    rows.push(filteredSlices);
+  } else {
+    rows.push(
+      filteredSlices.filter((s) => s.boxNumber >= 1 && s.boxNumber <= 3)
+    );
+    rows.push(
+      filteredSlices.filter((s) => s.boxNumber >= 4 && s.boxNumber <= 6)
+    );
+    rows.push(
+      filteredSlices.filter((s) => s.boxNumber >= 7 && s.boxNumber <= 9)
+    );
+  }
+  console.log(style(state.project.name, ansi.bold));
+  console.log();
+  const border = (text) => style(text, ansi.dim);
+  const makeBorder = (left, mid2, right) => {
+    const parts = [];
+    for (let c = 0; c < numCols; c++) {
+      parts.push("\u2500".repeat(colWidth));
+    }
+    return border(left + parts.join(mid2) + right);
+  };
+  const top = makeBorder("\u250C", "\u252C", "\u2510");
+  const mid = makeBorder("\u251C", "\u253C", "\u2524");
+  const bot = makeBorder("\u2514", "\u2534", "\u2518");
+  for (let r = 0; r < rows.length; r++) {
+    const row = rows[r];
+    console.log(r === 0 ? top : mid);
+    const cellLines = row.map((slice) => cellContents.get(slice.id) ?? []);
+    const rowHeight = Math.max(3, ...cellLines.map((l) => l.length + 2));
+    for (let line = 0; line < rowHeight; line++) {
+      let output2 = border("\u2502");
+      for (let c = 0; c < numCols; c++) {
+        const lines = cellLines[c] ?? [];
+        const contentLine = line - 1;
+        let content = "";
+        if (contentLine >= 0 && contentLine < lines.length) {
+          content = truncateStyled(lines[contentLine], innerWidth);
+        }
+        output2 += `${" ".repeat(PADDING) + padRightStyled(content, innerWidth) + " ".repeat(PADDING)}${border("\u2502")}`;
+      }
+      console.log(output2);
+    }
+  }
+  console.log(bot);
+  const totalTasks = state.tasks.length;
+  const doneTasks = state.tasks.filter((t) => t.done).length;
+  const progressColor = doneTasks === totalTasks ? ansi.green : ansi.yellow;
+  console.log();
+  console.log(
+    `${style("Progress:", ansi.bold)} ${style(`${doneTasks}/${totalTasks}`, ansi.bold, progressColor)} tasks done`
+  );
+}
+function formatGroupLabel(boxNumbers) {
+  if (boxNumbers.length === 0)
+    return "";
+  if (boxNumbers.length === 1)
+    return `Box ${boxNumbers[0]}`;
+  const ranges = [];
+  let start = boxNumbers[0];
+  let end = boxNumbers[0];
+  for (let i = 1; i < boxNumbers.length; i++) {
+    if (boxNumbers[i] === end + 1) {
+      end = boxNumbers[i];
+    } else {
+      ranges.push(start === end ? `${start}` : `${start}\u2013${end}`);
+      start = boxNumbers[i];
+      end = boxNumbers[i];
+    }
+  }
+  ranges.push(start === end ? `${start}` : `${start}\u2013${end}`);
+  return `Boxes ${ranges.join(", ")}`;
+}
+function buildStatusText(state, slice) {
+  const layers = getSliceLayers(state, slice);
+  const tasks = getSliceTasks(state, slice);
+  if (tasks.length === 0)
+    return style("No tasks yet", ansi.dim);
+  const doneTasks = tasks.filter((t) => t.done).length;
+  const totalTasks = tasks.length;
+  if (doneTasks === totalTasks)
+    return style("All done", ansi.green);
+  if (layers.length > 1) {
+    const doneLayerNames = layers.filter((l) => l.status === "done").map((l) => {
+      const idx = layers.indexOf(l);
+      return l.name ?? `Layer ${idx + 1}`;
+    });
+    const openCount = totalTasks - doneTasks;
+    const parts = [];
+    if (doneLayerNames.length > 0) {
+      parts.push(`${doneLayerNames.join(", ")} marked done`);
+    }
+    if (openCount > 0) {
+      parts.push(`${openCount} task${openCount === 1 ? "" : "s"} still open`);
+    }
+    return parts.join(", ");
+  }
+  return `${doneTasks}/${totalTasks} tasks done`;
+}
+function showSummaryTable(state, boxId) {
+  const sortedSlices = sortBy_default(state.slices, "boxNumber");
+  const filteredSlices = boxId ? sortedSlices.filter((s) => s.id === boxId) : sortedSlices;
+  const summaryRows = [];
+  const unnamedEmpty = [];
+  for (const slice of filteredSlices) {
+    const tasks = getSliceTasks(state, slice);
+    if (!slice.name && tasks.length === 0) {
+      unnamedEmpty.push(slice.boxNumber);
+      continue;
+    }
+    const doneTasks = tasks.filter((t) => t.done).length;
+    const doneColor = tasks.length > 0 && doneTasks === tasks.length ? ansi.green : ansi.yellow;
+    summaryRows.push({
+      scope: style(slice.name ?? `Box ${slice.boxNumber}`, ansi.bold),
+      done: tasks.length > 0 ? style(`${doneTasks}/${tasks.length}`, doneColor) : style("\u2014", ansi.dim),
+      status: buildStatusText(state, slice)
+    });
+  }
+  if (unnamedEmpty.length > 0) {
+    summaryRows.push({
+      scope: style(formatGroupLabel(unnamedEmpty), ansi.dim),
+      done: style("\u2014", ansi.dim),
+      status: style("Unnamed & empty", ansi.dim)
+    });
+  }
+  if (summaryRows.length === 0)
+    return;
+  const headers = {
+    scope: style("Scope", ansi.bold),
+    done: style("Done", ansi.bold),
+    status: style("Status", ansi.bold)
+  };
+  const scopeWidth = Math.max(
+    visibleLength(headers.scope),
+    ...summaryRows.map((r) => visibleLength(r.scope))
+  );
+  const doneWidth = Math.max(
+    visibleLength(headers.done),
+    ...summaryRows.map((r) => visibleLength(r.done))
+  );
+  const statusWidth = Math.max(
+    visibleLength(headers.status),
+    ...summaryRows.map((r) => visibleLength(r.status))
+  );
+  const pad = (text, width) => ` ${padRightStyled(text, width)} `;
+  const centerPad = (text, width) => {
+    const totalPad = width - visibleLength(text);
+    const left = Math.floor(totalPad / 2);
+    const right = totalPad - left;
+    return ` ${" ".repeat(left)}${text}${" ".repeat(right)} `;
+  };
+  const border = (text) => style(text, ansi.dim);
+  const hLine = (left, mid, right) => border(
+    `${left}${"\u2500".repeat(scopeWidth + 2)}${mid}${"\u2500".repeat(doneWidth + 2)}${mid}${"\u2500".repeat(statusWidth + 2)}${right}`
+  );
+  console.log();
+  console.log(hLine("\u250C", "\u252C", "\u2510"));
+  console.log(
+    `${border("\u2502")}${centerPad(headers.scope, scopeWidth)}${border("\u2502")}${centerPad(headers.done, doneWidth)}${border("\u2502")}${centerPad(headers.status, statusWidth)}${border("\u2502")}`
+  );
+  console.log(hLine("\u251C", "\u253C", "\u2524"));
+  for (let i = 0; i < summaryRows.length; i++) {
+    const row = summaryRows[i];
+    console.log(
+      `${border("\u2502")}${pad(row.scope, scopeWidth)}${border("\u2502")}${pad(row.done, doneWidth)}${border("\u2502")}${pad(row.status, statusWidth)}${border("\u2502")}`
+    );
+    if (i < summaryRows.length - 1) {
+      console.log(hLine("\u251C", "\u253C", "\u2524"));
+    }
+  }
+  console.log(hLine("\u2514", "\u2534", "\u2518"));
+}
+
 // cli/server.ts
 import fs2 from "fs";
 import http from "http";
 import path2 from "path";
+import readline from "readline";
 import { fileURLToPath } from "url";
 import getPort from "get-port";
 import open from "open";
@@ -1969,9 +2265,24 @@ function readRequestBody(req) {
     req.on("error", reject);
   });
 }
+function confirm(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  rl.on("error", () => {
+  });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.toLowerCase() === "y");
+    });
+  });
+}
 async function startServer(filePath) {
   const absoluteFilePath = path2.resolve(filePath);
   const distPath = getDistPath();
+  let browserDirty = false;
   if (!fs2.existsSync(distPath)) {
     console.error(
       "Error: dist/ directory not found. Run `pnpm run build` first."
@@ -1993,6 +2304,23 @@ async function startServer(filePath) {
       res.end('{"ok":true}');
       return;
     }
+    if (url2 === "/api/events" && req.method === "GET") {
+      res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        Connection: "keep-alive"
+      });
+      sseClients.add(res);
+      req.on("close", () => sseClients.delete(res));
+      return;
+    }
+    if (url2 === "/api/dirty" && req.method === "POST") {
+      const body = await readRequestBody(req);
+      browserDirty = JSON.parse(body).dirty;
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end('{"ok":true}');
+      return;
+    }
     if (serveStaticFile(res, distPath, url2))
       return;
     const indexPath = path2.join(distPath, "index.html");
@@ -2006,6 +2334,12 @@ async function startServer(filePath) {
   });
   const port = await getPort();
   const url = `http://localhost:${port}`;
+  const sseClients = /* @__PURE__ */ new Set();
+  fs2.watch(absoluteFilePath, () => {
+    for (const client of sseClients) {
+      client.write("data: file-changed\n\n");
+    }
+  });
   server.listen(port, () => {
     console.log(`
   Vertical is running at ${url}`);
@@ -2013,6 +2347,22 @@ async function startServer(filePath) {
     console.log("  Press Ctrl+C to stop\n");
     open(url);
   });
+  process.on("SIGINT", async () => {
+    if (browserDirty) {
+      try {
+        const shouldQuit = await confirm(
+          "\n  There are unsaved changes in the browser. Quit anyway? (y/N) "
+        );
+        if (!shouldQuit) {
+          console.log("  Resuming...\n");
+          return;
+        }
+      } catch {
+      }
+    }
+    server.close();
+    process.exit(0);
+  });
 }
 
 // cli/index.ts
@@ -2051,21 +2401,26 @@ program.command("open").description("Open an existing .vertical file in the brow
   const filePath = resolveFilePath(file);
   await startServer(filePath);
 });
-program.command("show").description("Print the board to the terminal").argument("<file>", "Path to the .vertical file").option("--json", "Output as JSON").option("--box <slice-id>", "Show only a specific box").action((file, options) => {
-  const filePath = resolveFilePath(file, options.json);
-  const state = loadState(filePath);
-  if (options.box) {
-    const slice = state.slices.find((s) => s.id === options.box);
-    if (!slice) {
-      fail(`Box not found: ${options.box}`, options.json);
+program.command("show").description("Print the board to the terminal").argument("<file>", "Path to the .vertical file").option("--json", "Output as JSON").option("--box <slice-id>", "Show only a specific box").option("--visual", "Show the board as a visual 3x3 grid with summary").action(
+  (file, options) => {
+    const filePath = resolveFilePath(file, options.json);
+    const state = loadState(filePath);
+    if (options.box) {
+      const slice = state.slices.find((s) => s.id === options.box);
+      if (!slice) {
+        fail(`Box not found: ${options.box}`, options.json);
+      }
+    }
+    if (options.json) {
+      showBoardJson(state);
+    } else if (options.visual) {
+      showBoardGrid(state, options.box);
+      showSummaryTable(state, options.box);
+    } else {
+      showBoard(state, options.box);
     }
   }
-  if (options.json) {
-    showBoardJson(state);
-  } else {
-    showBoard(state, options.box);
-  }
-});
+);
 program.command("rename").description("Rename the project").argument("<file>", "Path to the .vertical file").argument("<name>", "New project name").option("--json", "Output as JSON").action((file, name, options) => {
   const filePath = resolveFilePath(file, options.json);
   const state = applyAction(filePath, { type: "RENAME_PROJECT", name });