@aiaiai-pt/manda-cli 0.1.1 → 0.2.0

package/README.md

@@ -37,6 +37,7 @@ Credentials are saved to `${XDG_CONFIG_HOME:-~/.config}/manda/config.json` with
 | `manda inbox [filters]` | List submissions |
 | `manda next [--project <id>]` | What to work on next: open reports you own or nobody owns, owned first, new first, then linked-topic roadmap order |
 | `manda instructions` | Print a block for CLAUDE.md or AGENTS.md describing the loop and commit trailers |
+| `manda watch [--since <cursor>] [--project <id>] [--interval <s>] [--once]` | Print changes as they land, one JSON object per line when piped: reports, report updates (customer replies carry `author_kind: customer`), topic updates, announcements. Starts from now without `--since`; `--once` polls one time and ends with a `cursor` line to resume from. The cursor is opaque; a bare `YYYY-MM-DD HH:MM:SS` (UTC) is also accepted as a starting point |
 | `manda report show <id>` | Show a report |
 | `manda report capture --project <id> --type bug\|feature\|other --message <text> [--name] [--email] [--source-label]` | Create a report |
 | `manda report assign <id> --to <email\|me\|none>` | Assign a report |
@@ -108,3 +109,11 @@ topic=$(manda topic create --project proj-1 --title "Widget focus trap" --json |
 manda topic link-report "$topic" --report "$id"
 manda topic transition "$topic" plan
 ```
+
+# Wake on changes (one JSON line per event; a customer reply on a resolved report reopens it)
+manda watch --since "$cursor" | while read -r event; do
+  if [ "$(jq -r .author_kind <<<"$event")" = customer ]; then
+    manda report reopen "$(jq -r .report_id <<<"$event")"
+  fi
+done
+```

package/dist/bin.js

@@ -3,7 +3,7 @@ import { parseArgs } from "node:util";
 import { resolveConfig, saveConfigFile } from "./config.js";
 import { api, exitCodeForStatus } from "./client.js";
 import { printError, printJson, printKeyValue, isJsonMode } from "./output.js";
-import { whoami, projects, inbox, next, instructions, reportShow, reportCapture, reportAssign, reportAck, reportResolve, reportReopen, reportLink, reportComment, topicList, topicShow, topicCreate, topicTransition, topicNote, topicEdit, topicLinkReport, topicUnlinkReport, topicLinkWork, topicUnlinkWork, topicPublish, topicUnpublish, topicEditPublic, topicReorder, topicAnnounce, topicUnannounce, } from "./commands.js";
+import { whoami, projects, inbox, next, watch, instructions, reportShow, reportCapture, reportAssign, reportAck, reportResolve, reportReopen, reportLink, reportComment, topicList, topicShow, topicCreate, topicTransition, topicNote, topicEdit, topicLinkReport, topicUnlinkReport, topicLinkWork, topicUnlinkWork, topicPublish, topicUnpublish, topicEditPublic, topicReorder, topicAnnounce, topicUnannounce, } from "./commands.js";
 const USAGE = `Usage: manda <command> [options]
 
 Commands:
@@ -12,6 +12,7 @@ Commands:
   inbox                          List submissions (inbox)
   next                           What to work on next, in priority order (--project)
   instructions                   Print a CLAUDE.md / AGENTS.md block for this loop
+  watch                          Print changes as they land (--since, --project, --interval, --once)
   report show <id>               Show a report
   report capture                 Create a new report
   report assign <id>             Assign a report
@@ -92,6 +93,10 @@ const parseOptions = {
         "public-title": { type: "string" },
         "public-summary": { type: "string" },
         announcement: { type: "string" },
+        // watch flags
+        since: { type: "string" },
+        interval: { type: "string" },
+        once: { type: "boolean", default: false },
     },
     // Strict: an unknown or misspelled flag is a usage error, never silently ignored.
     strict: true,
@@ -199,6 +204,9 @@ try {
         case "next":
             await next(config, flags);
             break;
+        case "watch":
+            await watch(config, flags);
+            break;
         case "report": {
             const reportId = positionals[2];
             switch (subcommand) {

package/dist/commands.d.ts

@@ -4,8 +4,31 @@ export declare function whoami(config: Config, flags: Flags): Promise<void>;
 export declare function projects(config: Config, flags: Flags): Promise<void>;
 export declare function inbox(config: Config, flags: Flags): Promise<void>;
 export declare function next(config: Config, flags: Flags): Promise<void>;
+export interface WatchEvent {
+    id: string;
+    at: string;
+    type: string;
+    kind: string;
+    project_id: string;
+    report_id: string | null;
+    topic_id: string | null;
+    author_email: string | null;
+    author_kind: string | null;
+    author_agent: string | null;
+    body: string;
+}
+/** Keeps the events not yet seen, in order, and remembers them. The feed is at-least-once
+ * at the cursor boundary, so the same id can arrive on consecutive polls. */
+export declare function unseenEvents(seen: Set<string>, events: WatchEvent[]): WatchEvent[];
+export declare function formatEvent(e: WatchEvent): string;
+/** `manda watch`: print each change as it lands, one JSON object per line when piped, so a
+ * harness can wake on stdout. Without --since it starts from now. --once polls one time and
+ * ends with a `cursor` line to resume from. The cursor is opaque to the client; a bare
+ * `YYYY-MM-DD HH:MM:SS` is also accepted as a starting point. Dedupe by id covers the
+ * inclusive boundary of that bare form. */
+export declare function watch(config: Config, flags: Flags): Promise<void>;
 /** A block for CLAUDE.md or AGENTS.md: the loop a harness runs with manda as its coordination layer. */
-export declare const INSTRUCTIONS = "## Manda: customer feedback and work coordination\n\nManda is the ledger of what customers reported and what they have been told. Use the `manda`\nCLI (`npm i -g @aiaiai-pt/manda-cli`, `MANDA_TOKEN` set) as the coordination layer while\nworking in this codebase, alone or with a person. Every call prints JSON when piped; exit codes:\n0 ok, 1 usage, 2 auth, 3 conflict (reload and decide again), 4 not found, 5 other.\n\nThe loop:\n\n1. `manda next --json` lists open reports you own or nobody owns, in priority order. Take the first.\n2. `manda report show <id> --json` reads the report and its timeline. `manda report assign <id> --to me` takes it\n   (owned reports rank first in `next`; an unowned one you are working on will sink below fresh reports), then\n   `manda report ack <id>` starts review.\n3. Group it: `manda topic list --json` to find the topic it belongs to, then\n   `manda topic link-report <topic> --report <id>`; or `manda topic create --project <project> --title \"<customer intent>\"`\n   and `manda topic transition <topic> plan` then `start` when you begin.\n4. Do the work in the repository. Put `Manda-Report: <id>` and `Manda-Topic: <topic>` as commit trailers\n   and `manda topic link-work <topic> --tracker github --issue <pr number> --issue-url <pr url>` once a PR exists.\n5. Tell the customer only when it is true: `manda report comment <id> --audience customer --outcome resolved --body \"<what changed, in their words>\"`.\n   Internal notes use `--audience internal`. Never resolve without a customer-facing explanation.\n6. `manda topic transition <topic> complete` when the change is available to customers; `manda topic announce <topic> --body \"<progress>\"` for public progress.\n\nRules: read before you write (every write checks the revision); do not reprioritise by editing reports, reorder topics\n(`manda topic reorder`) with the person who owns the roadmap; a 3 exit means someone else changed it, re-read and decide again.\n";
+export declare const INSTRUCTIONS = "## Manda: customer feedback and work coordination\n\nManda is the ledger of what customers reported and what they have been told. Use the `manda`\nCLI (`npm i -g @aiaiai-pt/manda-cli`, `MANDA_TOKEN` set) as the coordination layer while\nworking in this codebase, alone or with a person. Every call prints JSON when piped; exit codes:\n0 ok, 1 usage, 2 auth, 3 conflict (reload and decide again), 4 not found, 5 other.\n\nThe loop:\n\n1. `manda next --json` lists open reports you own or nobody owns, in priority order. Take the first.\n2. `manda report show <id> --json` reads the report and its timeline. `manda report assign <id> --to me` takes it\n   (owned reports rank first in `next`; an unowned one you are working on will sink below fresh reports), then\n   `manda report ack <id>` starts review.\n3. Group it: `manda topic list --json` to find the topic it belongs to, then\n   `manda topic link-report <topic> --report <id>`; or `manda topic create --project <project> --title \"<customer intent>\"`\n   and `manda topic transition <topic> plan` then `start` when you begin.\n4. Do the work in the repository. Put `Manda-Report: <id>` and `Manda-Topic: <topic>` as commit trailers\n   and `manda topic link-work <topic> --tracker github --issue <pr number> --issue-url <pr url>` once a PR exists.\n5. Tell the customer only when it is true, and \"true\" means you exercised their path, not the artefact:\n   load the page or call the entry point they use (the hosted script, the endpoint, the screen) on the\n   deployed version and watch it work. A green suite, a merged PR or a file read back are not that.\n   Then `manda report comment <id> --audience customer --outcome resolved --body \"<what changed, in their words>\"`.\n   Internal notes use `--audience internal`. Never resolve without a customer-facing explanation.\n6. `manda topic transition <topic> complete` when the change is available to customers; `manda topic announce <topic> --body \"<progress>\"` for public progress.\n7. Between tasks, `manda watch` prints one JSON line per change as it lands: new reports, customer replies\n   (`type` report_update with `author_kind` customer), topic changes. `manda watch --once` polls once and ends with\n   a `cursor` line; resume later with `manda watch --since <cursor>`. A customer reply on a report you resolved\n   means it is not done: `manda report reopen <id>` and go back to step 2.\n\nRules: read before you write (every write checks the revision); do not reprioritise by editing reports, reorder topics\n(`manda topic reorder`) with the person who owns the roadmap; a 3 exit means someone else changed it, re-read and decide again.\n";
 export declare function instructions(): void;
 export declare function reportShow(config: Config, id: string, flags: Flags): Promise<void>;
 export declare function reportCapture(config: Config, flags: Flags): Promise<void>;

package/dist/commands.js

@@ -163,6 +163,60 @@ export async function next(config, flags) {
         ]);
     }
 }
