@zinn-dev/cli 0.9.0 → 0.11.0

package/README.md

@@ -54,8 +54,8 @@ zinn project column create MDR "Boardlog"
 Create a task with a title and an optional description. New tasks enter the project's first column:
 
 ```sh
-zinn task create MDR "Refine 75% of the numbers"
-zinn task create MDR "Review the employee handbook" "Prepare for a 75% Dance Experience"
+zinn task create MDR --title "Refine 75% of the numbers"
+zinn task create MDR --title "Review the employee handbook" --description "Prepare for a 75% Dance Experience"
 ```
 
 Tasks are created with keys such as `MDR-1`. List active tasks, optionally limited to one project, or view one task:
@@ -68,6 +68,39 @@ zinn task view MDR-1
 
 When a project key is supplied, the list follows the project's column order and the task order within each column.
 
+## Labels
+
+Labels are global and reusable in all the available projects.
+
+```sh
+zinn label create urgent --color red --description "Needs attention soon"
+zinn label create review
+zinn label list
+```
+
+### Adding to tasks
+
+```sh
+zinn task create MDR --title "Check the numbers" --label urgent --label review
+zinn task label add MDR-1 urgent review
+zinn task label remove MDR-1 review
+zinn task edit MDR-1 --add-label review --remove-label urgent
+```
+
+For adding or removing multiple labels at the same time, repeat `--label` on creation, or `--add-label` and `--remove-label` while editing for each label.
+Each value is considered as the label name: `--label "needs review"`, so if you have commas, then they are considered parts of names.
+Label names are case-sensitive, and the whitespace from input is trimmed.
+
+Descriptions default to an empty string and the label colors default to white. Available colors are _red_, _green_, _yellow_, _blue_, _magenta_, _cyan_, _white_, and _gray_.
+
+Task creation and edits apply content and label changes together, or roll back together on failure.
+Note that label changes also update the task's modification timestamp. Archived tasks can also have their labels edited.
+
+Commands like `task view` and task mutation output show attached labels.
+
+`zinn label delete urgent` asks for confirmation, then deletes the definition and removes it from every task. Declining confirmation leaves the label and its attachments unchanged.
+Use `task label remove` to remove a label attachment from one task instead. Task/project deletion cleans up label attachments, but does not affect labels themselves.
+
 ## Task relations
 
 ```sh
@@ -91,7 +124,7 @@ Use `task relation create --help` to discover types.
 
 ## Edit tasks
 
-Edit a task's title, description, or both:
+Edit a task's title, description, priority, or labels:
 
 ```sh
 zinn task edit MDR-1 --title "Meet the quarterly refinement quota"
@@ -163,3 +196,15 @@ zinn task move --help
 The short `-h` form works in the same positions.
 
 Running `zinn` without a command shows help
+
+## Task priority
+
+Priority is optional: `low`, `medium`, `high`, or `urgent`. New tasks have no assigned priority by default.
+
+```sh
+zinn task create MDR --title "Review the numbers" --priority high
+zinn task edit MDR-1 --priority urgent
+zinn task edit MDR-1 --priority none
+```
+
+Use `none` to clear priority. Omitting `--priority` on edits preserves it. Assigned priorities appear in task list and view output; board ordering remains unchanged.

package/index.ts

@@ -27,6 +27,12 @@ Commands:
   task delete
   task relation create
   task relation list
+  task relation delete
+  task label add
+  task label remove
+  label create
+  label list
+  label delete
 
 Run zinn <namespace> --help or zinn <command> --help for more information.
 Running zinn without a command shows this help.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zinn-dev/cli",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "A kanban workflow in the terminal.",
   "license": "MIT",
   "bugs": {
@@ -42,6 +42,6 @@
     "access": "public"
   },
   "dependencies": {
-    "@zinn-dev/core": "0.9.0"
+    "@zinn-dev/core": "0.11.0"
   }
 }

package/src/lib.ts

@@ -1,4 +1,35 @@
+import type { parseArgs } from "node:util";
+
+type ParsedTokens = NonNullable<ReturnType<typeof parseArgs>["tokens"]>;
+
 export function quit(reason: string): never {
   console.error(reason);
   process.exit(1);
 }
