@pxlabz/tasq-cli 0.1.4 → 0.1.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.tasq-skill.md +31 -2
- package/dist/tasq.js +235 -3
- package/examples/release-narrator.sh +142 -0
- package/package.json +2 -2
package/.tasq-skill.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: tasq
|
|
3
|
-
description: Read and write Tasq tasks, projects, threads, comments and mentions from the shell with the `tasq` CLI. Use when you are working in a repository whose issues live in Tasq, when someone asks you to look at a task by its key (ENG-42), when you need to comment on or update a task, or when you are running as a Tasq agent and want to receive the mentions and thread messages addressed to you. Covers authentication, the full command reference, the mention-reply-ack workflow, threads, exit codes, and working alongside other agents.
|
|
3
|
+
description: Read and write Tasq tasks, projects, threads, comments and mentions from the shell with the `tasq` CLI. Use when you are working in a repository whose issues live in Tasq, when someone asks you to look at a task by its key (ENG-42), when you need to comment on or update a task, or when you are running as a Tasq agent and want to receive the mentions and thread messages addressed to you. Covers authentication, the full command reference, the mention-reply-ack workflow, threads, release narratives, exit codes, and working alongside other agents.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Tasq
|
|
@@ -61,6 +61,13 @@ tasq events ack <id>…
|
|
|
61
61
|
tasq project list
|
|
62
62
|
tasq cycle current [--team <identifier>]
|
|
63
63
|
|
|
64
|
+
tasq release list [--team <identifier>]
|
|
65
|
+
tasq release view <releaseId>
|
|
66
|
+
tasq release context <releaseId> [--markdown]
|
|
67
|
+
tasq release diff <releaseId>
|
|
68
|
+
tasq release export <releaseId> [--out <file>]
|
|
69
|
+
tasq release narrate <releaseId> (--body <markdown> | --file <path>)
|
|
70
|
+
|
|
64
71
|
tasq auth login [--email <email>]
|
|
65
72
|
tasq auth logout
|
|
66
73
|
tasq auth whoami
|
|
@@ -76,7 +83,7 @@ A comment goes on a task or a project, never both and never neither: give the ta
|
|
|
76
83
|
|
|
77
84
|
## When you are mentioned
|
|
78
85
|
|
|
79
|
-
`tasq events listen` prints NDJSON — one compact JSON object per line, per event — whatever `--json` says, because it is meant to be read by a loop. Each object carries ids only: `{ id, kind, workspace, taskId, taskKey, projectId, threadId, commentId, mentionedBy, deliveryCount, createdAt }`. `kind` is `mention` or `
|
|
86
|
+
`tasq events listen` prints NDJSON — one compact JSON object per line, per event — whatever `--json` says, because it is meant to be read by a loop. Each object carries ids only: `{ id, kind, workspace, taskId, taskKey, projectId, threadId, commentId, releaseId, mentionedBy, deliveryCount, createdAt }`. `kind` is `mention`, `thread_message` or `cycle_closed`; on the first two exactly one of `taskId` and `projectId` is set, and `mentionedBy` carries `{ memberId, type, name }` whose `type` is `user` or `agent`. On a `cycle_closed` every one of those is null and only `releaseId` is set — see **Release narratives**. There is no comment body in the event, on purpose: every read you make from those ids goes through your policy, so you see exactly what you are allowed to see.
|
|
80
87
|
|
|
81
88
|
The loop is:
|
|
82
89
|
|
|
@@ -120,6 +127,28 @@ Acknowledge both kinds the same way, with `tasq events ack <eventId>`, and only
|
|
|
120
127
|
|
|
121
128
|
On an isolated team — the default — another agent's messages do not reach you and yours do not wake another agent, so a thread that needs work you cannot do is a thread to escalate to a person. See **Working with other agents** below.
|
|
122
129
|
|
|
130
|
+
## Release narratives
|
|
131
|
+
|
|
132
|
+
When a cycle closes, Tasq writes a **release**: the number, the dates, and every task in the cycle classified as shipped, carried over or dropped, with the ones that arrived mid-cycle marked. It writes that row itself, from the close snapshot, whether or not any agent is connected. The **narrative** is the Markdown body attached to it afterwards, and that is the part you write.
|
|
133
|
+
|
|
134
|
+
If you are set as a team's release narrator, each close sends you one `cycle_closed` event. It is the only event kind that carries a `releaseId`, and it carries nothing else: `taskId`, `taskKey`, `projectId`, `threadId`, `commentId` and `mentionedBy` are all null, because a cycle close is not somebody talking to you. The `releaseId` is the whole payload.
|
|
135
|
+
|
|
136
|
+
The loop is:
|
|
137
|
+
|
|
138
|
+
1. **Listen.** `tasq events listen --wait 20`, the same listener as for mentions. Filter on `kind == "cycle_closed"` and read `.releaseId`.
|
|
139
|
+
2. **Read the release.** `tasq release context <releaseId>` prints a Markdown prompt: the cycle and its dates, the shipped / carried over / dropped lists, the change against the previous release, and the previous narrative. `--json` gives the same bundle raw. Each task list is capped at 100; a cut list says so.
|
|
140
|
+
3. **Write it.** Prose about what the cycle did, for the people who were not in it. The diff and the counts are already on the page — do not just restate them.
|
|
141
|
+
4. **Save it.** `tasq release narrate <releaseId> --file notes.md`, or `--body "…"` for a short one, or pipe the body in with neither flag. The cap is 50,000 characters.
|
|
142
|
+
5. **Acknowledge.** `tasq events ack <eventId>`, last, as always.
|
|
143
|
+
|
|
144
|
+
Three things to know before you write:
|
|
145
|
+
|
|
146
|
+
- **The release already exists.** Nothing waits on you. If you never answer, the release stands with an empty narrative and the team still sees what shipped.
|
|
147
|
+
- **It is one field, last write wins.** There is no thread and no version history: `release narrate` replaces whatever is there. A person may have written or edited it in the web app before you ran, and a person may replace yours afterwards. Your name and the time are shown next to it either way, so read the release before overwriting a narrative that is already good.
|
|
148
|
+
- **It is not a thread event.** Isolation and the loop caps govern agents waking agents in conversations; a cycle close is Tasq waking one agent. Neither applies, and your narrative wakes nobody.
|
|
149
|
+
|
|
150
|
+
`tasq release list --team ENG` is the timeline, newest first; `tasq release view <releaseId>` shows one in full; `tasq release export <releaseId>` prints it as Markdown for a changelog. `examples/release-narrator.sh` in this package is a working reference for the loop above, minus the writing.
|
|
151
|
+
|
|
123
152
|
## Exit codes
|
|
124
153
|
|
|
125
154
|
| Code | Meaning |
|
package/dist/tasq.js
CHANGED
|
@@ -6570,6 +6570,30 @@ var TasqClient = class _TasqClient {
|
|
|
6570
6570
|
}
|
|
6571
6571
|
return await response.json();
|
|
6572
6572
|
}
|
|
6573
|
+
/**
|
|
6574
|
+
* A read whose body is Markdown rather than JSON.
|
|
6575
|
+
*
|
|
6576
|
+
* The export and the `format=markdown` context are documents, not
|
|
6577
|
+
* envelopes, so they are read as text. Errors still arrive as the JSON
|
|
6578
|
+
* envelope every other route uses, so the failure path is `#toError`'s,
|
|
6579
|
+
* unchanged.
|
|
6580
|
+
*/
|
|
6581
|
+
async #text(path, params, options) {
|
|
6582
|
+
const headers = new Headers({ accept: "text/markdown" });
|
|
6583
|
+
if (this.#token === void 0) throw noCredentialError();
|
|
6584
|
+
headers.set("authorization", `Bearer ${this.#token}`);
|
|
6585
|
+
const timeout = options?.timeoutMs === void 0 ? void 0 : AbortSignal.timeout(options.timeoutMs);
|
|
6586
|
+
const signals = [options?.signal, timeout].filter(
|
|
6587
|
+
(candidate) => candidate != null
|
|
6588
|
+
);
|
|
6589
|
+
const signal = signals.length === 0 ? void 0 : signals.length === 1 ? signals[0] : AbortSignal.any(signals);
|
|
6590
|
+
const response = await this.#fetch(
|
|
6591
|
+
`${this.#baseUrl}${path}${queryString(params)}`,
|
|
6592
|
+
{ headers, signal }
|
|
6593
|
+
);
|
|
6594
|
+
if (!response.ok) throw await this.#toError(response);
|
|
6595
|
+
return await response.text();
|
|
6596
|
+
}
|
|
6573
6597
|
async #toError(response) {
|
|
6574
6598
|
const retryAfter = response.headers.get("retry-after");
|
|
6575
6599
|
const fallback = {
|
|
@@ -6676,6 +6700,43 @@ var TasqClient = class _TasqClient {
|
|
|
6676
6700
|
options
|
|
6677
6701
|
)
|
|
6678
6702
|
};
|
|
6703
|
+
/**
|
|
6704
|
+
* Releases: the structural record of a cycle close, and the narrative an
|
|
6705
|
+
* agent or a person attaches to it (B-04d).
|
|
6706
|
+
*
|
|
6707
|
+
* Reads are authorized by the workspace role guard rather than a policy
|
|
6708
|
+
* action, so a read-only agent may pull the context it needs; the write
|
|
6709
|
+
* goes through `release.saveNarrative` like every other action.
|
|
6710
|
+
*/
|
|
6711
|
+
releases = {
|
|
6712
|
+
list: async (slug, teamIdentifier) => (await this.#get(
|
|
6713
|
+
`/workspaces/${encodeURIComponent(slug)}/releases`,
|
|
6714
|
+
{ team: teamIdentifier }
|
|
6715
|
+
)).releases,
|
|
6716
|
+
get: async (slug, releaseId) => (await this.#get(
|
|
6717
|
+
`/workspaces/${encodeURIComponent(slug)}/releases/${encodeURIComponent(releaseId)}`
|
|
6718
|
+
)).release,
|
|
6719
|
+
/**
|
|
6720
|
+
* The context bundle a narrator writes from.
|
|
6721
|
+
*
|
|
6722
|
+
* `format: "markdown"` returns the server-rendered prompt as a string,
|
|
6723
|
+
* which is what a harness pastes into a model; the default returns the
|
|
6724
|
+
* bundle, for a runner that branches on the fields itself.
|
|
6725
|
+
*/
|
|
6726
|
+
context: ((slug, releaseId, options = {}) => {
|
|
6727
|
+
const path = `/workspaces/${encodeURIComponent(slug)}/releases/${encodeURIComponent(releaseId)}/context`;
|
|
6728
|
+
return options.format === "markdown" ? this.#text(path, { format: "markdown" }, options) : this.#get(path, void 0, options);
|
|
6729
|
+
}),
|
|
6730
|
+
diff: async (slug, releaseId) => (await this.#get(
|
|
6731
|
+
`/workspaces/${encodeURIComponent(slug)}/releases/${encodeURIComponent(releaseId)}/diff`
|
|
6732
|
+
)).diff,
|
|
6733
|
+
/** The release as a Markdown document, the same body the web export serves. */
|
|
6734
|
+
export: (slug, releaseId) => this.#text(
|
|
6735
|
+
`/workspaces/${encodeURIComponent(slug)}/releases/${encodeURIComponent(releaseId)}/export`
|
|
6736
|
+
),
|
|
6737
|
+
/** Last write wins; the author and timestamp move with the body (D-3). */
|
|
6738
|
+
saveNarrative: (slug, input) => this.dispatch("release.saveNarrative", slug, input)
|
|
6739
|
+
};
|
|
6679
6740
|
members = {
|
|
6680
6741
|
list: async (slug) => (await this.#get(
|
|
6681
6742
|
`/workspaces/${encodeURIComponent(slug)}/members`
|
|
@@ -6721,6 +6782,7 @@ var TasqClient = class _TasqClient {
|
|
|
6721
6782
|
// ../sdk/src/types.ts
|
|
6722
6783
|
var MAX_AGENT_WAKES_PER_MESSAGE = 10;
|
|
6723
6784
|
var MAX_CONSECUTIVE_AGENT_MESSAGES = 5;
|
|
6785
|
+
var RELEASE_NARRATIVE_MAX = 5e4;
|
|
6724
6786
|
|
|
6725
6787
|
// src/errors.ts
|
|
6726
6788
|
var EXIT_OK = 0;
|
|
@@ -6783,7 +6845,7 @@ function reportError(error, io2) {
|
|
|
6783
6845
|
// package.json
|
|
6784
6846
|
var package_default = {
|
|
6785
6847
|
name: "@pxlabz/tasq-cli",
|
|
6786
|
-
version: "0.1.
|
|
6848
|
+
version: "0.1.6",
|
|
6787
6849
|
description: "Command-line client for Tasq, for humans and agents alike",
|
|
6788
6850
|
keywords: [
|
|
6789
6851
|
"tasq",
|
|
@@ -6976,6 +7038,21 @@ function formatCycles(cycles) {
|
|
|
6976
7038
|
])
|
|
6977
7039
|
);
|
|
6978
7040
|
}
|
|
7041
|
+
function formatReleases(releases) {
|
|
7042
|
+
if (releases.length === 0) return "No releases.";
|
|
7043
|
+
return table(
|
|
7044
|
+
["#", "Cycle", "Closed", "Shipped", "Carried", "Dropped", "Narrative by"],
|
|
7045
|
+
releases.map((release) => [
|
|
7046
|
+
String(release.number),
|
|
7047
|
+
dash(release.cycleName),
|
|
7048
|
+
release.closedAt.slice(0, 10),
|
|
7049
|
+
String(release.counts.shipped),
|
|
7050
|
+
String(release.counts.carriedOver),
|
|
7051
|
+
String(release.counts.dropped),
|
|
7052
|
+
dash(release.narrativeAuthor?.name)
|
|
7053
|
+
])
|
|
7054
|
+
);
|
|
7055
|
+
}
|
|
6979
7056
|
function formatWorkspaces(workspaces) {
|
|
6980
7057
|
if (workspaces.length === 0) return "No workspaces.";
|
|
6981
7058
|
return table(
|
|
@@ -7343,6 +7420,140 @@ async function projectList(ctx) {
|
|
|
7343
7420
|
ctx.io.out(ctx.config.json ? jsonOutput(projects) : formatProjects(projects));
|
|
7344
7421
|
}
|
|
7345
7422
|
|
|
7423
|
+
// src/commands/release.ts
|
|
7424
|
+
import { writeFileSync as writeFileSync2 } from "fs";
|
|
7425
|
+
import { readFileSync as readFileSync2 } from "fs";
|
|
7426
|
+
async function releaseList(ctx, options) {
|
|
7427
|
+
const slug = requireWorkspace(ctx.config);
|
|
7428
|
+
const releases = await ctx.client.releases.list(slug, options.team);
|
|
7429
|
+
ctx.io.out(ctx.config.json ? jsonOutput(releases) : formatReleases(releases));
|
|
7430
|
+
}
|
|
7431
|
+
function taskLine(task) {
|
|
7432
|
+
const suffix = task.addedMidCycle ? " (added mid-cycle)" : "";
|
|
7433
|
+
return ` ${task.taskIdentifier} \u2014 ${task.title}${suffix}`;
|
|
7434
|
+
}
|
|
7435
|
+
function taskList(io2, heading, tasks) {
|
|
7436
|
+
io2.out(`${heading} (${tasks.length})`);
|
|
7437
|
+
if (tasks.length === 0) {
|
|
7438
|
+
io2.out(" \u2014");
|
|
7439
|
+
} else {
|
|
7440
|
+
for (const task of tasks) io2.out(taskLine(task));
|
|
7441
|
+
}
|
|
7442
|
+
io2.out("");
|
|
7443
|
+
}
|
|
7444
|
+
function countsLine(release) {
|
|
7445
|
+
const { shipped, carriedOver, dropped, addedMidCycle } = release.counts;
|
|
7446
|
+
return `Shipped ${shipped} \xB7 carried over ${carriedOver} \xB7 dropped ${dropped} \xB7 added mid-cycle ${addedMidCycle}`;
|
|
7447
|
+
}
|
|
7448
|
+
async function releaseView(ctx, releaseId) {
|
|
7449
|
+
const slug = requireWorkspace(ctx.config);
|
|
7450
|
+
const release = await ctx.client.releases.get(slug, releaseId);
|
|
7451
|
+
if (ctx.config.json) {
|
|
7452
|
+
ctx.io.out(jsonOutput(release));
|
|
7453
|
+
return;
|
|
7454
|
+
}
|
|
7455
|
+
ctx.io.out(`${release.teamIdentifier} \u2014 Release ${release.number}`);
|
|
7456
|
+
ctx.io.out(`${release.cycleName ?? "unnamed cycle"} closed ${release.closedAt}`);
|
|
7457
|
+
ctx.io.out(countsLine(release));
|
|
7458
|
+
ctx.io.out("");
|
|
7459
|
+
const author = release.narrativeAuthor;
|
|
7460
|
+
ctx.io.out(
|
|
7461
|
+
author === null ? "Narrative" : `Narrative \u2014 ${author.name ?? "unknown"} (${author.type ?? "unknown"}, ${author.updatedAt})`
|
|
7462
|
+
);
|
|
7463
|
+
ctx.io.out("");
|
|
7464
|
+
ctx.io.out(release.narrative ?? "_No narrative yet._");
|
|
7465
|
+
ctx.io.out("");
|
|
7466
|
+
const by = (disposition) => release.tasks.filter((task) => task.disposition === disposition);
|
|
7467
|
+
taskList(ctx.io, "Shipped", by("shipped"));
|
|
7468
|
+
taskList(ctx.io, "Carried over", by("carried_over"));
|
|
7469
|
+
taskList(ctx.io, "Dropped", by("dropped"));
|
|
7470
|
+
}
|
|
7471
|
+
async function releaseContext(ctx, releaseId, _options = {}) {
|
|
7472
|
+
const slug = requireWorkspace(ctx.config);
|
|
7473
|
+
if (ctx.config.json) {
|
|
7474
|
+
const bundle = await ctx.client.releases.context(slug, releaseId);
|
|
7475
|
+
ctx.io.out(jsonOutput(bundle));
|
|
7476
|
+
return;
|
|
7477
|
+
}
|
|
7478
|
+
ctx.io.out(
|
|
7479
|
+
await ctx.client.releases.context(slug, releaseId, {
|
|
7480
|
+
format: "markdown"
|
|
7481
|
+
})
|
|
7482
|
+
);
|
|
7483
|
+
}
|
|
7484
|
+
function diffList(io2, heading, tasks) {
|
|
7485
|
+
taskList(io2, heading, tasks);
|
|
7486
|
+
}
|
|
7487
|
+
async function releaseDiff(ctx, releaseId) {
|
|
7488
|
+
const slug = requireWorkspace(ctx.config);
|
|
7489
|
+
const diff = await ctx.client.releases.diff(slug, releaseId);
|
|
7490
|
+
if (ctx.config.json) {
|
|
7491
|
+
ctx.io.out(jsonOutput(diff));
|
|
7492
|
+
return;
|
|
7493
|
+
}
|
|
7494
|
+
ctx.io.out(
|
|
7495
|
+
diff.previousReleaseNumber === null ? "No previous release: this is the first release for this team." : `Compared with release ${diff.previousReleaseNumber}`
|
|
7496
|
+
);
|
|
7497
|
+
ctx.io.out("");
|
|
7498
|
+
diffList(ctx.io, "Added", diff.added);
|
|
7499
|
+
diffList(ctx.io, "Completed", diff.completed);
|
|
7500
|
+
diffList(ctx.io, "Still carried", diff.carried);
|
|
7501
|
+
diffList(ctx.io, "Dropped since", diff.dropped);
|
|
7502
|
+
}
|
|
7503
|
+
async function releaseExport(ctx, releaseId, options, deps = {}) {
|
|
7504
|
+
const slug = requireWorkspace(ctx.config);
|
|
7505
|
+
const markdown = await ctx.client.releases.export(slug, releaseId);
|
|
7506
|
+
if (options.out === void 0) {
|
|
7507
|
+
ctx.io.out(markdown);
|
|
7508
|
+
return;
|
|
7509
|
+
}
|
|
7510
|
+
const write = deps.writeFile ?? ((path, body) => writeFileSync2(path, body));
|
|
7511
|
+
write(options.out, markdown);
|
|
7512
|
+
ctx.io.err(`Wrote ${options.out}`);
|
|
7513
|
+
}
|
|
7514
|
+
async function narrativeBody(options, deps) {
|
|
7515
|
+
if (options.body !== void 0 && options.file !== void 0) {
|
|
7516
|
+
throw new UsageError(
|
|
7517
|
+
"Pass --body or --file, not both. With neither, the body is read from stdin."
|
|
7518
|
+
);
|
|
7519
|
+
}
|
|
7520
|
+
if (options.body !== void 0) return options.body;
|
|
7521
|
+
if (options.file !== void 0) {
|
|
7522
|
+
const read = deps.readFile ?? ((path) => readFileSync2(path, "utf8"));
|
|
7523
|
+
return read(options.file);
|
|
7524
|
+
}
|
|
7525
|
+
const readStdin = deps.readStdin ?? defaultReadStdin;
|
|
7526
|
+
return await readStdin();
|
|
7527
|
+
}
|
|
7528
|
+
async function defaultReadStdin() {
|
|
7529
|
+
const chunks = [];
|
|
7530
|
+
for await (const chunk of process.stdin) chunks.push(chunk);
|
|
7531
|
+
return Buffer.concat(chunks).toString("utf8");
|
|
7532
|
+
}
|
|
7533
|
+
async function releaseNarrate(ctx, releaseId, options, deps = {}) {
|
|
7534
|
+
const slug = requireWorkspace(ctx.config);
|
|
7535
|
+
const narrative = await narrativeBody(options, deps);
|
|
7536
|
+
if (narrative.trim() === "") {
|
|
7537
|
+
throw new UsageError(
|
|
7538
|
+
"The narrative is empty. Pass --body, --file, or pipe the body in."
|
|
7539
|
+
);
|
|
7540
|
+
}
|
|
7541
|
+
if (narrative.length > RELEASE_NARRATIVE_MAX) {
|
|
7542
|
+
throw new UsageError(
|
|
7543
|
+
`The narrative is ${narrative.length} characters; the limit is ${RELEASE_NARRATIVE_MAX}.`
|
|
7544
|
+
);
|
|
7545
|
+
}
|
|
7546
|
+
const { result } = await ctx.client.releases.saveNarrative(slug, {
|
|
7547
|
+
releaseId,
|
|
7548
|
+
narrative
|
|
7549
|
+
});
|
|
7550
|
+
if (ctx.config.json) {
|
|
7551
|
+
ctx.io.out(jsonOutput(result.release));
|
|
7552
|
+
return;
|
|
7553
|
+
}
|
|
7554
|
+
ctx.io.out(`Narrative saved on release ${result.release.number}.`);
|
|
7555
|
+
}
|
|
7556
|
+
|
|
7346
7557
|
// src/render/thread-context.ts
|
|
7347
7558
|
function entityHeading(entity) {
|
|
7348
7559
|
return entity.key === null ? `**${entity.title}**` : `**${entity.key}** \u2014 ${entity.title}`;
|
|
@@ -7480,7 +7691,7 @@ function filters(options) {
|
|
|
7480
7691
|
);
|
|
7481
7692
|
return Object.fromEntries(entries);
|
|
7482
7693
|
}
|
|
7483
|
-
async function
|
|
7694
|
+
async function taskList2(ctx, options) {
|
|
7484
7695
|
const slug = requireWorkspace(ctx.config);
|
|
7485
7696
|
const query = filters(options);
|
|
7486
7697
|
if (options.status !== void 0) {
|
|
@@ -7688,7 +7899,7 @@ function buildProgram(io2) {
|
|
|
7688
7899
|
});
|
|
7689
7900
|
const task = program2.command("task").description("Tasks");
|
|
7690
7901
|
task.command("list").description("List tasks").option("--team <identifier>", "team identifier").option("--status <name>", "status name").option("--assignee <id>", "assignee member id").option("--priority <priority>", "urgent | high | medium | low | none").option("--project <id>", "project id").option("--cycle <id>", "cycle id").option("-q, --q <text>", "search text").option("--include-archived", "include archived tasks").action(async (options) => {
|
|
7691
|
-
await
|
|
7902
|
+
await taskList2(contextFor(program2, io2), {
|
|
7692
7903
|
team: options.team,
|
|
7693
7904
|
status: options.status,
|
|
7694
7905
|
assignee: options.assignee,
|
|
@@ -7770,6 +7981,27 @@ function buildProgram(io2) {
|
|
|
7770
7981
|
cycle.command("current").description("Show the active cycle and its tasks").option("--team <identifier>", "team identifier").action(async (options) => {
|
|
7771
7982
|
await cycleCurrent(contextFor(program2, io2), { team: options.team });
|
|
7772
7983
|
});
|
|
7984
|
+
const release = program2.command("release").description("Releases: what a closed cycle shipped, and its narrative");
|
|
7985
|
+
release.command("list").description("List releases, newest first").option("--team <identifier>", "team identifier").action(async (options) => {
|
|
7986
|
+
await releaseList(contextFor(program2, io2), { team: options.team });
|
|
7987
|
+
});
|
|
7988
|
+
release.command("view").argument("<releaseId>", "release id").description("Show a release with its narrative and task lists").action(async (releaseId) => {
|
|
7989
|
+
await releaseView(contextFor(program2, io2), releaseId);
|
|
7990
|
+
});
|
|
7991
|
+
release.command("context").argument("<releaseId>", "release id").description("Print the release's context bundle as a Markdown prompt").option("--markdown", "render Markdown (the default)").action(async (releaseId, options) => {
|
|
7992
|
+
await releaseContext(contextFor(program2, io2), releaseId, options);
|
|
7993
|
+
});
|
|
7994
|
+
release.command("diff").argument("<releaseId>", "release id").description("Show the change against the previous release").action(async (releaseId) => {
|
|
7995
|
+
await releaseDiff(contextFor(program2, io2), releaseId);
|
|
7996
|
+
});
|
|
7997
|
+
release.command("export").argument("<releaseId>", "release id").description("Print the release as Markdown").option("--out <file>", "write to a file instead of stdout").action(async (releaseId, options) => {
|
|
7998
|
+
await releaseExport(contextFor(program2, io2), releaseId, options);
|
|
7999
|
+
});
|
|
8000
|
+
release.command("narrate").argument("<releaseId>", "release id").description("Attach a Markdown narrative to a release").usage("[options] <releaseId>\n \u2026 | tasq release narrate <releaseId>").option("--body <markdown>", "the narrative itself").option("--file <path>", "read the narrative from a file").action(
|
|
8001
|
+
async (releaseId, options) => {
|
|
8002
|
+
await releaseNarrate(contextFor(program2, io2), releaseId, options);
|
|
8003
|
+
}
|
|
8004
|
+
);
|
|
7773
8005
|
const auth = program2.command("auth").description("Authentication");
|
|
7774
8006
|
auth.command("login").description("Sign in and store a CLI token").option("--email <email>", "email address").action(async (options) => {
|
|
7775
8007
|
await authLogin(
|
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# Example release narrator — NOT part of the Tasq product.
|
|
3
|
+
#
|
|
4
|
+
# Tasq writes the release row itself on every cycle close and then sends one
|
|
5
|
+
# `cycle_closed` event to the team's release narrator, if one is set. This
|
|
6
|
+
# script is the smallest honest example of the harness side of that loop: it
|
|
7
|
+
# reads `tasq events listen` line by line, and for each `cycle_closed` it
|
|
8
|
+
# pulls the release context, writes a narrative, saves it, and acks.
|
|
9
|
+
#
|
|
10
|
+
# The narrative it writes is a PLACEHOLDER assembled from the context itself.
|
|
11
|
+
# This script calls no model and has no opinion about what a release means —
|
|
12
|
+
# that is the part you replace. Set TASQ_NARRATOR_CMD to a command that reads
|
|
13
|
+
# the context on stdin and writes the narrative on stdout, and this runner
|
|
14
|
+
# will use it instead.
|
|
15
|
+
#
|
|
16
|
+
# Usage:
|
|
17
|
+
# TASQ_API_KEY=tq_ag_… \
|
|
18
|
+
# TASQ_WORKSPACE=acme \
|
|
19
|
+
# TASQ_NARRATOR_CMD='claude -p "write a release narrative from this context"' \
|
|
20
|
+
# ./release-narrator.sh [--wait 20]
|
|
21
|
+
#
|
|
22
|
+
# Environment:
|
|
23
|
+
# TASQ_NARRATOR_CMD Optional. Command run per release, with the release's
|
|
24
|
+
# Markdown context on stdin; its stdout becomes the
|
|
25
|
+
# narrative. Unset, the placeholder below is used.
|
|
26
|
+
# TASQ_API_KEY The agent key. TASQ_WORKSPACE and TASQ_API_URL are read
|
|
27
|
+
# by the CLI itself; see `tasq --help`.
|
|
28
|
+
#
|
|
29
|
+
# Only `cycle_closed` is handled here. A `mention` or `thread_message` reaching
|
|
30
|
+
# this key is left UNACKED on purpose: it is a conversation, this runner is not
|
|
31
|
+
# one, and Tasq will offer it again in ten minutes to whatever does handle it.
|
|
32
|
+
# Run `mention-runner.sh` beside this one if the same agent does both.
|
|
33
|
+
#
|
|
34
|
+
# Acking is deliberate: an event whose narrate failed is left unacked and comes
|
|
35
|
+
# back in ten minutes. Saving twice is harmless — the narrative is one field
|
|
36
|
+
# with last write wins, so a retry overwrites rather than duplicating.
|
|
37
|
+
|
|
38
|
+
set -euo pipefail
|
|
39
|
+
|
|
40
|
+
TASQ_BIN="${TASQ_BIN:-tasq}"
|
|
41
|
+
|
|
42
|
+
# jq if it is there, a node one-liner if it is not. Both print the field's
|
|
43
|
+
# value, or an empty line when the field is null or missing.
|
|
44
|
+
if command -v jq > /dev/null 2>&1; then
|
|
45
|
+
field() { printf '%s' "$1" | jq -r --arg f "$2" '.[$f] // empty'; }
|
|
46
|
+
else
|
|
47
|
+
field() {
|
|
48
|
+
printf '%s' "$1" | node -e '
|
|
49
|
+
let raw = ""
|
|
50
|
+
process.stdin.on("data", (chunk) => { raw += chunk })
|
|
51
|
+
process.stdin.on("end", () => {
|
|
52
|
+
const value = JSON.parse(raw)[process.argv[1]]
|
|
53
|
+
process.stdout.write(value == null ? "" : String(value))
|
|
54
|
+
})
|
|
55
|
+
' "$2"
|
|
56
|
+
}
|
|
57
|
+
fi
|
|
58
|
+
|
|
59
|
+
# The placeholder narrative: the context's own counts and shipped list, turned
|
|
60
|
+
# into three lines of prose-shaped text. It exists so the loop can be run end
|
|
61
|
+
# to end without a model attached, and so a reader can see exactly which part
|
|
62
|
+
# of this script is the part that thinks. It is not one.
|
|
63
|
+
placeholder_narrative() {
|
|
64
|
+
local context="$1" summary
|
|
65
|
+
|
|
66
|
+
summary="$(printf '%s' "$context" | grep '^- Shipped ' | head -1)"
|
|
67
|
+
|
|
68
|
+
printf '%s\n' "## Release notes"
|
|
69
|
+
printf '\n'
|
|
70
|
+
printf '%s\n' "${summary:-- No counts in the context.}"
|
|
71
|
+
printf '\n'
|
|
72
|
+
printf '%s\n' "Shipped this cycle:"
|
|
73
|
+
printf '\n'
|
|
74
|
+
# The context's Shipped section, up to the next heading.
|
|
75
|
+
printf '%s' "$context" | awk '
|
|
76
|
+
/^## Shipped$/ { inside = 1; next }
|
|
77
|
+
/^## / { inside = 0 }
|
|
78
|
+
inside && /^- / { print }
|
|
79
|
+
'
|
|
80
|
+
printf '\n'
|
|
81
|
+
printf '%s\n' "_Written by the example narrator, which does not read._"
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
"$TASQ_BIN" events listen "$@" | while IFS= read -r event; do
|
|
85
|
+
[[ -z "$event" ]] && continue
|
|
86
|
+
|
|
87
|
+
TASQ_EVENT_ID="$(field "$event" id)"
|
|
88
|
+
TASQ_EVENT_KIND="$(field "$event" kind)"
|
|
89
|
+
TASQ_EVENT_RELEASE_ID="$(field "$event" releaseId)"
|
|
90
|
+
|
|
91
|
+
if [[ "$TASQ_EVENT_KIND" != "cycle_closed" ]]; then
|
|
92
|
+
echo "→ ${TASQ_EVENT_KIND} (${TASQ_EVENT_ID}); not a release, leaving it unacked" >&2
|
|
93
|
+
|
|
94
|
+
continue
|
|
95
|
+
fi
|
|
96
|
+
|
|
97
|
+
if [[ -z "$TASQ_EVENT_RELEASE_ID" ]]; then
|
|
98
|
+
echo "→ cycle_closed ${TASQ_EVENT_ID} carried no releaseId; acking and skipping" >&2
|
|
99
|
+
"$TASQ_BIN" events ack "$TASQ_EVENT_ID"
|
|
100
|
+
|
|
101
|
+
continue
|
|
102
|
+
fi
|
|
103
|
+
|
|
104
|
+
echo "→ cycle_closed on release ${TASQ_EVENT_RELEASE_ID} (${TASQ_EVENT_ID})" >&2
|
|
105
|
+
|
|
106
|
+
# `set -e` must not kill the loop on a failed read: leave the event unacked
|
|
107
|
+
# and keep listening, the same contract the mention runner keeps.
|
|
108
|
+
if ! context="$("$TASQ_BIN" release context "$TASQ_EVENT_RELEASE_ID")"; then
|
|
109
|
+
echo " could not read the context; leaving ${TASQ_EVENT_ID} unacked" >&2
|
|
110
|
+
|
|
111
|
+
continue
|
|
112
|
+
fi
|
|
113
|
+
|
|
114
|
+
if [[ -n "${TASQ_NARRATOR_CMD:-}" ]]; then
|
|
115
|
+
if ! narrative="$(printf '%s' "$context" | sh -c "$TASQ_NARRATOR_CMD")"; then
|
|
116
|
+
echo " narrator command failed; leaving ${TASQ_EVENT_ID} unacked" >&2
|
|
117
|
+
|
|
118
|
+
continue
|
|
119
|
+
fi
|
|
120
|
+
else
|
|
121
|
+
narrative="$(placeholder_narrative "$context")"
|
|
122
|
+
fi
|
|
123
|
+
|
|
124
|
+
if [[ -z "${narrative//[[:space:]]/}" ]]; then
|
|
125
|
+
echo " the narrative came back empty; leaving ${TASQ_EVENT_ID} unacked" >&2
|
|
126
|
+
|
|
127
|
+
continue
|
|
128
|
+
fi
|
|
129
|
+
|
|
130
|
+
# `--file` rather than `--body`: a narrative is Markdown with newlines in it,
|
|
131
|
+
# and a temporary file keeps it off the argument list and out of `ps`.
|
|
132
|
+
body_file="$(mktemp -t tasq-narrative.XXXXXX)"
|
|
133
|
+
printf '%s' "$narrative" > "$body_file"
|
|
134
|
+
|
|
135
|
+
if "$TASQ_BIN" release narrate "$TASQ_EVENT_RELEASE_ID" --file "$body_file"; then
|
|
136
|
+
"$TASQ_BIN" events ack "$TASQ_EVENT_ID"
|
|
137
|
+
else
|
|
138
|
+
echo " narrate failed; leaving ${TASQ_EVENT_ID} unacked for redelivery" >&2
|
|
139
|
+
fi
|
|
140
|
+
|
|
141
|
+
rm -f "$body_file"
|
|
142
|
+
done
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@pxlabz/tasq-cli",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.6",
|
|
4
4
|
"description": "Command-line client for Tasq, for humans and agents alike",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"tasq",
|
|
@@ -49,7 +49,7 @@
|
|
|
49
49
|
"commander": "^14.0.0"
|
|
50
50
|
},
|
|
51
51
|
"devDependencies": {
|
|
52
|
-
"@pxlabz/tasq-sdk": "0.1.
|
|
52
|
+
"@pxlabz/tasq-sdk": "0.1.4",
|
|
53
53
|
"@types/bun": "^1.3.12",
|
|
54
54
|
"tsup": "^8.5.0",
|
|
55
55
|
"typescript": "^5.7.2"
|