tatr-ql 0.1.0 → 0.2.0

package/bin/index.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.js";
+
+main().catch((error) => {
+  console.error(`tatr: ${error.message}`);
+  process.exitCode = 1;
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tatr-ql",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Task Tracker (Nodejs Version)",
   "keywords": [
     "task",
@@ -22,11 +22,18 @@
   "license": "MIT",
   "author": "zakaria elalaoui",
   "type": "module",
-  "main": "index.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "vitest",
+    "test:run": "vitest run"
+  },
+  "bin": {
+    "tatr": "./bin/tatr.js"
   },
   "dependencies": {
-    "ziko": "^2.0.0-beta.10"
+    "ziko": "^2.0.0-beta.10",
+    "zod": "^4.6.2"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.11"
   }
 }

package/src/cli.js

@@ -0,0 +1,242 @@
+import { spawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  createTask,
+  deleteTask,
+  ensureTasksDir,
+  listTasks,
+  readTask,
+  tasksPath,
+  writeTask
+} from "./store.js";
+import { parseTags } from "./task.js";
+import { matchesQuery } from "./query.js";
+import packageJson from "../package.json" with { type: "json" };
+
+const {version : VERSION} = packageJson;
+
+const help = () => console.log(`
+tatr ${VERSION} — filesystem task tracker
+
+Usage:
+  tatr <command> [options]
+
+Commands:
+  new <title>       Create a task
+  ls [query]        List tasks, optionally filtered by TQL
+  show <id>         Show a task
+  edit <id>         Edit TASK.md in $EDITOR
+  close <id>        Mark a task CLOSED
+  reopen <id>       Mark a task OPEN
+  rm <id>           Delete a task
+  tags              Show tag descriptions
+  init              Create tasks/
+  help              Show this help
+  version           Show the version
+
+new options:
+  --priority <n>    Task priority (default: 0)
+  --tags <a,b,c>    Comma-separated tags
+  --suffix <name>   HUID suffix
+  --description <x> Initial description
+
+ls options:
+  --all             Include CLOSED tasks (default is all; kept for compatibility)
+  --open            Only OPEN tasks
+  --closed          Only CLOSED tasks
+
+TQL examples:
+  tatr ls :bug
+  tatr ls ':bug and not :ui'
+  tatr ls 'not tagged'
+  tatr ls ':bug and priority lt 50'
+  tatr ls '[:bug or :enhancement] and priority ge 10'
+`.trim());
+
+const parseFlags = (args) => {
+  const positionals = [];
+  const flags = {};
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (!arg.startsWith("--")) {
+      positionals.push(arg);
+      continue;
+    }
+
+    const eq = arg.indexOf("=");
+
+    if (eq !== -1) {
+      flags[arg.slice(2, eq)] = arg.slice(eq + 1);
+      continue;
+    }
+
+    const key = arg.slice(2);
+    const next = args[i + 1];
+
+    if (next && !next.startsWith("--")) {
+      flags[key] = next;
+      i++;
+    } else {
+      flags[key] = true;
+    }
+  }
+
+  return { positionals, flags };
+};
+
+const formatTask = (task) => {
+  const tags = task.tags.length ? ` [${task.tags.join(", ")}]` : "";
+  return `${task.id}  ${task.status.padEnd(6)}  ${String(task.priority).padStart(4)}  ${task.title}${tags}`;
+};
+
+const commandNew = async (args) => {
+  const { positionals, flags } = parseFlags(args);
+  const title = positionals.join(" ").trim();
+
+  if (!title) throw new Error("Usage: tatr new <title>");
+
+  const task = await createTask({
+    title,
+    priority: flags.priority ?? 0,
+    tags: flags.tags ? parseTags(flags.tags) : [],
+    description: flags.description ?? "",
+    suffix: flags.suffix
+  });
+
+  console.log(task.id);
+};
+
+const commandLs = async (args) => {
+  const { positionals, flags } = parseFlags(args);
+  const query = positionals.join(" ").trim();
+  let tasks = await listTasks();
+
+  if (flags.open) tasks = tasks.filter((task) => task.status === "OPEN");
+  if (flags.closed) tasks = tasks.filter((task) => task.status === "CLOSED");
+  if (query) tasks = tasks.filter((task) => matchesQuery(query, task));
+
+  tasks.sort((a, b) =>
+    b.priority - a.priority ||
+    a.id.localeCompare(b.id)
+  );
+
+  for (const task of tasks) console.log(formatTask(task));
+};
+
+const commandShow = async (id) => {
+  if (!id) throw new Error("Usage: tatr show <id>");
+
+  const task = await readTask(id);
+
+  console.log(`ID:       ${task.id}`);
+  console.log(`TITLE:    ${task.title}`);
+  console.log(`STATUS:   ${task.status}`);
+  console.log(`PRIORITY: ${task.priority}`);
+  console.log(`TAGS:     ${task.tags.join(", ")}`);
+
+  if (task.description) console.log(`\n${task.description}`);
+};
+
+const commandEdit = async (id) => {
+  if (!id) throw new Error("Usage: tatr edit <id>");
+
+  const editor = process.env.EDITOR || process.env.VISUAL;
+  if (!editor) throw new Error("Set $EDITOR or $VISUAL before using tatr edit");
+
+  const file = join(tasksPath(), id, "TASK.md");
+  await readFile(file, "utf8");
+
+  const child = spawn(editor, [file], {
+    stdio: "inherit",
+    shell: true
+  });
+
+  await new Promise((resolve, reject) => {
+    child.on("error", reject);
+    child.on("exit", (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`editor exited with code ${code}`));
+    });
+  });
+};
+
+const setStatus = async (id, status) => {
+  if (!id) {
+    throw new Error(
+      `Usage: tatr ${status === "CLOSED" ? "close" : "reopen"} <id>`
+    );
+  }
+
+  const task = await readTask(id);
+  task.status = status;
+  await writeTask(task);
+};
+
+const commandTags = async () => {
+  const file = join(tasksPath(), "tags");
+
+  try {
+    console.log(await readFile(file, "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      console.log("No tasks/tags file.");
+      return;
+    }
+    throw error;
+  }
+};
+
+export const main = async (argv = process.argv.slice(2)) => {
+  const [command = "help", ...args] = argv;
+
+  switch (command) {
+    case "help":
+    case "-h":
+    case "--help":
+      help();
+      break;
+    case "version":
+    case "-v":
+    case "--version":
+      console.log(VERSION);
+      break;
+    case "init":
+      await ensureTasksDir();
+      console.log(`Initialized ${tasksPath()}`);
+      break;
+    case "new":
+    case "add":
+      await commandNew(args);
+      break;
+    case "ls":
+    case "list":
+      await commandLs(args);
+      break;
+    case "show":
+      await commandShow(args[0]);
+      break;
+    case "edit":
+      await commandEdit(args[0]);
+      break;
+    case "close":
+      await setStatus(args[0], "CLOSED");
+      break;
+    case "reopen":
+    case "open":
+      await setStatus(args[0], "OPEN");
+      break;
+    case "rm":
+    case "delete":
+      if (!args[0]) throw new Error("Usage: tatr rm <id>");
+      await deleteTask(args[0]);
+      break;
+    case "tags":
+      await commandTags();
+      break;
+    default:
+      throw new Error(`Unknown command "${command}". Run "tatr help".`);
+  }
+};

package/src/index.js

@@ -0,0 +1,5 @@
+export * from './huid.js'
+export * from './query.js'
+export * from './store.js'
+export * from './task.js'
+export * from './cli.js'

package/src/query.js

@@ -0,0 +1,199 @@
+/*
+ * TQL parser/evaluator.
+ *
+ * Grammar:
+ *   expr    := or
+ *   or      := and ("or" and)*
+ *   and     := compare ("and" compare)*
+ *   compare := primary (compare-op primary)*
+ *   primary := tag | "[" expr "]" | "not" primary | "any" | "tagged"
+ *            | "priority" | number
+ */
+
+import { z } from "zod";
+
+const COMPARATORS = new Set(["lt", "le", "gt", "ge", "eq", "ne"]);
+const KEYWORDS = new Set([
+  "and",
+  "or",
+  "not",
+  "any",
+  "tagged",
+  "priority",
+  ...COMPARATORS
+]);
+
+const TokenSchema = z.object({
+  type: z.string(),
+  value: z.union([z.string(), z.number(), z.null()])
+});
+
+const TokensSchema = z.array(TokenSchema);
+
+export const tokenize = (input) => {
+  const tokens = [];
+  let i = 0;
+  while (i < input.length) {
+    const ch = input[i];
+    if (/\s/.test(ch)) {
+      i++;
+      continue;
+    }
+    if (ch === "[") {
+      tokens.push({ type: "lbracket", value: ch });
+      i++;
+      continue;
+    }
+    if (ch === "]") {
+      tokens.push({ type: "rbracket", value: ch });
+      i++;
+      continue;
+    }
+    if (ch === ":") {
+      let j = i + 1;
+      while (j < input.length && !/[\s[\]]/.test(input[j])) j++;
+      if (j === i + 1) throw new Error("Empty tag in TQL");
+      tokens.push({ type: "tag", value: input.slice(i + 1, j) });
+      i = j;
+      continue;
+    }
+    if (ch === "-" || /\d/.test(ch)) {
+      let j = i;
+      if (input[j] === "-") j++;
+      const start = j;
+      while (j < input.length && /\d/.test(input[j])) j++;
+      if (j === start) {
+        throw new Error(`Invalid number near "${input.slice(i)}"`);
+      }
+      tokens.push({
+        type: "number",
+        value: Number.parseInt(input.slice(i, j), 10)
+      });
+      i = j;
+      continue;
+    }
+
+    let j = i;
+    while (j < input.length && !/[\s[\]]/.test(input[j])) j++;
+    const word = input.slice(i, j);
+    const lower = word.toLowerCase();
+    if (KEYWORDS.has(lower)) tokens.push({ type: lower, value: lower });
+    else throw new Error(`Unexpected token "${word}"`);
+    i = j;
+  }
+  return TokensSchema.parse([
+    ...tokens,
+    { type: "eof", value: null }
+  ]);
+};
+
+export const parseQuery = (input) => {
+  if (!input || !input.trim()) return { type: "any" };
+  const tokens = tokenize(input);
+  let pos = 0;
+  const peek = () => tokens[pos];
+  const take = () => tokens[pos++];
+  const expect = (type) => {
+    const token = take();
+    if (token.type !== type) throw new Error(`Expected ${type}, got ${token.type}`);
+    return token;
+  };
+  const parsePrimary = () => {
+    const token = peek();
+    switch (token.type) {
+      case "not":
+        take();
+        return { type: "not", expr: parsePrimary() };
+      case "lbracket":
+        take();
+        const expr = parseOr();
+        expect("rbracket");
+        return expr;
+      case "tag":
+        take();
+        return { type: "tag", tag: token.value };
+      case "any":
+        take();
+        return { type: "any" };
+      case "tagged":
+        take();
+        return { type: "tagged" };
+      case "priority":
+        take();
+        return { type: "priority" };
+      case "number":
+        take();
+        return { type: "number", value: token.value };
+      default:
+        throw new Error(`Expected expression, got ${token.type}`);
+    }
+  };
+
+  const parseCompare = () => {
+    let left = parsePrimary();
+    while (COMPARATORS.has(peek().type)) {
+      const op = take().type;
+      const right = parsePrimary();
+      left = { type: "compare", op, left, right };
+    }
+    return left;
+  };
+
+  const parseAnd = () => {
+    let left = parseCompare();
+    while (peek().type === "and") {
+      take();
+      left = {
+        type: "and",
+        left,
+        right: parseCompare()
+      };
+    }
+    return left;
+  };
+
+  const parseOr = () => {
+    let left = parseAnd();
+    while (peek().type === "or") {
+      take();
+      left = {
+        type: "or",
+        left,
+        right: parseAnd()
+      };
+    }
+    return left;
+  };
+
+  const ast = parseOr();
+  if (peek().type !== "eof") throw new Error(`Unexpected token "${peek().value}"`);
+  return ast;
+};
+
+export const evaluateQuery = (ast, task) => {
+  switch (ast.type) {
+    case "any": return true;
+    case "tag": return task.tags.includes(ast.tag);
+    case "tagged": return task.tags.length > 0;
+    case "priority": return task.priority;
+    case "number": return ast.value;
+    case "not": return !Boolean(evaluateQuery(ast.expr, task));
+    case "and": return Boolean(evaluateQuery(ast.left, task)) && Boolean(evaluateQuery(ast.right, task));
+    case "or": return Boolean(evaluateQuery(ast.left, task)) || Boolean(evaluateQuery(ast.right, task));
+    case "compare": {
+      const left = evaluateQuery(ast.left, task);
+      const right = evaluateQuery(ast.right, task);
+      switch (ast.op) {
+        case "lt": return left < right;
+        case "le": return left <= right;
+        case "gt": return left > right;
+        case "ge": return left >= right;
+        case "eq": return left === right;
+        case "ne": return left !== right;
+        default: throw new Error(`Unknown comparator ${ast.op}`);
+      }
+    }
+    default: throw new Error(`Unknown AST node ${ast.type}`);
+  }
+};
+export const matchesQuery = (query, task) => evaluateQuery(typeof query === "string" ? parseQuery(query) : query, task);

package/src/store.js

@@ -0,0 +1,123 @@
+import {
+  access,
+  mkdir,
+  readdir,
+  readFile,
+  writeFile,
+  rm,
+  rename
+} from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { uniqueHuid, isHuid } from "./huid.js";
+import { parseTaskMarkdown, serializeTask } from "./task.js";
+
+export const findProjectRoot = (start = process.cwd()) => resolve(start);
+export const tasksPath = (projectRoot = process.cwd()) => join(findProjectRoot(projectRoot), "tasks");
+export const ensureTasksDir = async (projectRoot = process.cwd()) => {
+  const dir = tasksPath(projectRoot);
+  await mkdir(dir, { recursive: true });
+  return dir;
+};
+
+export const listTaskIds = async (projectRoot = process.cwd()) => {
+  const dir = tasksPath(projectRoot);
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    return entries
+      .filter((entry) => entry.isDirectory() && isHuid(entry.name))
+      .map((entry) => entry.name)
+      .sort();
+  } catch (error) {
+    if (error.code === "ENOENT") return [];
+    throw error;
+  }
+};
+
+export const readTask = async (id, projectRoot = process.cwd()) => {
+  if (!isHuid(id)) {
+    throw new Error(`Invalid task ID: ${id}`);
+  }
+  const file = join(tasksPath(projectRoot), id, "TASK.md");
+  const markdown = await readFile(file, "utf8");
+  return parseTaskMarkdown(markdown, id);
+};
+
+export const listTasks = async (projectRoot = process.cwd()) => {
+  const ids = await listTaskIds(projectRoot);
+  const tasks = [];
+  for (const id of ids) {
+    try {
+      tasks.push(await readTask(id, projectRoot));
+    } catch (error) {
+      if (error.code === "ENOENT") continue;
+      throw error;
+    }
+  }
+
+  return tasks;
+};
+
+export const createTask = async ({
+  projectRoot = process.cwd(),
+  title,
+  priority = 0,
+  status = "OPEN",
+  tags = [],
+  description = "",
+  suffix
+}) => {
+  if (!title?.trim()) {
+    throw new Error("Task title is required");
+  }
+  const dir = await ensureTasksDir(projectRoot);
+  const id = await uniqueHuid(dir, { suffix });
+  const taskDir = join(dir, id);
+  await mkdir(taskDir);
+  const task = {
+    id,
+    title: title.trim(),
+    status: String(status).toUpperCase(),
+    priority: Number.parseInt(priority, 10),
+    tags: Array.isArray(tags)
+      ? tags
+      : String(tags)
+          .split(",")
+          .map((x) => x.trim())
+          .filter(Boolean),
+    description
+  };
+  await writeFile(
+    join(taskDir, "TASK.md"),
+    serializeTask(task),
+    "utf8"
+  );
+  return task;
+};
+
+export const writeTask = async (task, projectRoot = process.cwd()) => {
+  if (!isHuid(task.id)) {
+    throw new Error(`Invalid task ID: ${task.id}`);
+  }
+  const file = join(tasksPath(projectRoot), task.id, "TASK.md");
+  await writeFile(file, serializeTask(task), "utf8");
+  return task;
+};
+
+export const deleteTask = async (id, projectRoot = process.cwd()) => {
+  if (!isHuid(id)) {
+    throw new Error(`Invalid task ID: ${id}`);
+  }
+  await rm(join(tasksPath(projectRoot), id), {
+    recursive: true,
+    force: false
+  });
+};
+
+export const moveTask = async (id, newId, projectRoot = process.cwd()) => {
+  if (!isHuid(id) || !isHuid(newId)) {
+    throw new Error("Both task IDs must be valid HUIDs");
+  }
+  const dir = tasksPath(projectRoot);
+  await access(join(dir, id));
+  await rename(join(dir, id), join(dir, newId));
+};