+
+export function validatePositionalCount(
+  positionals: Array<string>,
+  expected: number,
+  message: string,
+) {
+  if (positionals.length !== expected) {
+    quit(message);
+  }
+}
+
+export function validateUniqueOptions(tokens: ParsedTokens, repeatableOptions: Array<string> = []) {
+  const parsedArgs = new Set<string>();
+
+  for (const token of tokens) {
+    if (token.kind !== "option") {
+      continue;
+    }
+
+    const isRepeatable = repeatableOptions.includes(token.name);
+    if (parsedArgs.has(token.name) && !isRepeatable) {
+      quit(`Option "--${token.name}" can only be specified once`);
+    }
+
+    parsedArgs.add(token.name);
+  }
+}

package/src/routes/label-router.ts

@@ -0,0 +1,74 @@
+import type { RouteDef } from "../types";
+
+import { parseArgs } from "node:util";
+import { label, labelCreateSchema, labelDeleteSchema } from "@zinn-dev/core";
+
+import { quit, validatePositionalCount, validateUniqueOptions } from "../lib";
+
+export const labelRouter = {
+  create: {
+    run: (args) => {
+      const { values, positionals, tokens } = parseArgs({
+        args,
+        options: { description: { type: "string" }, color: { type: "string" } },
+        allowPositionals: true,
+        strict: true,
+        tokens: true,
+      });
+
+      validatePositionalCount(positionals, 1, "Exactly one label name is required");
+
+      validateUniqueOptions(tokens);
+
+      const input = labelCreateSchema.parse({ name: positionals[0], ...values });
+      const created = label.create(input);
+
+      console.info(`${created.name} | ${created.color} | ${created.description}`);
+    },
+    help: `Usage: zinn label create <name> [--description <text>] [--color <color>]
+
+Create a global label. Names are case-sensitive and cannot be blank.
+Description defaults to an empty string; color defaults to white.
+Colors: red, green, yellow, blue, magenta, cyan, white, gray.
+
+Example: zinn label create bug --description "Unexpected behavior" --color red`,
+  },
+  list: {
+    run: (args) => {
+      parseArgs({ args, strict: true, allowPositionals: false });
+      for (const entry of label.getAll()) {
+        console.info(`${entry.name} | ${entry.color} | ${entry.description}`);
+      }
+    },
+    help: `Usage: zinn label list
+
+List all global label definitions.`,
+  },
+  delete: {
+    run: (args) => {
+      const { positionals } = parseArgs({ args, strict: true, allowPositionals: true });
+      validatePositionalCount(positionals, 1, "Exactly one label name is required");
+      const props = labelDeleteSchema.parse({ name: positionals[0] });
+      const labelMatch = label.getByName(props.name);
+
+      if (labelMatch == null) {
+        quit(`A label with name "${props.name}" does not exist`);
+      }
+
+      const canDelete = confirm(
+        `Are you sure you want to delete label "${labelMatch.name}" and remove it from all tasks?`,
+      );
+      if (!canDelete) {
+        console.info(`Deletion cancelled for label "${labelMatch.name}"`);
+        return;
+      }
+
+      const deleted = label.delete(props);
+      console.info(`Deleted label "${deleted.name}"`);
+    },
+    help: `Usage: zinn label delete <name>
+
+Delete a label definition and remove it from all tasks after confirmation.
+To remove a label from just one task, use zinn task label remove.`,
+  },
+} satisfies RouteDef;

package/src/routes/project-router.ts

@@ -3,7 +3,7 @@ import type { RouteDef } from "../types";
 import { parseArgs } from "node:util";
 
 import { column, project } from "@zinn-dev/core";
