lytos-cli 0.2.0 → 0.3.0

package/README.md

@@ -1,36 +1,53 @@
 # Lytos — CLI
 
 [![CI](https://github.com/getlytos/lytos-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/getlytos/lytos-cli/actions/workflows/ci.yml)
-[![npm](https://img.shields.io/npm/v/lytos)](https://www.npmjs.com/package/lytos-cli)
+[![npm](https://img.shields.io/npm/v/lytos-cli)](https://www.npmjs.com/package/lytos-cli)
 
 > The command-line tool for [Lytos](https://github.com/getlytos/lytos-method) — a human-first method for working with AI agents.
 
+**Lytos** gives your AI agents a structured context: what the project is, how to work, what "done" means, what's in progress, and what's been learned. Everything in markdown. No vendor lock-in, no API, no account.
+
 ---
 
-## Install
+## The problem
 
-```bash
-npm install -g lytos-cli
-```
+AI agents (Claude, Cursor, GPT...) are powerful but stateless. Every session starts from zero. They don't know your project's conventions, your sprint priorities, or what was tried last week.
+
+**Lytos** solves this by creating a `.lytos/` directory in your project — a structured context that any AI can read, and that you own.
+
+---
 
-Then use:
+## The 5 pillars
+
+`lytos init` scaffolds a `.lytos/` directory built on 5 pillars:
+
+| Pillar | Purpose | File / Directory |
+|--------|---------|-----------------|
+| **Intent** | Why the project exists — its constitution | `manifest.md` |
+| **Design** | Procedures for recurring tasks (code review, testing, deployment...) | `skills/` |
+| **Standards** | Non-negotiable quality criteria | `rules/` |
+| **Progress** | Issues, sprint, what's moving and what's blocked | `issue-board/` |
+| **Memory** | What's been learned — sovereign, portable, model-independent | `memory/` |
+
+These 5 pillars are the method. The AI agent reads them at the start of each session and follows them.
+
+---
+
+## Install
 
 ```bash
-lytos init          # Install Lytos in your project
-lytos board         # Regenerate BOARD.md from issue frontmatter
+npm install -g lytos-cli
 ```
 
 Or use without installing:
 
 ```bash
-npx lytos init
+npx lytos-cli init
 ```
 
 ---
 
-## What it does
-
-One command to install the method, one command to validate your setup, one command to see your sprint.
+## Commands
 
 | Command | What it does |
 |---------|-------------|
@@ -42,22 +59,70 @@ One command to install the method, one command to validate your setup, one comma
 
 ---
 
+## What `lytos init` generates
+
+```
+your-project/
+└── .lytos/
+    ├── manifest.md              # Intent — project identity and constraints
+    ├── LYTOS.md                 # Method reference
+    ├── sprint.md                # Current sprint
+    ├── skills/                  # Design — 9 reusable procedures
+    │   ├── session-start.md
+    │   ├── code-structure.md
+    │   ├── code-review.md
+    │   ├── testing.md
+    │   ├── documentation.md
+    │   ├── git-workflow.md
+    │   ├── deployment.md
+    │   ├── security.md
+    │   └── api-design.md
+    ├── rules/                   # Standards — quality criteria
+    │   └── default-rules.md
+    ├── issue-board/             # Progress — kanban board
+    │   ├── BOARD.md
+    │   ├── 0-icebox/
+    │   ├── 1-backlog/
+    │   ├── 2-sprint/
+    │   ├── 3-in-progress/
+    │   ├── 4-review/
+    │   └── 5-done/
+    └── memory/                  # Memory — accumulated knowledge
+        ├── MEMORY.md
+        └── cortex/
+            ├── architecture.md
+            ├── patterns.md
+            ├── bugs.md
+            └── ...
+```
+
+---
+
+## Design principles
+
+- **Offline-first** — no network needed (except `lytos init` to download templates)
+- **Zero lock-in** — plain markdown files, works with any AI tool
+- **No telemetry** — no tracking, no analytics, ever
+- **Human-first** — the human defines the method, the AI follows it
+
+---
+
 ## Built with Lytos
 
 This project uses Lytos to develop itself. The `.lytos/` directory contains the real manifest, sprint, issues, and memory for this project — not templates.
 
-If you want to contribute, open this repo in Claude Code and say: **"Help me understand this project."**
-
 ---
 
-## Author
+## Links
+
+- [Lytos Method](https://github.com/getlytos/lytos-method) — the method itself
+- [Documentation](https://github.com/getlytos/lytos-website) — full docs (EN/FR)
 
-Created by **Frederic Galliné** — [ubeez.com](https://ubeez.com)
+---
 
-- GitHub: [@FredericGalline](https://github.com/FredericGalline)
-- X: [@fred](https://x.com/fred)
+## Author
 
-Part of the [Lytos](https://github.com/getlytos/lytos-method) project.
+Created by **Frederic Galline** — [ubeez.com](https://ubeez.com)
 
 ---
 

package/dist/cli.js

@@ -611,8 +611,10 @@ function color(code, text) {
 }
 var green = (t) => color("32", t);
 var red = (t) => color("31", t);
+var yellow = (t) => color("33", t);
 var blue = (t) => color("34", t);
 var bold = (t) => color("1", t);
+var dim = (t) => color("2", t);
 function info(msg) {
   console.error(`${blue("\u2192")} ${msg}`);
 }
@@ -648,7 +650,7 @@ async function promptChoice(question, choices) {
   }
   console.error("");
   const answer = await prompt("Choice");
-  const match = choices.find((c) => c.key === answer);
+  const match = choices.find((c2) => c2.key === answer);
   return match ? match.key : choices[0].key;
 }
 var initCommand = new Command("init").description("Scaffold Lytos in your project").option("--name <name>", "Project name").option(
@@ -747,8 +749,8 @@ var initCommand = new Command("init").description("Scaffold Lytos in your projec
 
 // src/commands/board.ts
 import { Command as Command2 } from "commander";
-import { existsSync as existsSync5, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
-import { join as join4 } from "path";
+import { existsSync as existsSync6, readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "fs";
+import { join as join5 } from "path";
 
 // src/lib/board-generator.ts
 import { readdirSync, readFileSync as readFileSync2, existsSync as existsSync4 } from "fs";
@@ -927,18 +929,199 @@ function boardToJson(data) {
   };
 }
 
+// src/lib/board-display.ts
+import { readFileSync as readFileSync3, existsSync as existsSync5 } from "fs";
+import { join as join4 } from "path";
+var noColor2 = process.env.NO_COLOR !== void 0 || process.argv.includes("--no-color");
+function c(code, text) {
+  if (noColor2) return text;
+  return `\x1B[${code}m${text}\x1B[0m`;
+}
+var bold2 = (t) => c("1", t);
+var dim2 = (t) => c("2", t);
+var green2 = (t) => c("32", t);
+var yellow2 = (t) => c("33", t);
+var magenta = (t) => c("35", t);
+var cyan = (t) => c("36", t);
+var white = (t) => c("37", t);
+var bgRed = (t) => c("41", t);
+var boldYellow = (t) => c("1;33", t);
+var boldBlue = (t) => c("1;34", t);
+var boldGreen = (t) => c("1;32", t);
+var boldCyan = (t) => c("1;36", t);
+var boldMagenta = (t) => c("1;35", t);
+function colorPriority(p) {
+  if (p.startsWith("P0")) return bgRed(bold2(` ${p} `));
+  if (p.startsWith("P1")) return boldYellow(p);
+  if (p.startsWith("P2")) return boldBlue(p);
+  if (p.startsWith("P3")) return dim2(p);
+  return p;
+}
+function colorEffort(e) {
+  return dim2(e);
+}
+function colorStatus(status, count) {
+  const label = STATUS_DISPLAY[status] || status;
+  const countStr = `(${count})`;
+  switch (status) {
+    case "0-icebox":
+      return dim2(`\u25B8 ${label} ${countStr}`);
+    case "1-backlog":
+      return bold2(white(`\u25B8 ${label} ${countStr}`));
+    case "2-sprint":
+      return boldCyan(`\u25B8 ${label} ${countStr}`);
+    case "3-in-progress":
+      return boldYellow(`\u25B8 ${label} ${countStr}`);
+    case "4-review":
+      return boldMagenta(`\u25B8 ${label} ${countStr}`);
+    case "5-done":
+      return boldGreen(`\u25B8 ${label} ${countStr}`);
+    default:
+      return `\u25B8 ${label} ${countStr}`;
+  }
+}
+var STATUS_DISPLAY = {
+  "0-icebox": "ICEBOX",
+  "1-backlog": "BACKLOG",
+  "2-sprint": "SPRINT",
+  "3-in-progress": "IN PROGRESS",
+  "4-review": "REVIEW",
+  "5-done": "DONE"
+};
+var ACTIVE_STATUSES = [
+  "0-icebox",
+  "1-backlog",
+  "2-sprint",
+  "3-in-progress",
+  "4-review"
+];
+function buildTree(issues) {
+  const issueIds = new Set(issues.map((i) => String(i.frontmatter.id)));
+  const result = [];
+  const children = /* @__PURE__ */ new Map();
+  const roots = [];
+  for (const issue of issues) {
+    const deps = issue.frontmatter.depends;
+    const depList = Array.isArray(deps) ? deps : deps ? [deps] : [];
+    const parentInGroup = depList.find((d) => issueIds.has(d));
+    if (parentInGroup) {
+      const existing = children.get(parentInGroup) || [];
+      existing.push(issue);
+      children.set(parentInGroup, existing);
+    } else {
+      roots.push(issue);
+    }
+  }
+  function addIssue(issue, depth, isLast) {
+    result.push({ issue, depth, isLast });
+    const kids = children.get(String(issue.frontmatter.id)) || [];
+    kids.forEach((kid, i) => {
+      addIssue(kid, depth + 1, i === kids.length - 1);
+    });
+  }
+  roots.forEach((root, i) => {
+    addIssue(root, 0, i === roots.length - 1);
+  });
+  return result;
+}
+function formatIssue(di) {
+  const { issue, depth, isLast } = di;
+  const id = String(issue.frontmatter.id || "?");
+  const title = String(issue.frontmatter.title || "?");
+  const priority = String(issue.frontmatter.priority || "?");
+  const effort = String(issue.frontmatter.effort || "?");
+  const maxTitle = 50;
+  const displayTitle = title.length > maxTitle ? title.slice(0, maxTitle - 1) + "\u2026" : title;
+  let prefix = "  ";
+  if (depth === 0) {
+    prefix = "  ";
+  } else {
+    prefix = "  " + "   ".repeat(depth - 1) + (isLast ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 ");
+  }
+  return `${prefix}${dim2(id)}  ${colorPriority(priority)}  ${colorEffort(effort)}  ${displayTitle}`;
+}
+function detectProjectName(cwd) {
+  try {
+    const manifestPath = join4(cwd, ".lytos", "manifest.md");
+    if (existsSync5(manifestPath)) {
+      const content = readFileSync3(manifestPath, "utf-8");
+      const nameMatch = content.match(/\|\s*Name\s*\|\s*(.+?)\s*\|/);
+      if (nameMatch) return nameMatch[1].trim();
+    }
+    const pkgPath = join4(cwd, "package.json");
+    if (existsSync5(pkgPath)) {
+      const pkg = JSON.parse(readFileSync3(pkgPath, "utf-8"));
+      if (pkg.name) return pkg.name;
+    }
+  } catch {
+  }
+  return "project";
+}
+function displayBoard(data) {
+  const projectName = detectProjectName(process.cwd());
+  const line = "\u2500".repeat(52);
+  console.log("");
+  console.log(`  ${boldCyan("\u2554")}${boldCyan("\u2550".repeat(52))}${boldCyan("\u2557")}`);
+  console.log(`  ${boldCyan("\u2551")}  ${bold2("LYTOS BOARD")} \u2014 ${projectName}${" ".repeat(Math.max(0, 38 - projectName.length))}${boldCyan("\u2551")}`);
+  console.log(`  ${boldCyan("\u255A")}${boldCyan("\u2550".repeat(52))}${boldCyan("\u255D")}`);
+  console.log("");
+  const counts = {};
+  for (const status of [...ACTIVE_STATUSES, "5-done"]) {
+    counts[status] = data.issues.filter((i) => i.status === status).length;
+  }
+  const shownStatuses = ["1-backlog", "2-sprint", "3-in-progress", "4-review"];
+  for (const status of shownStatuses) {
+    const issues = data.issues.filter((i) => i.status === status);
+    console.log(`  ${colorStatus(status, issues.length)}`);
+    if (issues.length === 0) {
+      console.log("");
+      continue;
+    }
+    console.log(`  ${dim2("\u2502")}`);
+    const tree = buildTree(issues);
+    for (const di of tree) {
+      console.log(`  ${dim2("\u2502")} ${formatIssue(di)}`);
+    }
+    console.log("");
+  }
+  const iceboxCount = counts["0-icebox"];
+  if (iceboxCount > 0) {
+    console.log(`  ${colorStatus("0-icebox", iceboxCount)}`);
+    const iceboxIssues = data.issues.filter((i) => i.status === "0-icebox");
+    console.log(`  ${dim2("\u2502")}`);
+    const tree = buildTree(iceboxIssues);
+    for (const di of tree) {
+      console.log(`  ${dim2("\u2502")} ${formatIssue(di)}`);
+    }
+    console.log("");
+  }
+  console.log(`  ${colorStatus("5-done", counts["5-done"])}`);
+  console.log("");
+  console.log(`  ${dim2(line)}`);
+  const parts = [
+    `${bold2(String(data.issues.length))} issues`,
+    counts["1-backlog"] ? `${counts["1-backlog"]} backlog` : null,
+    counts["2-sprint"] ? `${cyan(String(counts["2-sprint"]))} sprint` : null,
+    counts["3-in-progress"] ? `${yellow2(String(counts["3-in-progress"]))} wip` : null,
+    counts["4-review"] ? `${magenta(String(counts["4-review"]))} review` : null,
+    counts["5-done"] ? `${green2(String(counts["5-done"]))} done ${green2("\u2713")}` : null
+  ].filter(Boolean);
+  console.log(`  ${parts.join(dim2(" \xB7 "))}`);
+  console.log("");
+}
+
 // src/commands/board.ts
 function findBoardDir(cwd) {
   const candidates = [
-    join4(cwd, ".lytos", "issue-board"),
-    join4(cwd, "issue-board")
+    join5(cwd, ".lytos", "issue-board"),
+    join5(cwd, "issue-board")
   ];
   for (const candidate of candidates) {
-    if (existsSync5(candidate)) return candidate;
+    if (existsSync6(candidate)) return candidate;
   }
   return null;
 }
-var boardCommand = new Command2("board").description("Regenerate BOARD.md from issue frontmatter").option(
+var boardCommand = new Command2("board").description("Display board overview and regenerate BOARD.md").option(
   "--check",
   "Check if BOARD.md is up to date (exit 1 if not)",
   false
@@ -961,12 +1144,12 @@ var boardCommand = new Command2("board").description("Regenerate BOARD.md from i
   }
   const newContent = generateBoardMarkdown(data);
   if (opts.check) {
-    const boardPath2 = join4(boardDir, "BOARD.md");
-    if (!existsSync5(boardPath2)) {
+    const boardPath2 = join5(boardDir, "BOARD.md");
+    if (!existsSync6(boardPath2)) {
       error("BOARD.md does not exist.");
       process.exit(1);
     }
-    const existing = readFileSync3(boardPath2, "utf-8");
+    const existing = readFileSync4(boardPath2, "utf-8");
     const normalize = (s) => s.replace(/\*\*Last generated\*\*:.*/, "").trim();
     if (normalize(existing) === normalize(newContent)) {
       ok("BOARD.md is up to date.");
@@ -978,18 +1161,115 @@ var boardCommand = new Command2("board").description("Regenerate BOARD.md from i
       process.exit(1);
     }
   }
-  const boardPath = join4(boardDir, "BOARD.md");
+  displayBoard(data);
+  const boardPath = join5(boardDir, "BOARD.md");
   writeFileSync2(boardPath, newContent, "utf-8");
   ok(
-    `BOARD.md generated: ${data.issues.length} issues found`
+    `BOARD.md regenerated`
   );
 });
 
+// src/lib/update-check.ts
+import { existsSync as existsSync7, readFileSync as readFileSync5, writeFileSync as writeFileSync3, mkdirSync as mkdirSync2 } from "fs";
+import { join as join6 } from "path";
+import { homedir } from "os";
+import { get } from "https";
+var PACKAGE_NAME = "lytos-cli";
+var CHECK_INTERVAL_MS = 24 * 60 * 60 * 1e3;
+var CACHE_DIR = join6(homedir(), ".lytos");
+var CACHE_FILE = join6(CACHE_DIR, "last-update-check");
+function isNewer(remote, local) {
+  const r = remote.split(".").map(Number);
+  const l = local.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((r[i] || 0) > (l[i] || 0)) return true;
+    if ((r[i] || 0) < (l[i] || 0)) return false;
+  }
+  return false;
+}
+function shouldCheck() {
+  try {
+    if (!existsSync7(CACHE_FILE)) return true;
+    const lastCheck = parseInt(readFileSync5(CACHE_FILE, "utf-8").trim(), 10);
+    return Date.now() - lastCheck > CHECK_INTERVAL_MS;
+  } catch {
+    return true;
+  }
+}
+function saveCheckTimestamp() {
+  try {
+    if (!existsSync7(CACHE_DIR)) {
+      mkdirSync2(CACHE_DIR, { recursive: true });
+    }
+    writeFileSync3(CACHE_FILE, String(Date.now()), "utf-8");
+  } catch {
+  }
+}
+function fetchLatestVersion() {
+  return new Promise((resolve2) => {
+    const timeout = setTimeout(() => resolve2(null), 3e3);
+    get(
+      `https://registry.npmjs.org/${PACKAGE_NAME}/latest`,
+      { headers: { Accept: "application/json" } },
+      (res) => {
+        let data = "";
+        res.on("data", (chunk) => data += chunk);
+        res.on("end", () => {
+          clearTimeout(timeout);
+          try {
+            const json = JSON.parse(data);
+            resolve2(json.version || null);
+          } catch {
+            resolve2(null);
+          }
+        });
+        res.on("error", () => {
+          clearTimeout(timeout);
+          resolve2(null);
+        });
+      }
+    ).on("error", () => {
+      clearTimeout(timeout);
+      resolve2(null);
+    });
+  });
+}
+async function checkForUpdates(currentVersion) {
+  if (!shouldCheck()) return;
+  saveCheckTimestamp();
+  const latest = await fetchLatestVersion();
+  if (!latest) return;
+  if (isNewer(latest, currentVersion)) {
+    console.error("");
+    console.error(
+      `  ${yellow("\u26A0")} Update available: ${dim(currentVersion)} \u2192 ${bold(latest)}`
+    );
+    console.error(
+      `    Run ${bold("npm install -g lytos-cli")} to update`
+    );
+    console.error("");
+  }
+}
+
 // src/cli.ts
 var program = new Command3();
-program.name("lytos").description(
+program.name("lyt").description(
   "CLI tool for Lytos \u2014 a human-first method for working with AI agents"
-).version("0.1.1");
+).version("0.2.1");
 program.addCommand(initCommand);
 program.addCommand(boardCommand);
+program.command("lint").description("Validate .lytos/ structure and content (coming soon)").action(() => {
+  console.error("Coming soon. Follow https://github.com/getlytos/lytos-cli for updates.");
+  process.exit(0);
+});
+program.command("doctor").description("Full diagnostic \u2014 missing files, broken links, stale memory (coming soon)").action(() => {
+  console.error("Coming soon. Follow https://github.com/getlytos/lytos-cli for updates.");
+  process.exit(0);
+});
+program.command("status").description("Display sprint DAG in terminal (coming soon)").action(() => {
+  console.error("Coming soon. Follow https://github.com/getlytos/lytos-cli for updates.");
+  process.exit(0);
+});
+var VERSION = "0.2.1";
 program.parse();
+checkForUpdates(VERSION);

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "lytos-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "CLI tool for Lytos — a human-first method for working with AI agents",
   "type": "module",
   "bin": {
+    "lyt": "dist/cli.js",
     "lytos": "dist/cli.js",
     "lytos-cli": "dist/cli.js"
   },