+/** Keeps the events not yet seen, in order, and remembers them. The feed is at-least-once
+ * at the cursor boundary, so the same id can arrive on consecutive polls. */
+export function unseenEvents(seen, events) {
+    const fresh = [];
+    for (const e of events) {
+        if (seen.has(e.id))
+            continue;
+        seen.add(e.id);
+        fresh.push(e);
+    }
+    return fresh;
+}
+export function formatEvent(e) {
+    const subject = e.report_id ? `report ${e.report_id}` : `topic ${e.topic_id}`;
+    const who = e.author_agent ? `${e.author_agent} (agent for ${e.author_email})` : e.author_email ?? "";
+    const by = e.author_kind === "customer" ? `customer ${who}` : who;
+    const body = e.body.replace(/\s+/g, " ");
+    return `${e.at}  ${e.type}/${e.kind}  ${subject}  ${by}: ${body.length > 120 ? body.slice(0, 117) + "..." : body}`;
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** `manda watch`: print each change as it lands, one JSON object per line when piped, so a
+ * harness can wake on stdout. Without --since it starts from now. --once polls one time and
+ * ends with a `cursor` line to resume from. The cursor is opaque to the client; a bare
+ * `YYYY-MM-DD HH:MM:SS` is also accepted as a starting point. Dedupe by id covers the
+ * inclusive boundary of that bare form. */
+export async function watch(config, flags) {
+    const once = flags["once"] === true;
+    const intervalRaw = flags["interval"] === undefined ? "15" : String(flags["interval"]);
+    const interval = Number(intervalRaw);
+    if (!Number.isFinite(interval) || interval < 1)
+        die(400, "--interval must be a number of seconds, at least 1");
+    let since = flags["since"] === undefined ? undefined : String(flags["since"]);
+    const seen = new Set();
+    const jsonMode = isJsonMode(flags);
+    for (;;) {
+        const query = { since, project_id: flags["project"] ? String(flags["project"]) : undefined };
+        if (flags["limit"])
+            query["limit"] = String(flags["limit"]);
+        const res = await api(config, "/api/agent/v1/changes", { query });
+        if (!res.ok)
+            return handleError(res);
+        for (const e of unseenEvents(seen, res.data.events)) {
+            process.stdout.write(jsonMode ? JSON.stringify(e) + "\n" : formatEvent(e) + "\n");
+        }
+        since = res.data.cursor;
+        if (seen.size > 10_000)
+            seen.clear();
+        if (once) {
+            process.stdout.write(jsonMode ? JSON.stringify({ type: "cursor", cursor: since }) + "\n" : `cursor ${since}\n`);
+            return;
+        }
+        await sleep(interval * 1000);
+    }
+}
 // --- instructions ---
 /** A block for CLAUDE.md or AGENTS.md: the loop a harness runs with manda as its coordination layer. */
 export const INSTRUCTIONS = `## Manda: customer feedback and work coordination
@@ -183,9 +237,16 @@ The loop:
    and \`manda topic transition <topic> plan\` then \`start\` when you begin.
 4. Do the work in the repository. Put \`Manda-Report: <id>\` and \`Manda-Topic: <topic>\` as commit trailers
    and \`manda topic link-work <topic> --tracker github --issue <pr number> --issue-url <pr url>\` once a PR exists.
-5. Tell the customer only when it is true: \`manda report comment <id> --audience customer --outcome resolved --body "<what changed, in their words>"\`.
+5. Tell the customer only when it is true, and "true" means you exercised their path, not the artefact:
+   load the page or call the entry point they use (the hosted script, the endpoint, the screen) on the
+   deployed version and watch it work. A green suite, a merged PR or a file read back are not that.
+   Then \`manda report comment <id> --audience customer --outcome resolved --body "<what changed, in their words>"\`.
    Internal notes use \`--audience internal\`. Never resolve without a customer-facing explanation.
 6. \`manda topic transition <topic> complete\` when the change is available to customers; \`manda topic announce <topic> --body "<progress>"\` for public progress.
+7. Between tasks, \`manda watch\` prints one JSON line per change as it lands: new reports, customer replies
+   (\`type\` report_update with \`author_kind\` customer), topic changes. \`manda watch --once\` polls once and ends with
+   a \`cursor\` line; resume later with \`manda watch --since <cursor>\`. A customer reply on a report you resolved
+   means it is not done: \`manda report reopen <id>\` and go back to step 2.
 
 Rules: read before you write (every write checks the revision); do not reprioritise by editing reports, reorder topics
 (\`manda topic reorder\`) with the person who owns the roadmap; a 3 exit means someone else changed it, re-read and decide again.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiaiai-pt/manda-cli",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "CLI for the Manda feedback service",
   "license": "MIT",
   "type": "module",