@zinn-dev/cli 0.0.8 → 0.1.0

package/README.md

@@ -1,3 +1,129 @@
 # @zinn-dev/cli
 
-The `zinn` binary. Requires [Bun](https://bun.sh).
+The `zinn` command-line interface. Requires [Bun](https://bun.sh).
+
+## Install
+
+```sh
+bun add --global @zinn-dev/cli
+```
+
+Zinn stores projects and tasks in the shared local database at `~/.zinn/data/zinn.sqlite`.
+Set `ZINN_DIR` to use another Zinn directory and keep using the same value for commands that should share that database.
+
+## Start a project
+
+Create a project with a name and a short key that begins with a letter and then uses only letters and numbers:
+
+```sh
+zinn project create "Website refresh" SITE
+```
+
+Project keys are stored in uppercase. Each project starts with _Backlog_, _TODO_, _In Progress_, _Review_, and _Done_ columns. List projects or inspect a project's columns with:
+
+```sh
+zinn project list
+zinn project column list SITE
+```
+
+Add another column at the end of the board:
+
+```sh
+zinn project column create SITE "Waiting"
+```
+
+`zinn project delete SITE` permanently deletes the project and all of its columns and tasks. The command does not ask for confirmation.
+
+## Create and read tasks
+
+Create a task with a title and an optional description. New tasks enter the project's first column:
+
+```sh
+zinn task create SITE "Rewrite the home page"
+zinn task create SITE "Check the mobile layout" "Test the navigation at narrow widths"
+```
+
+Tasks are created with keys such as `SITE-1`. List active tasks, optionally limited to one project, or view one task:
+
+```sh
+zinn task list
+zinn task list SITE
+zinn task view SITE-1
+```
+
+When a project key is supplied, the list follows the project's column order and the task order within each column.
+
+## Edit tasks
+
+Edit a task's title, description, or both:
+
+```sh
+zinn task edit SITE-1 --title "Rewrite the landing page"
+zinn task edit SITE-1 --description "Include the new product screenshots"
+zinn task edit SITE-1 --title "Rewrite the landing page" --description ""
+```
+
+Omitted fields stay unchanged. An empty description is stored as an empty string.
+
+At least one flag is required and task titles cannot be blank. Archived tasks can be edited without unarchiving them. Supplying unchanged values does not change the modification timestamp.
+Use `--title="--example"` when a value begins with a dash.
+
+## Move and order tasks
+
+Move a task to another column in its project:
+
+```sh
+zinn task move SITE-1 "In Progress"
+```
+
+A moved task appears at the bottom of its destination column. Moving it to its current column does nothing. Archived tasks must be unarchived before they can be moved.
+
+Change a task's position within its current column:
+
+```sh
+zinn task order SITE-2 top
+zinn task order SITE-2 up
+zinn task order SITE-2 down
+zinn task order SITE-2 bottom
+zinn task move SITE-2 "In Progress"
+zinn task order SITE-2 before SITE-1
+zinn task order SITE-2 after SITE-1
+```
+
+The task being reordered and the target of `before` or `after` must be active tasks in the same column.
+
+## Archive and delete tasks
+
+Active tasks are shown by default. Archive a task to hide it from active lists, then list archived tasks or all tasks:
+
+```sh
+zinn task archive SITE-1
+zinn task list SITE --archived
+zinn task list SITE --all
+```
+
+`--archived` and `--all` cannot be used together. In an `--all` listing, Zinn adds an Active or Archived status column.
+
+Unarchiving puts a task at the bottom of its previous column:
+
+```sh
+zinn task unarchive SITE-1
+```
+
+Delete a task permanently with `zinn task delete SITE-1`. Unlike project deletion, task deletion asks for confirmation.
+
+## Help
+
+Use root or namespace help to discover commands, then open a command's help for its arguments and behavior:
+
+```sh
+zinn --help
+zinn project --help
+zinn project column --help
+zinn task --help
+zinn task move --help
+```
+
+The short `-h` form works in the same positions.
+
+Running `zinn` without a command launches the work-in-progress TUI when attached to an interactive terminal. The commands documented above provide the complete current workflow.

package/index.ts

@@ -2,18 +2,6 @@
 import { quit } from "./src/lib";
 
 const args = process.argv.slice(2);
-const FLAG = {
-  help: ["-h", "--help"],
-  project: ["project"],
-  task: ["task"],
-  create: ["create"],
-  delete: ["delete"],
-};
-
-const MESSAGE = {
-  displayUnknownCommand: (cmd: string) =>
-    `Unrecognized command "${cmd}". Please run \`zinn --help\` for a list of available commands`,
-};
 
 if (args.length === 0) {
   if (!!process.stdout.isTTY) {
@@ -25,93 +13,37 @@ if (args.length === 0) {
 } else {
   // TODO: isTTY check for human readable colored and structured formatting like tables
   const firstArg = args[0]!;
-  if (FLAG.help.includes(firstArg)) {
-    // TODO: document that project keys are always uppercased
+  // TODO: root routing with flags
+  if (["-h", "--help"].includes(firstArg)) {
     console.info(`ZINN - A kanban workflow in the terminal
 
-      usage: zinn [options]
-      -h, --help  For help using Zinn`);
+Usage: zinn <command>
+
+Options:
+  -h, --help  Show help
+
+Commands:
+  project create
+  project list
+  project delete
+  project column create
+  project column list
+  task create
+  task list
+  task view
+  task edit
+  task move
+  task order
+  task archive
+  task unarchive
+  task delete
+
+Run zinn <namespace> --help or zinn <command> --help for more information.
+Running zinn without a command opens the work-in-progress TUI in an interactive terminal.`);
   } else {
-    const { project, task } = await import("@zinn-dev/core");
-
-    if (FLAG.project.includes(firstArg)) {
-      const secondArg = args[1];
-      if (secondArg == null) {
-        // TODO: implement `zinn project --help` for better guiding
-        quit(`The command "${firstArg}" requires a secondary command: zinn ${firstArg} <command>`);
-      } else if (FLAG.create.includes(secondArg)) {
-        // TODO: allow direct key value pairs with flags like --name and --key
-        const projectName = args[2];
-        // TODO: maybe auto generate project key from name instead of forcing explicit input (however, very open to collision)
-        const projectKey = args[3];
-
-        if (projectName == null || projectKey == null) {
-          quit("Both the project name and the project key must be defined");
-        }
-
-        try {
-          project.create({ key: projectKey, name: projectName });
-        } catch (err: any) {
-          quit(err?.message ?? "Something went wrong");
-        }
-      } else if (FLAG.delete.includes(secondArg)) {
-        const projectKey = args[2];
-        if (projectKey == null) {
-          quit("You need to specificy which project to delete");
-        }
-
-        try {
-          // TODO: add y/n confirmation
-          project.delete(projectKey);
-        } catch (err: any) {
-          quit(err?.message ?? "Something went wrong");
-        }
-      } else {
-        quit(MESSAGE.displayUnknownCommand(`${firstArg} ${secondArg}`));
-      }
-    } else if (FLAG.task.includes(firstArg)) {
-      const secondArg = args[1];
-      if (secondArg == null) {
-        // TODO: implement `zinn project --help` for better guiding
-        console.error(
-          `The command "${firstArg}" requires a secondary command: zinn ${firstArg} <command>`,
-        );
-        process.exit(1);
-      } else if (FLAG.create.includes(secondArg)) {
-        const projectKey = args[2];
-        if (projectKey == null) {
-          quit("A task needs to belong to a project");
-        }
-
-        const taskName = args[3];
-        if (taskName == null) {
-          quit("A task needs at least a title");
-        }
-
-        const taskDesc = args[4];
-
-        // TODO: do empty strings bypass this check?
-
-        try {
-          const standardizedKey = project.standardizeKey(projectKey);
-          // TODO: `getByKey` already standardizes the key, but to display it in standardized format, I also used it here. Should it run twice on the same thing?
-          const projectMatch = project.getByKey(standardizedKey);
-          if (projectMatch == null) {
-            quit(`Project with key "${standardizedKey}" does not exist`);
-          }
-
-          // TODO: should it non-null (??) or non-falsy (||) check?
-          task.create({
-            project_id: projectMatch.id,
-            name: taskName,
-            description: taskDesc ?? null,
-          });
-        } catch (err: any) {
-          quit(err?.message ?? "Something went wrong");
-        }
-      }
-    } else {
-      quit(MESSAGE.displayUnknownCommand(firstArg));
-    }
+    const { createRouter } = await import("./src/routes/router");
+    const { routes } = await import("./src/routes/routes");
+    const router = createRouter(routes);
+    router.route(args);
   }
 }

package/package.json

@@ -1,48 +1,48 @@
 {
-	"name": "@zinn-dev/cli",
-	"version": "0.0.8",
-	"description": "A kanban workflow in the terminal.",
-	"license": "MIT",
-	"bugs": {
-		"url": "https://github.com/yethranayeh/zinn/issues"
-	},
-	"author": {
-		"name": "Alper Halil",
-		"email": "contact@aktasalper.com",
-		"url": "https://aktasalper.com"
-	},
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/yethranayeh/zinn.git"
-	},
-	"keywords": [
-		"kanban",
-		"cli",
-		"terminal",
-		"tui",
-		"opentui",
-		"bun"
-	],
-	"module": "index.ts",
-	"exports": {
-		".": {
-			"types": "./index.ts",
-			"import": "./index.ts"
-		}
-	},
-	"files": [
-		"index.ts",
-		"src"
-	],
-	"type": "module",
-	"bin": {
-		"zinn": "./index.ts"
-	},
-	"publishConfig": {
-		"access": "public"
-	},
-	"dependencies": {
-		"@zinn-dev/core": "0.0.4",
-		"@zinn-dev/tui": "0.0.1"
-	}
-}
+  "name": "@zinn-dev/cli",
+  "version": "0.1.0",
+  "description": "A kanban workflow in the terminal.",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/yethranayeh/zinn/issues"
+  },
+  "author": {
+    "name": "Alper Halil",
+    "email": "contact@aktasalper.com",
+    "url": "https://aktasalper.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yethranayeh/zinn.git"
+  },
+  "keywords": [
+    "kanban",
+    "cli",
+    "terminal",
+    "tui",
+    "opentui",
+    "bun"
+  ],
+  "module": "index.ts",
+  "exports": {
+    ".": {
+      "types": "./index.ts",
+      "import": "./index.ts"
+    }
+  },
+  "files": [
+    "index.ts",
+    "src"
+  ],
+  "type": "module",
+  "bin": {
+    "zinn": "./index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@zinn-dev/core": "0.1.0",
+    "@zinn-dev/tui": "0.0.1"
+  }
+}

package/src/routes/project-router.ts

@@ -0,0 +1,111 @@
+import type { RouteDef } from "../types";
+
+import { column, project } from "@zinn-dev/core";
+import { quit } from "../lib";
+
+export const projectRouter = {
+  create: {
+    run: (args: Array<string>) => {
+      const projectName = args[0];
+      // TODO: maybe auto generate project key from name instead of forcing explicit input (however, very open to collision)
+      const projectKey = args[1];
+
+      if (projectName == null || projectKey == null) {
+        quit("Both the project name and the project key must be defined");
+      }
+
+      try {
+        project.create({ key: projectKey, name: projectName });
+      } catch (err: any) {
+        quit(err?.message ?? "Something went wrong");
+      }
+    },
+    help: `Usage: zinn project create <name> <project-key>
+
+Create a project with the default Backlog, TODO, In Progress, Review, and Done columns.
+Project keys are stored in uppercase.
+
+Example: zinn project create "Website refresh" SITE`,
+  },
+  list: {
+    run: () => {
+      const projects = project.getAll();
+      if (projects.length === 0) {
+        return;
+      }
+
+      const longestKeyLength = projects.reduce(
+        (prev, current) => Math.max(prev, current.key.length),
+        0,
+      );
+
+      console.info(projects.map((p) => `${p.key.padEnd(longestKeyLength)} | ${p.name}`).join("\n"));
+    },
+    help: `Usage: zinn project list
+
+List projects and their keys.
+
+Example: zinn project list`,
+  },
+  delete: {
+    run: (args: Array<string>) => {
+      const projectKey = args[0];
+
+      if (projectKey == null) {
+        quit("You need to specificy which project to delete");
+      }
+
+      try {
+        // TODO: add y/n confirmation
+        project.delete(projectKey);
+      } catch (err: any) {
+        quit(err?.message ?? "Something went wrong");
+      }
+    },
+    help: `Usage: zinn project delete <project-key>
+
+Permanently delete a project and all of its columns and tasks without confirmation.
+
+Example: zinn project delete SITE`,
+  },
+  column: {
+    create: {
+      run: (args: Array<string>) => {
+        const projectKey = args[0];
+        const columnName = args[1];
+
+        if (projectKey == null || columnName == null) {
+          quit("Both the project name and the column name must be defined");
+        }
+
+        try {
+          column.create({ projectKey, name: columnName });
+        } catch (err: any) {
+          quit(err?.message ?? "Something went wrong");
+        }
+      },
+      help: `Usage: zinn project column create <project-key> <column-name>
+
+Add a column at the end of a project's board.
+
+Example: zinn project column create SITE "Waiting for review"`,
+    },
+    list: {
+      run: (args: Array<string>) => {
+        const projectKey = args[0];
+        if (projectKey == null) {
+          quit("Project key needs to be specified to list columns");
+        }
+
+        // TODO: attach per-column task count
+        // TODO: terminal formatting
+        console.info(column.getAllByProjectKey(projectKey).map((c) => c.name));
+      },
+      help: `Usage: zinn project column list <project-key>
+
+List a project's columns in board order.
+
+Example: zinn project column list SITE`,
+    },
+  },
+} satisfies RouteDef;

package/src/routes/router.test.ts

@@ -0,0 +1,79 @@
+import type { Command, RouteDef } from "../types";
+
+import { test, expect, mock, spyOn } from "bun:test";
+import { createRouter, parseRoutes } from "./router";
+
+const mockCommand: Command = { run: mock(() => {}), help: `` };
+
+test("command nesting is properly parsed", () => {
+  const routes: RouteDef = {
+    foo: {
+      create: mockCommand,
+      bar: {
+        create: mockCommand,
+        baz: {
+          create: mockCommand,
+          foo: {
+            create: mockCommand,
+          },
+        },
+      },
+    },
+  };
+  expect(parseRoutes(routes).map((r) => r.command)).toEqual([
+    "foo create",
+    "foo bar create",
+    "foo bar baz create",
+    "foo bar baz foo create",
+  ]);
+});
+
+test("router calls the run functions", () => {
+  const routes: RouteDef = {
+    foo: {
+      create: mockCommand,
+      bar: {
+        create: mockCommand,
+      },
+    },
+  };
+
+  let router = createRouter(routes);
+  router.route(["foo", "create"]);
+  expect(mockCommand.run).toHaveBeenCalledTimes(1);
+
+  router.route(["foo", "bar", "create"]);
+  expect(mockCommand.run).toHaveBeenCalledTimes(2);
+});
+
+test("router calls the deepest nesting command", () => {
+  const fooCreate = mock(() => {});
+  const barCreate = mock(() => {});
+  const routes = {
+    foo: {
+      create: { run: fooCreate, help: "" },
+      bar: {
+        create: { run: barCreate, help: "" },
+      },
+    },
+  } satisfies RouteDef;
+
+  let router = createRouter(routes);
+  router.route(["foo", "bar", "create"]);
+  expect(routes.foo.bar.create.run).toHaveBeenCalledTimes(1);
+  expect(routes.foo.create.run).not.toHaveBeenCalled();
+});
+
+test("a help request never runs a command even when its help is empty", () => {
+  const run = mock(() => {});
+  const info = spyOn(console, "info").mockImplementation(() => {});
+  const router = createRouter({ foo: { run, help: "" } });
+
+  try {
+    router.route(["foo", "--help"]);
+    expect(run).not.toHaveBeenCalled();
+    expect(info).toHaveBeenCalledWith("");
+  } finally {
+    info.mockRestore();
+  }
+});

package/src/routes/router.ts

@@ -0,0 +1,107 @@
+import type { Command, ParsedRoute, RouteDef } from "../types";
+
+import { quit } from "../lib";
+
+function getIsRunnable(obj: any): obj is Command {
+  return Object.hasOwn(obj, "run");
+}
+
+function toCommand(args: Array<string>) {
+  return args.join(" ");
+}
+
+function getNamespaceHelp(parsedRoutes: Array<ParsedRoute>, namespace: string) {
+  const prefix = `${namespace} `;
+  const commands = parsedRoutes
+    .map((route) => route.command)
+    .filter((command) => command.startsWith(prefix));
+
+  if (commands.length === 0) {
+    return null;
+  }
+
+  return `Usage: zinn ${namespace} <command>\n\nCommands:\n${commands.map((command) => `  ${command}`).join("\n")}`;
+}
+
+export function parseRoutes(routesDef: RouteDef, prefix?: string) {
+  const routeDefinitions: Array<ParsedRoute> = [];
+  if (process.env.DEBUG) {
+    console.debug(`::router.parseRoutes[${prefix ?? ""}]`, routesDef);
+  }
+
+  for (const key of Object.keys(routesDef)) {
+    const definition = routesDef[key as keyof typeof routesDef]!;
+
+    const isRunnable = getIsRunnable(definition);
+    const combinedRoute = prefix ? `${prefix} ${key}` : key;
+    if (isRunnable) {
+      routeDefinitions.push({ command: combinedRoute, ...definition });
+    } else {
+      const result = parseRoutes(definition, combinedRoute);
+      routeDefinitions.push(...result);
+    }
+  }
+
+  return routeDefinitions;
+}
+
+function route(parsedRoutes: Array<ParsedRoute>, args: Array<string>) {
+  const isHelpRequest = ["-h", "--help"].includes(args.at(-1) ?? "");
+
+  if (isHelpRequest && args.length > 1) {
+    const namespace = toCommand(args.slice(0, -1));
+    const namespaceHelp = getNamespaceHelp(parsedRoutes, namespace);
+    if (namespaceHelp != null) {
+      console.info(namespaceHelp);
+      return;
+    }
+  }
+
+  let match: ParsedRoute | null = null;
+  let nestingLevel = 0;
+
+  for (let endIndex = args.length; endIndex >= 0; endIndex--) {
+    const command = toCommand(args.slice(0, endIndex));
+    const matchedRoute = parsedRoutes.find((r) => r.command === command);
+
+    if (matchedRoute) {
+      match = matchedRoute;
+      nestingLevel = endIndex;
+      break;
+    }
+  }
+
+  if (process.env.DEBUG) {
+    console.log("::router.route", { args, result: parsedRoutes.map((r) => r.command), match });
+  }
+
+  if (match == null) {
+    quit(
+      `Unrecognized command "${toCommand(args)}". Please run \`zinn --help\` for a list of available commands`,
+    );
+  }
+
+  const commandArgs = args.slice(nestingLevel);
+  const isCommandHelpRequest =
+    commandArgs.length === 1 && ["-h", "--help"].includes(commandArgs[0]!);
+
+  if (isCommandHelpRequest) {
+    console.info(match.help);
+    return;
+  }
+
+  try {
+    match.run(commandArgs);
+  } catch (err: any) {
+    quit(
+      err?.message ??
+        `Something went wrong while running "${match.command}" with args: ${commandArgs.join(",")}`,
+    );
+  }
+}
+
+export function createRouter(routesDef: RouteDef) {
+  const parsedRoutes = parseRoutes(routesDef);
+
+  return { route: (args: Array<string>) => route(parsedRoutes, args) };
+}

package/src/routes/routes.ts

@@ -0,0 +1,8 @@
+import { projectRouter } from "./project-router";
+import { taskRouter } from "./task-router";
+
+// TODO: lazy load?
+export const routes = {
+  project: projectRouter,
+  task: taskRouter,
+};

package/src/routes/task-router.ts

@@ -0,0 +1,319 @@
+import type { RouteDef } from "../types";
+
+import { parseArgs } from "node:util";
+
+import { task, project, column } from "@zinn-dev/core";
+import { quit } from "../lib";
+
+export const taskRouter = {
+  edit: {
+    run: (args) => {
+      const { values, positionals, tokens } = parseArgs({
+        args,
+        options: { title: { type: "string" }, description: { type: "string" } },
+        allowPositionals: true,
+        strict: true,
+        tokens: true,
+      });
+
+      const taskKey = positionals[0];
+
+      if (taskKey == null) {
+        quit("Task key must be specified");
+      }
+
+      if (positionals.length > 1) {
+        quit("Only one task key can be specified");
+      }
+
+      const parsedArgs = new Set<string>();
+      for (const token of tokens) {
+        if (token.kind !== "option") {
+          continue;
+        }
+
+        if (parsedArgs.has(token.name)) {
+          quit(`Option "--${token.name}" can only be specified once`);
+        }
+
+        parsedArgs.add(token.name);
+      }
+
+      if (values.title === undefined && values.description === undefined) {
+        quit("Provide at least one edit flag: --title or --description");
+      }
+
+      task.edit({ taskKey, ...values });
+    },
+    help: `Usage: zinn task edit <task-key> [--title <text>] [--description <text>]
+
+Change the supplied fields and preserve everything else.
+Provide at least one edit flag. Use --description "" for an empty description.
+
+Titles cannot be blank.
+Archived tasks can be edited. Unchanged values leave the task unchanged.
+Use --title="--example" for text beginning with a dash.
+
+Example: zinn task edit SITE-1 --title "Rewrite the landing page"`,
+  },
+  create: {
+    run: (args: Array<string>) => {
+      const projectKey = args[0];
+      if (projectKey == null) {
+        quit("A task needs to belong to a project");
+      }
+
+      const taskTitle = args[1];
+      if (taskTitle == null) {
+        quit("A task needs at least a title");
+      }
+
+      const taskDesc = args[2];
+
+      // TODO: do empty strings bypass this check?
+
+      try {
+        const standardizedKey = project.standardizeKey(projectKey);
+        // TODO: `getByKey` already standardizes the key, but to display it in standardized format, I also used it here. Should it run twice on the same thing?
+        const projectMatch = project.getByKey(standardizedKey);
+        if (projectMatch == null) {
+          quit(`Project with key "${standardizedKey}" does not exist`);
+        }
+
+        // TODO: should it non-null (??) or non-falsy (||) check?
+        task.create({
+          project_id: projectMatch.id,
+          title: taskTitle,
+          description: taskDesc ?? null,
+        });
+      } catch (err: any) {
+        quit(err?.message ?? "Something went wrong");
+      }
+    },
+    help: `Usage: zinn task create <project-key> <title> [description]
+
+Create a task in the project's first column.
+
+Example: zinn task create SITE "Rewrite the home page" "Update the product copy"`,
+  },
+  list: {
+    run: (args) => {
+      const showsArchived = args.includes("--archived");
+      const showsAll = args.includes("--all");
+
+      if (showsArchived && showsAll) {
+        quit('Use either "--archived" or "--all", not both');
+      }
+
+      const positionalArgs = args.filter((arg) => !["--archived", "--all"].includes(arg));
+      const projectKey = positionalArgs[0];
+
+      if (positionalArgs.length > 1) {
+        quit("Only one project key can be specified");
+      }
+
+      const archive = showsAll ? "all" : showsArchived ? "archived" : "active";
+
+      const tasks = task.getAll({ projectKey, archive });
+
+      if (tasks.length === 0) {
+        return;
+      }
+
+      const presentableTasks = tasks.map((t) => {
+        // TODO: A task's project and column is fetched in both `list` and `view`. Make a reusable fetcher?
+        const taskProject = project.getById(t.project_id)!;
+        const taskColumn = column.getById(t.column_id)!;
+        const taskKey = `${taskProject.key}-${t.number}`;
+
+        return {
+          id: taskKey,
+          status: t.archived_at == null ? "Active" : "Archived",
+          title: t.title,
+          description: t.description,
+          column: taskColumn.name,
+        };
+      });
+
+      const longestIdLength = presentableTasks.reduce(
+        (prev, current) => Math.max(prev, current.id.length),
+        0,
+      );
+      const longestStatusLength = presentableTasks.reduce(
+        (prev, current) => Math.max(prev, current.status.length),
+        0,
+      );
+
+      console.info(
+        presentableTasks
+          .map((t) => {
+            // TODO: console output formatting for standardizied output
+            const status = showsAll ? ` | ${t.status.padEnd(longestStatusLength)}` : "";
+            const description = t.description == null ? "" : ` | ${t.description}`;
+            return `${t.id.padEnd(longestIdLength)}${status} | ${t.column} | ${t.title}${description}`;
+          })
+          .join("\n"),
+      );
+    },
+    help: `Usage: zinn task list [project-key] [--archived | --all]
+
+List active tasks by default.
+Use --archived to list archived tasks or --all to list both.
+
+Example: zinn task list SITE --all`,
+  },
+  view: {
+    run: (args) => {
+      const taskKey = args[0];
+
+      if (taskKey == null) {
+        quit("Task key must be specified");
+      }
+
+      const taskMatch = task.getByKey(taskKey);
+      const taskProject = project.getById(taskMatch.project_id)!;
+      const taskColumn = column.getById(taskMatch.column_id)!;
+
+      const canonicalTaskKey = `${taskProject.key}-${taskMatch.number}`;
+      const description = taskMatch.description == null ? "" : ` | ${taskMatch.description}`;
+      console.info(`${canonicalTaskKey} | ${taskColumn?.name} | ${taskMatch.title}${description}`);
+    },
+    help: `Usage: zinn task view <task-key>
+
+Show a task with its current column and description.
+
+Example: zinn task view SITE-1`,
+  },
+  move: {
+    run: (args) => {
+      const [taskKey, targetColumn] = args;
+
+      if (taskKey == null) {
+        quit("Task key must be specified");
+      }
+
+      if (targetColumn == null) {
+        quit("Target column must be specified");
+      }
+
+      task.move({ taskKey, targetColumn });
+    },
+    help: `Usage: zinn task move <task-key> <target-column>
+
+Move a task to another column in its project.
+Moving a task to a different column lists it last in that column,
+matching placement at the bottom of a visual kanban column.
+
+Giving a task's current column as the target will not do anything.
+Archived tasks must be unarchived before they can be moved.
+
+Example: zinn task move SITE-1 "In Progress"`,
+  },
+  order: {
+    run: (args) => {
+      const [taskKey, direction, targetTaskKey, ...extraArgs] = args;
+
+      if (taskKey == null) {
+        quit("Task key must be specified");
+      }
+
+      if (direction == null) {
+        quit("Order direction must be specified");
+      }
+
+      switch (direction) {
+        case "before":
+        case "after": {
+          if (targetTaskKey == null) {
+            quit(`Target task must be specified for "${direction}"`);
+          }
+
+          if (extraArgs.length > 0) {
+            quit("Only one target task can be specified");
+          }
+
+          task.order({ taskKey, direction, targetTaskKey });
+          return;
+        }
+        case "top":
+        case "up":
+        case "down":
+        case "bottom": {
+          if (targetTaskKey != null) {
+            quit(`Order direction "${direction}" does not accept a target task`);
+          }
+
+          task.order({ taskKey, direction });
+          return;
+        }
+        default:
+          quit(`Unknown order direction "${direction}"`);
+      }
+    },
+    help: `Usage: zinn task order <task-key> <top | up | down | bottom>
+       zinn task order <task-key> <before | after> <target-task-key>
+
+Change a task's position within its current column.
+Use top or bottom for either end, up or down for one position,
+or before or after to place it relative to another task.
+
+Example: zinn task order SITE-2 before SITE-1`,
+  },
+  delete: {
+    run: (args: Array<string>) => {
+      const taskKey = args[0];
+
+      if (taskKey == null) {
+        quit("Task key must be specified");
+      }
+
+      try {
+        task.getByKey(taskKey);
+        const canDelete = confirm(`Are you sure you want to delete ${taskKey}?`);
+
+        if (canDelete) {
+          task.delete(taskKey);
+        }
+      } catch (err: any) {
+        quit(err?.message ?? "Something went wrong");
+      }
+    },
+    help: `Usage: zinn task delete <task-key>
+
+Permanently delete a task after confirmation.
+
+Example: zinn task delete SITE-1`,
+  },
+  archive: {
+    run: (args: Array<string>) => {
+      const taskKey = args[0];
+
+      if (taskKey == null) {
+        quit("Task key must be specified");
+      }
+
+      task.archive(taskKey);
+    },
+    help: `Usage: zinn task archive <task-key>
+
+Archive a task so it no longer appears in active task lists.
+
+Example: zinn task archive SITE-1`,
+  },
+  unarchive: {
+    run: (args: Array<string>) => {
+      const taskKey = args[0];
+
+      if (taskKey == null) {
+        quit("Task key must be specified");
+      }
+
+      task.unarchive(taskKey);
+    },
+    help: `Usage: zinn task unarchive <task-key>
+
+Unarchive a task at the bottom of its previous column.
+
+Example: zinn task unarchive SITE-1`,
+  },
+} satisfies RouteDef;

package/src/types.ts

@@ -0,0 +1,6 @@
+export type Command = { run: (args: Array<string>) => void; help: string };
+export type ParsedRoute = {
+  command: string;
+} & Command;
+
+export type RouteDef = { [key: string]: Command | RouteDef };