-import { quit } from "../lib";
+import { quit, validatePositionalCount, validateUniqueOptions } from "../lib";
 
 export const projectRouter = {
   edit: {
@@ -22,22 +22,9 @@ export const projectRouter = {
         quit("Project key must be specified");
       }
 
-      if (positionals.length > 1) {
-        quit("Only one project key can be specified");
-      }
-
-      const parsedArgs = new Set<string>();
-      for (const token of tokens) {
-        if (token.kind !== "option") {
-          continue;
-        }
+      validatePositionalCount(positionals, 1, "Only one project key can be specified");
 
-        if (parsedArgs.has(token.name)) {
-          quit(`The "--${token.name}" flag can only be specified once`);
-        }
-
-        parsedArgs.add(token.name);
-      }
+      validateUniqueOptions(tokens);
 
       if (values.name === undefined) {
         quit("Provide an edit flag: --name");
@@ -72,22 +59,9 @@ Example: zinn project edit MDR --name "Macrodata Refinement"`,
         quit("Project key must be specified");
       }
 
-      if (positionals.length > 1) {
-        quit("Only one project key can be specified");
-      }
-
-      const parsedArgs = new Set<string>();
-      for (const token of tokens) {
-        if (token.kind !== "option") {
-          continue;
-        }
+      validatePositionalCount(positionals, 1, "Only one project key can be specified");
 
-        if (parsedArgs.has(token.name)) {
-          quit(`The "--${token.name}" flag can only be specified once`);
-        }
-
-        parsedArgs.add(token.name);
-      }
+      validateUniqueOptions(tokens);
 
       try {
         const createdProject = project.create({ key: projectKey, name: values.name });

package/src/routes/relation-router.ts

@@ -2,7 +2,7 @@ import type { RouteDef } from "../types";
 
 import { parseArgs } from "node:util";
 import { relation, relationCreateSchema, task } from "@zinn-dev/core";
-import { quit } from "../lib";
+import { quit, validatePositionalCount, validateUniqueOptions } from "../lib";
 
 export function formatRelations(taskKey: string) {
   const taskMatch = task.getByKey(taskKey);
@@ -47,16 +47,9 @@ function parseRelationArgs(args: string[]) {
     tokens: true,
   });
 
-  if (positionals.length !== 2) {
-    quit("Exactly two task keys are required: source, target");
-  }
-
-  const optionCount = tokens.filter((token) => token.kind === "option").length;
+  validatePositionalCount(positionals, 2, "Exactly two task keys are required: source, target");
 
-  if (optionCount > 1) {
-    // TODO: maybe a reusable option validator can be given expected option keys, and it can spit out unsupported options as well as help for what options are supported
-    quit('Option "--type" can only be specified once');
-  }
+  validateUniqueOptions(tokens);
 
   const typeResult = relationCreateSchema.shape.relation_type.safeParse(values.type);
 
@@ -127,10 +120,9 @@ Example: zinn task relation create APP-1 APP-2 --type dependency`,
   list: {
     run: (args) => {
       const { positionals } = parseArgs({ args, allowPositionals: true, strict: true });
-      if (positionals.length !== 1) {
-        quit("Provide exactly one task key");
-      }
+      validatePositionalCount(positionals, 1, "Provide exactly one task key");
       const output = formatRelations(positionals[0]!);
+
       if (output.length > 0) {
         console.info(output);
       }

package/src/routes/routes.ts

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

package/src/routes/task-router.ts

@@ -3,9 +3,11 @@ import type { RouteDef } from "../types";
 import { parseArgs } from "node:util";
 import { task, project, column } from "@zinn-dev/core";
 
-import { quit } from "../lib";
+import { quit, validatePositionalCount, validateUniqueOptions } from "../lib";
 import { formatRelations, relationRouter } from "./relation-router";
 
+// TODO: a CLI row formatter that accepts text columns and joins them with " | " would be useful
+// Reuse it across task list/view and other command output in a separate change.
 function formatTask(
   taskMatch: ReturnType<typeof task.getByKey>,
   options: { showsStatus?: boolean } = {},
@@ -17,16 +19,26 @@ function formatTask(
     : "";
   const description = taskMatch.description == null ? "" : ` | ${taskMatch.description}`;
 
-  return `${taskKey}${status} | ${taskColumn.name} | ${taskMatch.title}${description}`;
+  const priority = taskMatch.priority == null ? "" : ` | Priority: ${taskMatch.priority}`;
+  const labels = task.label.getAll(taskKey);
+  const labelText =
+    labels.length === 0 ? "" : ` | Labels: ${labels.map((label) => label.name).join(", ")}`;
+
+  return `${taskKey}${status} | ${taskColumn.name} | ${taskMatch.title}${description}${priority}${labelText}`;
 }
 
 export const taskRouter = {
-  relation: relationRouter,
   edit: {
     run: (args) => {
       const { values, positionals, tokens } = parseArgs({
         args,
-        options: { title: { type: "string" }, description: { type: "string" } },
+        options: {
+          title: { type: "string" },
+          description: { type: "string" },
+          priority: { type: "string" },
+          "add-label": { type: "string", multiple: true },
+          "remove-label": { type: "string", multiple: true },
+        },
         allowPositionals: true,
         strict: true,
         tokens: true,
@@ -38,81 +50,99 @@ export const taskRouter = {
         quit("Task key must be specified");
       }
 
-      if (positionals.length > 1) {
-        quit("Only one task key can be specified");
-      }
+      validatePositionalCount(positionals, 1, "Only one task key can be specified");
 
-      const parsedArgs = new Set<string>();
-      for (const token of tokens) {
-        if (token.kind !== "option") {
-          continue;
-        }
+      validateUniqueOptions(tokens, ["add-label", "remove-label"]);
 
-        if (parsedArgs.has(token.name)) {
-          quit(`Option "--${token.name}" can only be specified once`);
-        }
+      const hasEditFlags =
+        values.title !== undefined ||
+        values.description !== undefined ||
+        values.priority !== undefined ||
+        values["add-label"] !== undefined ||
+        values["remove-label"] !== undefined;
 
-        parsedArgs.add(token.name);
+      if (!hasEditFlags) {
+        quit(
+          "Provide at least one edit flag: --title, --description, --priority, --add-label, or --remove-label",
+        );
       }
 
-      if (values.title === undefined && values.description === undefined) {
-        quit("Provide at least one edit flag: --title or --description");
-      }
+      const editedTask = task.edit({
+        taskKey,
+        title: values.title,
+        description: values.description,
+        priority: parsePriority(values.priority),
+        addLabelNames: values["add-label"],
+        removeLabelNames: values["remove-label"],
+      });
 
-      const editedTask = task.edit({ taskKey, ...values });
       console.info(formatTask(editedTask));
     },
-    help: `Usage: zinn task edit <task-key> [--title <text>] [--description <text>]
+    help: `Usage: zinn task edit <task-key> [--title <text>] [--description <text>] [--priority <low|medium|high|urgent|none>] [--add-label <name>] [--remove-label <name>]
 
 Change the supplied fields and preserve everything else.
+Use --priority none to clear priority.
 Provide at least one edit flag. Use --description "" for an empty description.
 
-Titles cannot be blank.
+Repeat --add-label or --remove-label for multiple existing labels.
+Adding an attached label or removing an unattached label does not do anything.
 Archived tasks can be edited. Unchanged values leave the task unchanged.
+
+The same label cannot be both added and removed.
+Titles cannot be blank.
+
 Use --title="--example" for text beginning with a dash.
 
 Example: zinn task edit MDR-1 --title "Meet the quarterly refinement quota"`,
   },
   create: {
-    run: (args: Array<string>) => {
-      const projectKey = args[0];
+    run: (args) => {
+      const { values, positionals, tokens } = parseArgs({
+        args,
+        options: {
+          title: { type: "string" },
+          description: { type: "string" },
+          priority: { type: "string" },
+          label: { type: "string", multiple: true },
+        },
+        allowPositionals: true,
+        strict: true,
+        tokens: true,
+      });
+      const projectKey = positionals[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");
+      validatePositionalCount(
+        positionals,
+        1,
+        "Only one project key can be specified; use --title and --description",
+      );
+      if (values.title === undefined) {
+        quit("A task needs at least a title: use --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?
-        const createdTask = task.create({
-          project_id: projectMatch.id,
-          title: taskTitle,
-          description: taskDesc ?? null,
-        });
-        console.info(formatTask(createdTask));
-      } catch (err: any) {
-        quit(err?.message ?? "Something went wrong");
+      validateUniqueOptions(tokens, ["label"]);
+      const projectMatch = project.getByKey(projectKey);
+      if (projectMatch == null) {
+        quit(`Project with key "${project.standardizeKey(projectKey)}" does not exist`);
       }
+      const createdTask = task.create({
+        project_id: projectMatch.id,
+        title: values.title,
+        description: values.description ?? null,
+        priority: parsePriority(values.priority),
+        labelNames: values.label,
+      });
+      console.info(formatTask(createdTask));
     },
-    help: `Usage: zinn task create <project-key> <title> [description]
+    help: `Usage: zinn task create <project-key> --title <text> [--description <text>] [--priority <low|medium|high|urgent|none>] [--label <name>]
 
 Create a task in the project's first column.
+Priority defaults to none (unassigned).
+Repeat --label to attach multiple existing labels. Unknown labels are errors.
+Titles cannot be blank. Use --title="--example" for text beginning with a dash.
 
-Example: zinn task create MDR "Refine the numbers" "Sort the numbers and meet the quarterly quota"`,
+Example: zinn task create MDR --title "Refine the numbers" --description "Meet the quarterly quota" --label urgent`,
   },
   list: {
     run: (args) => {
@@ -147,6 +177,7 @@ Example: zinn task create MDR "Refine the numbers" "Sort the numbers and meet th
           status: t.archived_at == null ? "Active" : "Archived",
           title: t.title,
           description: t.description,
+          priority: t.priority,
           column: taskColumn.name,
         };
       });
@@ -166,7 +197,8 @@ Example: zinn task create MDR "Refine the numbers" "Sort the numbers and meet th
             // 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}`;
+            const priority = t.priority == null ? "" : ` | Priority: ${t.priority}`;
+            return `${t.id.padEnd(longestIdLength)}${status} | ${t.column} | ${t.title}${description}${priority}`;
           })
           .join("\n"),
       );
@@ -196,7 +228,7 @@ Example: zinn task list MDR --all`,
     },
     help: `Usage: zinn task view <task-key>
 
-Show a task with its current column, description, and relations.
+Show a task with its current column, description, priority, labels, and relations.
 
 Example: zinn task view MDR-1`,
   },
@@ -291,8 +323,9 @@ Example: zinn task order MDR-2 before MDR-1`,
         const canDelete = confirm(`Are you sure you want to delete ${taskKey}?`);
 
         if (canDelete) {
-          const deletedTask = task.delete(taskKey);
-          console.info(`Deleted ${formatTask(deletedTask)}`);
+          const formattedTask = formatTask(taskMatch);
+          task.delete(taskKey);
+          console.info(`Deleted ${formattedTask}`);
         } else {
           console.info(`Deletion cancelled for ${formatTask(taskMatch)}`);
         }
@@ -340,4 +373,50 @@ Unarchive a task at the bottom of its previous column.
 
 Example: zinn task unarchive MDR-1`,
   },
+  relation: relationRouter,
+  label: {
+    add: {
+      run: (args) => {
+        const props = parseTaskLabelArgs(args);
+        console.info(formatTask(task.label.add(props)));
+      },
+      help: `Usage: zinn task label add <task-key> <label-name> [label-name ...]
+
+Add existing labels to a task. Already attached labels are unchanged.`,
+    },
+    remove: {
+      run: (args) => {
+        const props = parseTaskLabelArgs(args);
+        console.info(formatTask(task.label.remove(props)));
+      },
+      help: `Usage: zinn task label remove <task-key> <label-name> [label-name ...]
+
+Remove existing labels from a task. Unattached labels are unchanged.
+Label definitions are preserved.`,
+    },
+  },
 } satisfies RouteDef;
+
+function parseTaskLabelArgs(args: string[]) {
+  const { positionals } = parseArgs({ args, strict: true, allowPositionals: true });
+  if (positionals.length < 2) {
+    quit("Provide a task key and at least one label name");
+  }
+  return { taskKey: positionals[0]!, labelNames: positionals.slice(1) };
+}
+
+function parsePriority(value: string | undefined) {
+  switch (value) {
+    case undefined:
+      return undefined;
+    case "none":
+      return null;
+    case "low":
+    case "medium":
+    case "high":
+    case "urgent":
+      return value;
+    default:
+      quit("Priority must be low, medium, high, urgent, or none");
+  }
+}