@shortcut-cli/shortcut-cli 3.7.0 → 3.8.0

package/README.md

@@ -8,19 +8,20 @@ This is a community-driven command line interface for [Shortcut](https://shortcu
 
 ## Table of Contents
 
--   [Usage & Commands](#usage)
-    -   [Install](#install)
-    -   [Search](#search)
-    -   [Story](#story)
-    -   [Story Creation](#story-creation)
-    -   [Workspace](#workspace)
-    -   [Members](#members)
-    -   [Epics](#epics)
-    -   [Workflows](#workflows)
-    -   [Projects](#projects)
-    -   [API](#api)
--   [Development](#development)
--   [Acknowledgments](#acknowledgments)
+- [Usage & Commands](#usage)
+    - [Install](#install)
+    - [Search](#search)
+    - [Story](#story)
+    - [Story Creation](#story-creation)
+    - [Workspace](#workspace)
+    - [Members](#members)
+    - [Epics](#epics)
+    - [Docs](#docs)
+    - [Workflows](#workflows)
+    - [Projects](#projects)
+    - [API](#api)
+- [Development](#development)
+- [Acknowledgments](#acknowledgments)
 
 ## Usage
 
@@ -54,8 +55,8 @@ SHORTCUT_API_TOKEN=foobar short story 3300
 
 To skip `short install` entirely, set the additional environment variables used for URL and mention-name substitutions:
 
--   `SHORTCUT_URL_SLUG` – your workspace slug, e.g. `acme-co`
--   `SHORTCUT_MENTION_NAME` – your personal mention name used in branches, e.g. `mike`
+- `SHORTCUT_URL_SLUG` – your workspace slug, e.g. `acme-co`
+- `SHORTCUT_MENTION_NAME` – your personal mention name used in branches, e.g. `mike`
 
 With these env vars in place you can run commands directly:
 
@@ -87,6 +88,8 @@ short story 3300
     create          create a story
     workflows       list workflows and their states
     epics           list epics and their states
+    docs            list and search docs
+    doc             view, create, update, or delete a doc
     projects        list or search projects
     workspace       list stories matching saved workspace query
     api             make a request to the Shortcut API
@@ -320,6 +323,29 @@ Comment: This is a comment
     -h, --help                output usage information
 ```
 
+#### Epic Creation
+
+```
+  Usage: short epic create [options]
+
+  create a new epic
+
+
+  Options:
+
+    -n, --name [text]          Set name of epic, required
+    -d, --description [text]   Set description of epic
+    -s, --state [name]         Set state of epic (to do, in progress, done)
+    --deadline [date]          Set deadline for epic (YYYY-MM-DD)
+    --planned-start [date]     Set planned start date (YYYY-MM-DD)
+    -o, --owners [id|name]     Set owners of epic, comma-separated
+    -T, --team [id|name]       Set team of epic
+    -l, --label [id|name]      Set labels of epic, comma-separated
+    -I, --idonly               Print only ID of epic result
+    -O, --open                 Open epic in browser
+    -h, --help                 output usage information
+```
+
 #### Epic Output Formatting
 
 Templating variables:
@@ -340,6 +366,97 @@ Templating variables:
 %co      Print completed status of epic
 ```
 
+### Docs
+
+```
+  Usage: short docs [options]
+
+  List and search Shortcut Docs. By default, lists all docs you have access to.
+  Use --title to search docs by title.
+
+
+  Options:
+
+    -a, --archived      Search for archived docs (requires --title)
+    -m, --mine          Search for docs created by me (requires --title)
+    -f, --following     Search for docs I am following (requires --title)
+    -t, --title [text]  Search docs by title (required for search filters)
+    -q, --quiet         Print only doc output, no loading dialog
+    -I, --idonly        Print only IDs of doc results
+    -h, --help          output usage information
+```
+
+#### Doc View, Create, Update, Delete
+
+```
+  Usage: short doc [command] [options]
+
+  view, create, or update a doc
+
+
+  Commands:
+
+    view [options] <id>    view a doc by ID
+    create [options]       create a new doc
+    update [options] <id>  update an existing doc
+    delete [options] <id>  delete a doc
+```
+
+View a doc:
+
+```
+  Usage: short doc view <id> [options]
+
+  Options:
+
+    --html       Include HTML content in output
+    -O, --open   Open doc in browser
+    -q, --quiet  Print only doc content, no metadata
+    -h, --help   output usage information
+```
+
+You can also view a doc directly by ID: `short doc <uuid>`
+
+Create a doc:
+
+```
+  Usage: short doc create [options]
+
+  Options:
+
+    -t, --title <text>    Set title of doc (required)
+    -c, --content <text>  Set content of doc (required)
+    --markdown            Treat content as markdown (default is HTML)
+    -I, --idonly          Print only ID of doc result
+    -O, --open            Open doc in browser
+    -h, --help            output usage information
+```
+
+Update a doc:
+
+```
+  Usage: short doc update <id> [options]
+
+  Options:
+
+    -t, --title <text>    Update title of doc
+    -c, --content <text>  Update content of doc
+    --markdown            Treat content as markdown (default is HTML)
+    -O, --open            Open doc in browser
+    -h, --help            output usage information
+```
+
+Delete a doc:
+
+```
+  Usage: short doc delete <id> [options]
+
+  Options:
+
+    --confirm   Confirm deletion (required)
+    -h, --help  output usage information
+```
+
 ### Workflows
 
 ```
@@ -409,11 +526,11 @@ npm start -- story 1234
 
 ## Acknowledgments
 
--   [Repository for this code](https://github.com/shortcut-cli/shortcut-cli)
--   [NPM registry for this code](https://www.npmjs.com/package/@shortcut-cli/shortcut-cli)
--   [Shortcut API](https://shortcut.com/api/rest/v3)
--   Official [@shortcut/client](https://github.com/useshortcut/shortcut-client-js)
--   [joshbeckman](https://github.com/joshbeckman), [j-martin](https://github.com/j-martin), [joshmfrankel](https://github.com/joshmfrankel), and [ohe](https://github.com/ohe) who created and contributed to this project
+- [Repository for this code](https://github.com/shortcut-cli/shortcut-cli)
+- [NPM registry for this code](https://www.npmjs.com/package/@shortcut-cli/shortcut-cli)
+- [Shortcut API](https://shortcut.com/api/rest/v3)
+- Official [@shortcut/client](https://github.com/useshortcut/shortcut-client-js)
+- [joshbeckman](https://github.com/joshbeckman), [j-martin](https://github.com/j-martin), [joshmfrankel](https://github.com/joshmfrankel), and [ohe](https://github.com/ohe) who created and contributed to this project
 
 ## Contributors
 

package/build/bin/short-doc.js

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+const require_rolldown_runtime = require('../_virtual/rolldown_runtime.js');
+const require_lib_spinner = require('../lib/spinner.js');
+const require_lib_client = require('../lib/client.js');
+let commander = require("commander");
+commander = require_rolldown_runtime.__toESM(commander);
+let os = require("os");
+os = require_rolldown_runtime.__toESM(os);
+let child_process = require("child_process");
+let chalk = require("chalk");
+chalk = require_rolldown_runtime.__toESM(chalk);
+
+//#region src/bin/short-doc.ts
+const spin = require_lib_spinner.default();
+const log = console.log;
+const program = commander.default.usage("[command] [options]").description("view, create, or update a doc");
+program.command("view <id>").description("view a doc by ID").option("--html", "Include HTML content in output").option("-O, --open", "Open doc in browser").option("-q, --quiet", "Print only doc content, no metadata").action(viewDoc);
+program.command("create").description("create a new doc").option("-t, --title <text>", "Set title of doc (required)").option("-c, --content <text>", "Set content of doc (required)").option("--markdown", "Treat content as markdown (default is HTML)").option("-I, --idonly", "Print only ID of doc result").option("-O, --open", "Open doc in browser").action(createDoc);
+program.command("update <id>").description("update an existing doc").option("-t, --title <text>", "Update title of doc").option("-c, --content <text>", "Update content of doc").option("--markdown", "Treat content as markdown (default is HTML)").option("-O, --open", "Open doc in browser").action(updateDoc);
+program.command("delete <id>").description("delete a doc").option("--confirm", "Confirm deletion without prompting").action(deleteDoc);
+const args = process.argv.slice(2);
+if (args.length > 0 && isUUID(args[0])) process.argv.splice(2, 0, "view");
+program.parse(process.argv);
+if (args.length === 0) {
+	program.outputHelp();
+	process.exit(1);
+} else if (args.length > 0 && !isUUID(args[0])) {
+	if (![
+		"view",
+		"create",
+		"update",
+		"delete"
+	].includes(args[0]) && !args[0].startsWith("-")) {
+		console.error(`Error: Unknown command or invalid doc ID: ${args[0]}`);
+		console.error("Run \"short doc --help\" for usage information.");
+		process.exit(1);
+	}
+}
+function isUUID(str) {
+	return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(str);
+}
+async function viewDoc(id, options) {
+	if (!options.quiet) spin.start();
+	let doc;
+	try {
+		const params = {};
+		if (options.html) params.content_format = "html";
+		doc = await require_lib_client.default.getDoc(id, params).then((r) => r.data);
+	} catch (e) {
+		if (!options.quiet) spin.stop(true);
+		log("Error fetching doc:", e.message || e);
+		process.exit(1);
+	}
+	if (!options.quiet) spin.stop(true);
+	if (options.quiet) log(doc.content_markdown || doc.content_html || "(No content)");
+	else printDoc(doc, options.html);
+	if (options.open) openURL(doc.app_url);
+}
+async function createDoc(options) {
+	if (!options.title) {
+		log("Must provide --title");
+		process.exit(1);
+	}
+	if (!options.content) {
+		log("Must provide --content");
+		process.exit(1);
+	}
+	if (!options.idonly) spin.start();
+	const docData = {
+		title: options.title,
+		content: options.content,
+		content_format: options.markdown ? "markdown" : "html"
+	};
+	let doc;
+	try {
+		const result = await require_lib_client.default.createDoc(docData);
+		doc = await require_lib_client.default.getDoc(result.data.id).then((r) => r.data);
+	} catch (e) {
+		if (!options.idonly) spin.stop(true);
+		log("Error creating doc:", e.message || e);
+		process.exit(1);
+	}
+	if (!options.idonly) spin.stop(true);
+	if (options.idonly) log(doc.id);
+	else {
+		log(chalk.default.green("Doc created successfully!"));
+		printDoc(doc);
+	}
+	if (options.open) openURL(doc.app_url);
+}
+async function updateDoc(id, options) {
+	if (!options.title && !options.content) {
+		log("Must provide --title and/or --content to update");
+		process.exit(1);
+	}
+	spin.start();
+	const docData = {};
+	if (options.title) docData.title = options.title;
+	if (options.content) {
+		docData.content = options.content;
+		docData.content_format = options.markdown ? "markdown" : "html";
+	}
+	let doc;
+	try {
+		doc = await require_lib_client.default.updateDoc(id, docData).then((r) => r.data);
+	} catch (e) {
+		spin.stop(true);
+		log("Error updating doc:", e.message || e);
+		process.exit(1);
+	}
+	spin.stop(true);
+	log(chalk.default.green("Doc updated successfully!"));
+	printDoc(doc);
+	if (options.open) openURL(doc.app_url);
+}
+async function deleteDoc(id, options) {
+	if (!options.confirm) {
+		log("Deletion requires --confirm flag");
+		log("Usage: short doc delete <id> --confirm");
+		process.exit(1);
+	}
+	spin.start();
+	try {
+		await require_lib_client.default.deleteDoc(id, {});
+	} catch (e) {
+		spin.stop(true);
+		log("Error deleting doc:", e.message || e);
+		process.exit(1);
+	}
+	spin.stop(true);
+	log(chalk.default.green(`Doc ${id} deleted successfully.`));
+}
+function printDoc(doc, includeHtml = false) {
+	log(chalk.default.blue.bold(doc.title || "(Untitled)"));
+	log(chalk.default.bold("ID:") + `       ${doc.id}`);
+	log(chalk.default.bold("URL:") + `      ${doc.app_url}`);
+	log(chalk.default.bold("Created:") + `  ${doc.created_at}`);
+	if (doc.created_at !== doc.updated_at) log(chalk.default.bold("Updated:") + `  ${doc.updated_at}`);
+	if (doc.archived) log(chalk.default.bold("Archived:") + ` ${doc.archived}`);
+	log();
+	if (doc.content_markdown) {
+		log(chalk.default.bold("Content (Markdown):"));
+		log(doc.content_markdown);
+	}
+	if (includeHtml && doc.content_html) {
+		log();
+		log(chalk.default.bold("Content (HTML):"));
+		log(doc.content_html);
+	}
+}
+function openURL(url) {
+	(0, child_process.exec)(`${os.default.platform() === "darwin" ? "open" : "xdg-open"} '${url}'`);
+}
+
+//#endregion

package/build/bin/short-docs.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+const require_rolldown_runtime = require('../_virtual/rolldown_runtime.js');
+const require_lib_spinner = require('../lib/spinner.js');
+const require_lib_client = require('../lib/client.js');
+let commander = require("commander");
+commander = require_rolldown_runtime.__toESM(commander);
+
+//#region src/bin/short-docs.ts
+const spin = require_lib_spinner.default("Loading docs... %s ");
+const log = console.log;
+const program = commander.default.description(`List and search Shortcut Docs. By default, lists all docs you have access to.
+  Use --title to search docs by title.`).usage("[options]").option("-a, --archived", "Search for archived docs (requires --title)").option("-m, --mine", "Search for docs created by me (requires --title)").option("-f, --following", "Search for docs I am following (requires --title)").option("-t, --title [text]", "Search docs by title (required for search filters)").option("-q, --quiet", "Print only doc output, no loading dialog").option("-I, --idonly", "Print only IDs of doc results").parse(process.argv);
+const main = async () => {
+	if (!program.quiet) spin.start();
+	let docs = [];
+	try {
+		if (program.title) {
+			const searchParams = { title: program.title };
+			if (program.archived !== void 0) searchParams.archived = !!program.archived;
+			if (program.mine) searchParams.created_by_me = true;
+			if (program.following) searchParams.followed_by_me = true;
+			docs = (await require_lib_client.default.searchDocuments(searchParams)).data.data;
+		} else {
+			if (program.archived || program.mine || program.following) {
+				if (!program.quiet) spin.stop(true);
+				log("Note: --archived, --mine, and --following require --title for searching.");
+				log("Listing all docs instead...");
+				if (!program.quiet) spin.start();
+			}
+			docs = (await require_lib_client.default.listDocs()).data;
+		}
+	} catch (e) {
+		if (!program.quiet) spin.stop(true);
+		log("Error fetching docs:", e.message || e);
+		process.exit(1);
+	}
+	if (!program.quiet) spin.stop(true);
+	if (docs.length === 0) {
+		log("No docs found.");
+		return;
+	}
+	docs.forEach((doc) => printDoc(doc));
+};
+const printDoc = (doc) => {
+	if (program.idonly) return log(doc.id);
+	log(`${doc.id} ${doc.title || "(Untitled)"}`);
+	log(`\tURL: ${doc.app_url}`);
+};
+main();
+
+//#endregion

package/build/bin/short-epic.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+const require_rolldown_runtime = require('../_virtual/rolldown_runtime.js');
+const require_lib_spinner = require('../lib/spinner.js');
+const require_lib_configure = require('../lib/configure.js');
+const require_lib_client = require('../lib/client.js');
+const require_lib_stories = require('../lib/stories.js');
+let commander = require("commander");
+commander = require_rolldown_runtime.__toESM(commander);
+let child_process = require("child_process");
+
+//#region src/bin/short-epic.ts
+const config = require_lib_configure.loadConfig();
+const spin = require_lib_spinner.default();
+const log = console.log;
+const program = commander.default.usage("[command] [options]").description("create or view epics");
+program.command("create").description("create a new epic").option("-n, --name [text]", "Set name of epic, required", "").option("-d, --description [text]", "Set description of epic", "").option("-s, --state [name]", "Set state of epic (to do, in progress, done)", "").option("--deadline [date]", "Set deadline for epic (YYYY-MM-DD)", "").option("--planned-start [date]", "Set planned start date (YYYY-MM-DD)", "").option("-o, --owners [id|name]", "Set owners of epic, comma-separated", "").option("-T, --team [id|name]", "Set team of epic", "").option("-l, --label [id|name]", "Set labels of epic, comma-separated", "").option("-M, --milestone [id]", "Set milestone of epic (deprecated, use objectives)", "").option("-I, --idonly", "Print only ID of epic result").option("-O, --open", "Open epic in browser").action(createEpic);
+program.parse(process.argv);
+async function createEpic(options) {
+	const entities = await require_lib_stories.default.fetchEntities();
+	if (!options.idonly) spin.start();
+	const epicData = { name: options.name };
+	if (options.description) epicData.description = options.description;
+	if (options.state) {
+		const stateMap = {
+			todo: "to do",
+			"to do": "to do",
+			inprogress: "in progress",
+			"in progress": "in progress",
+			done: "done"
+		};
+		const mappedState = stateMap[options.state.toLowerCase().replace(/[^a-z]/g, "")] || stateMap[options.state.toLowerCase()];
+		if (mappedState) epicData.state = mappedState;
+	}
+	if (options.deadline) epicData.deadline = new Date(options.deadline).toISOString();
+	if (options.plannedStart) epicData.planned_start_date = new Date(options.plannedStart).toISOString();
+	if (options.owners) epicData.owner_ids = require_lib_stories.default.findOwnerIds(entities, options.owners);
+	if (options.team) {
+		const group = require_lib_stories.default.findGroup(entities, options.team);
+		if (group === null || group === void 0 ? void 0 : group.id) epicData.group_ids = [group.id];
+	}
+	if (options.label) epicData.labels = require_lib_stories.default.findLabelNames(entities, options.label);
+	if (options.milestone) epicData.milestone_id = parseInt(options.milestone, 10);
+	let epic;
+	if (!epicData.name) {
+		if (!options.idonly) spin.stop(true);
+		log("Must provide --name");
+		process.exit(1);
+	} else try {
+		epic = await require_lib_client.default.createEpic(epicData).then((r) => r.data);
+	} catch (e) {
+		if (!options.idonly) spin.stop(true);
+		log("Error creating epic:", e.message || e);
+		process.exit(1);
+	}
+	if (!options.idonly) spin.stop(true);
+	if (epic) if (options.idonly) log(epic.id);
+	else {
+		printEpic(epic);
+		if (options.open) (0, child_process.exec)(`open https://app.shortcut.com/${config.urlSlug}/epic/${epic.id}`);
+	}
+}
+function printEpic(epic) {
+	log(`#${epic.id} ${epic.name}`);
+	if (epic.description) log(`Description:\t${epic.description}`);
+	log(`State:\t\t${epic.state}`);
+	if (epic.milestone_id) log(`Milestone:\t${epic.milestone_id}`);
+	if (epic.deadline) log(`Deadline:\t${epic.deadline}`);
+	if (epic.planned_start_date) log(`Planned Start:\t${epic.planned_start_date}`);
+	if (epic.owner_ids && epic.owner_ids.length > 0) log(`Owners:\t\t${epic.owner_ids.join(", ")}`);
+	if (epic.group_ids && epic.group_ids.length > 0) log(`Teams:\t\t${epic.group_ids.join(", ")}`);
+	if (epic.labels && epic.labels.length > 0) log(`Labels:\t\t${epic.labels.map((l) => l.name).join(", ")}`);
+	log(`URL:\t\t${epic.app_url}`);
+}
+
+//#endregion

package/build/bin/short.js

@@ -6,6 +6,6 @@ commander = require_rolldown_runtime.__toESM(commander);
 
 //#region src/bin/short.ts
 process.on("unhandledRejection", console.log);
-commander.default.version(require_package.version).description(require_package.description).command("install [options]", "install and configure API access").command("search [options] [SEARCH OPERATORS]", "search stories with optional query").alias("s").command("find [options] [SEARCH OPERATORS]", "[DEPRECATED] search stories with optional query").command("story ID [options]", "view or manipulate stories").alias("st").command("create [options]", "create a story").alias("c").command("members [options]", "list members").alias("m").command("workflows [options]", "list workflows and their states").alias("wf").command("epics [options]", "list epics and their states").alias("e").command("projects [options]", "list projects and their states").alias("p").command("workspace [NAME] [options]", "list stories matching saved workspace query", { isDefault: true }).alias("w").command("api <path> [options]", "make a request to the Shortcut API").parse(process.argv);
+commander.default.version(require_package.version).description(require_package.description).command("install [options]", "install and configure API access").command("search [options] [SEARCH OPERATORS]", "search stories with optional query").alias("s").command("find [options] [SEARCH OPERATORS]", "[DEPRECATED] search stories with optional query").command("story ID [options]", "view or manipulate stories").alias("st").command("create [options]", "create a story").alias("c").command("members [options]", "list members").alias("m").command("workflows [options]", "list workflows and their states").alias("wf").command("epics [options]", "list epics and their states").alias("e").command("epic [command] [options]", "create or view an epic").command("docs [options]", "list and search docs").alias("d").command("doc [command] [options]", "view, create, or update a doc").command("projects [options]", "list projects and their states").alias("p").command("workspace [NAME] [options]", "list stories matching saved workspace query", { isDefault: true }).alias("w").command("api <path> [options]", "make a request to the Shortcut API").parse(process.argv);
 
 //#endregion

package/build/package.js

@@ -1,6 +1,6 @@
 
 //#region package.json
-var version = "3.7.0";
+var version = "3.8.0";
 var description = "A community-driven command line tool for viewing, creating, and updating shortcut.com stories";
 
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shortcut-cli/shortcut-cli",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "description": "A community-driven command line tool for viewing, creating, and updating shortcut.com stories",
   "engines": {
     "node": ">=16"
@@ -40,7 +40,7 @@
   },
   "homepage": "https://github.com/shortcut-cli/shortcut-cli",
   "dependencies": {
-    "@shortcut/client": "^2.3.1",
+    "@shortcut/client": "^3.1.0",
     "chalk": "^2.2.0",
     "cli-spinner": "^0.2.10",
     "commander": "^2.12.0",