@aiaiai-pt/manda-cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,110 @@
-# Temporary Holding Version
+# @aiaiai-pt/manda-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+CLI for the [Manda](https://manda.aiaiai.pt) feedback service. One command per staff action, JSON on stdout, no runtime dependencies.
+
+## Install
+
+```sh
+npm i -g @aiaiai-pt/manda-cli
+```
+
+Requires Node.js 22 or later.
+
+## Auth
+
+Set environment variables (preferred for agents):
+
+```sh
+export MANDA_TOKEN=mn_agent_...
+export MANDA_URL=https://manda.aiaiai.pt  # optional, this is the default
+```
+
+Or save to a config file:
+
+```sh
+manda auth login --url https://manda.aiaiai.pt --token mn_agent_...
+manda auth status
+```
+
+Credentials are saved to `${XDG_CONFIG_HOME:-~/.config}/manda/config.json` with mode 0600. Environment variables take precedence over the config file; `--url` and `--token` flags override both.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `manda whoami` | Show authenticated identity |
+| `manda projects` | List projects |
+| `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 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 |
+| `manda report ack <id>` | Acknowledge a report |
+| `manda report resolve <id> --resolution <text>` | Resolve a report |
+| `manda report reopen <id>` | Reopen a report |
+| `manda report link <id> (--work-url <url> \| --none)` | Link or clear external work |
+| `manda report comment <id> --body <text> [--audience internal\|customer] [--outcome open\|resolved] [--request-id <uuid>]` | Add a comment, optionally closing or reopening |
+| `manda topic list [--project <id>]` | List topics |
+| `manda topic show <id>` | Show a topic |
+| `manda topic create --project <id> --title <text> [--description <text>]` | Create a topic |
+| `manda topic transition <id> plan\|start\|complete\|decline\|reconsider\|reopen [--body <text>]` | Transition a topic (decline needs a reason) |
+| `manda topic note <id> --body <text>` | Add a note |
+| `manda topic edit <id> --title <text> --description <text>` | Edit a topic |
+| `manda topic link-report <id> --report <id>` | Link a report to a topic |
+| `manda topic unlink-report <id> --report <id>` | Unlink a report |
+| `manda topic link-work <id> --tracker <t> --issue <i> --issue-url <url>` | Link external work |
+| `manda topic unlink-work <id> --tracker <t> --issue <i>` | Unlink external work |
+| `manda topic publish <id> [--public-title <text>] [--public-summary <text>]` | Publish a topic to the portal |
+| `manda topic unpublish <id>` | Unpublish a topic |
+| `manda topic edit-public <id> --public-title <text> --public-summary <text>` | Edit the public wording |
+| `manda topic reorder --project <id> <topicId> [...]` | Reorder topics |
+| `manda topic announce <id> --body <text>` | Add a public progress announcement |
+| `manda topic unannounce <id> --announcement <id>` | Remove an announcement |
+
+### Inbox filters
+
+`--project <id>`, `--state new|acknowledged|resolved`, `--assignee me|unassigned|<email>`, `--q <text>`, `--page N`, `--limit N`
+
+## Output
+
+- **JSON** on stdout when stdout is not a TTY or when `--json` is given.
+- **Human table** on a TTY without `--json`.
+- **Errors** as JSON on stderr: `{ "error": { "status", "message", "exit" } }`.
+- On a 409 conflict, the error includes a `"current"` field with the freshly fetched resource.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Usage error (missing or unknown flag, unknown command, stdin used for two flags) |
+| 2 | Auth failure (401, 403) or no credentials configured |
+| 3 | Conflict (409, stale revision) |
+| 4 | Not found (404) |
+| 5 | Server or network error (400, 415, 429, 5xx) |
+
+## Revision rule
+
+Every write reads the resource first to learn the current `revision` unless `--revision N` is given. On 409 the CLI does not retry: it refetches, prints the current state, and exits 3.
+
+`report comment` always sends a `request_id` (random UUID, or `--request-id` for idempotent retries).
+
+Text flags (`--message`, `--body`, `--resolution`, `--title`, `--description`, `--public-title`, `--public-summary`) accept `-` to read from stdin; one flag per call.
+
+## Agent loop example
+
+```sh
+export MANDA_TOKEN=mn_agent_...
+
+# Triage new reports
+for id in $(manda inbox --state new --json | jq -r '.submissions[].id'); do
+  manda report ack "$id"
+  manda report comment "$id" --body "Triaged by automation." --audience internal
+done
+
+# Create a topic and link a report
+topic=$(manda topic create --project proj-1 --title "Widget focus trap" --json | jq -r .id)
+manda topic link-report "$topic" --report "$id"
+manda topic transition "$topic" plan
+```

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,348 @@
+#!/usr/bin/env node
+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";
+const USAGE = `Usage: manda <command> [options]
+
+Commands:
+  whoami                         Show authenticated identity
+  projects                       List projects
+  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
+  report show <id>               Show a report
+  report capture                 Create a new report
+  report assign <id>             Assign a report
+  report ack <id>                Acknowledge a report
+  report resolve <id>            Resolve a report
+  report reopen <id>             Reopen a report
+  report link <id>               Link external work to a report (--work-url)
+  report comment <id>            Add a comment to a report
+  topic list                     List topics
+  topic show <id>                Show a topic
+  topic create                   Create a topic
+  topic transition <id> <event>  Transition a topic
+  topic note <id>                Add a note to a topic
+  topic edit <id>                Edit a topic
+  topic link-report <id>         Link a report to a topic
+  topic unlink-report <id>       Unlink a report from a topic
+  topic link-work <id>           Link external work to a topic (--issue-url)
+  topic unlink-work <id>         Unlink external work from a topic
+  topic publish <id>             Publish a topic
+  topic unpublish <id>           Unpublish a topic
+  topic edit-public <id>         Edit a topic's public view
+  topic reorder                  Reorder topics
+  topic announce <id>            Add an announcement to a topic
+  topic unannounce <id>          Remove an announcement (--announcement <id>)
+  auth login                     Save credentials
+  auth status                    Show credential source and verify
+
+Global options:
+  --url <url>        Server URL (overrides env/config)
+  --token <token>    Agent token (overrides env/config)
+  --json             Force JSON output
+  --help             Show help
+`;
+function usageError(message) {
+    printError(0, message, 1);
+    process.stderr.write(USAGE);
+    process.exit(1);
+}
+function showHelp() {
+    process.stdout.write(USAGE);
+    process.exit(0);
+}
+const parseOptions = {
+    options: {
+        url: { type: "string" },
+        token: { type: "string" },
+        json: { type: "boolean", default: false },
+        help: { type: "boolean", default: false },
+        // report flags
+        project: { type: "string" },
+        type: { type: "string" },
+        message: { type: "string" },
+        name: { type: "string" },
+        email: { type: "string" },
+        "source-label": { type: "string" },
+        to: { type: "string" },
+        revision: { type: "string" },
+        resolution: { type: "string" },
+        none: { type: "boolean", default: false },
+        body: { type: "string" },
+        audience: { type: "string" },
+        outcome: { type: "string" },
+        "request-id": { type: "string" },
+        // inbox flags
+        state: { type: "string" },
+        assignee: { type: "string" },
+        q: { type: "string" },
+        page: { type: "string" },
+        limit: { type: "string" },
+        // topic flags
+        title: { type: "string" },
+        description: { type: "string" },
+        report: { type: "string" },
+        tracker: { type: "string" },
+        issue: { type: "string" },
+        "issue-url": { type: "string" },
+        "work-url": { type: "string" },
+        "public-title": { type: "string" },
+        "public-summary": { type: "string" },
+        announcement: { type: "string" },
+    },
+    // Strict: an unknown or misspelled flag is a usage error, never silently ignored.
+    strict: true,
+    allowPositionals: true,
+};
+function parse() {
+    try {
+        return parseArgs(parseOptions);
+    }
+    catch (err) {
+        usageError(err instanceof Error ? err.message : String(err));
+    }
+}
+const { values: globalFlags, positionals } = parse();
+// --help anywhere prints usage, including `manda report --help`.
+if (globalFlags.help)
+    showHelp();
+const command = positionals[0];
+const subcommand = positionals[1];
+if (!command) {
+    usageError("No command provided");
+}
+// instructions needs neither a server nor credentials
+if (command === "instructions") {
+    instructions();
+    process.exit(0);
+}
+// Auth commands don't need a resolved config
+if (command === "auth") {
+    if (subcommand === "login") {
+        const url = globalFlags.url ? String(globalFlags.url) : undefined;
+        const token = globalFlags.token ? String(globalFlags.token) : undefined;
+        const envUrl = process.env["MANDA_URL"];
+        const envToken = process.env["MANDA_TOKEN"];
+        const finalUrl = url || envUrl || "https://manda.aiaiai.pt";
+        const finalToken = token || envToken;
+        if (!finalToken) {
+            usageError("--token is required for auth login (or set MANDA_TOKEN)");
+        }
+        saveConfigFile(finalUrl, finalToken);
+        process.stdout.write(`Credentials saved for ${finalUrl}\n`);
+        process.exit(0);
+    }
+    if (subcommand === "status") {
+        const config = resolveConfig({
+            url: globalFlags.url,
+            token: globalFlags.token,
+        });
+        if (!config) {
+            printError(0, "No credentials configured. Run: manda auth login --token <token>", 2);
+            process.exit(2);
+        }
+        if (isJsonMode(globalFlags)) {
+            const meRes = await api(config, "/api/agent/v1/me");
+            if (!meRes.ok) {
+                const exit = exitCodeForStatus(meRes.status);
+                printError(meRes.status, meRes.message, exit);
+                process.exit(exit);
+            }
+            printJson({ source: config.source, url: config.url, ...meRes.data });
+        }
+        else {
+            printKeyValue([
+                ["source", config.source],
+                ["url", config.url],
+            ]);
+            const meRes = await api(config, "/api/agent/v1/me");
+            if (!meRes.ok) {
+                const exit = exitCodeForStatus(meRes.status);
+                printError(meRes.status, meRes.message, exit);
+                process.exit(exit);
+            }
+            const d = meRes.data;
+            printKeyValue([
+                ["email", d.email],
+                ["domain", d.domain],
+                ["agent", d.agent.name],
+            ]);
+        }
+        process.exit(0);
+    }
+    usageError(`Unknown auth command: ${subcommand}`);
+}
+// All other commands need auth
+const config = resolveConfig({
+    url: globalFlags.url,
+    token: globalFlags.token,
+});
+if (!config) {
+    printError(0, "No credentials configured. Set MANDA_TOKEN or run: manda auth login --token <token>", 2);
+    process.exit(2);
+}
+const flags = globalFlags;
+try {
+    switch (command) {
+        case "whoami":
+            await whoami(config, flags);
+            break;
+        case "projects":
+            await projects(config, flags);
+            break;
+        case "inbox":
+            await inbox(config, flags);
+            break;
+        case "next":
+            await next(config, flags);
+            break;
+        case "report": {
+            const reportId = positionals[2];
+            switch (subcommand) {
+                case "show":
+                    if (!reportId)
+                        usageError("report show requires an ID");
+                    await reportShow(config, reportId, flags);
+                    break;
+                case "capture":
+                    await reportCapture(config, flags);
+                    break;
+                case "assign":
+                    if (!reportId)
+                        usageError("report assign requires an ID");
+                    await reportAssign(config, reportId, flags);
+                    break;
+                case "ack":
+                    if (!reportId)
+                        usageError("report ack requires an ID");
+                    await reportAck(config, reportId, flags);
+                    break;
+                case "resolve":
+                    if (!reportId)
+                        usageError("report resolve requires an ID");
+                    await reportResolve(config, reportId, flags);
+                    break;
+                case "reopen":
+                    if (!reportId)
+                        usageError("report reopen requires an ID");
+                    await reportReopen(config, reportId, flags);
+                    break;
+                case "link":
+                    if (!reportId)
+                        usageError("report link requires an ID");
+                    await reportLink(config, reportId, flags);
+                    break;
+                case "comment":
+                    if (!reportId)
+                        usageError("report comment requires an ID");
+                    await reportComment(config, reportId, flags);
+                    break;
+                default:
+                    usageError(subcommand
+                        ? `Unknown report command: ${subcommand}`
+                        : "report requires a subcommand");
+            }
+            break;
+        }
+        case "topic": {
+            const topicId = positionals[2];
+            switch (subcommand) {
+                case "list":
+                    await topicList(config, flags);
+                    break;
+                case "show":
+                    if (!topicId)
+                        usageError("topic show requires an ID");
+                    await topicShow(config, topicId, flags);
+                    break;
+                case "create":
+                    await topicCreate(config, flags);
+                    break;
+                case "transition": {
+                    if (!topicId)
+                        usageError("topic transition requires an ID");
+                    const event = positionals[3];
+                    if (!event)
+                        usageError("topic transition requires an event (plan|start|complete|decline|reconsider|reopen)");
+                    await topicTransition(config, topicId, event, flags);
+                    break;
+                }
+                case "note":
+                    if (!topicId)
+                        usageError("topic note requires an ID");
+                    await topicNote(config, topicId, flags);
+                    break;
+                case "edit":
+                    if (!topicId)
+                        usageError("topic edit requires an ID");
+                    await topicEdit(config, topicId, flags);
+                    break;
+                case "link-report":
+                    if (!topicId)
+                        usageError("topic link-report requires an ID");
+                    await topicLinkReport(config, topicId, flags);
+                    break;
+                case "unlink-report":
+                    if (!topicId)
+                        usageError("topic unlink-report requires an ID");
+                    await topicUnlinkReport(config, topicId, flags);
+                    break;
+                case "link-work":
+                    if (!topicId)
+                        usageError("topic link-work requires an ID");
+                    await topicLinkWork(config, topicId, flags);
+                    break;
+                case "unlink-work":
+                    if (!topicId)
+                        usageError("topic unlink-work requires an ID");
+                    await topicUnlinkWork(config, topicId, flags);
+                    break;
+                case "publish":
+                    if (!topicId)
+                        usageError("topic publish requires an ID");
+                    await topicPublish(config, topicId, flags);
+                    break;
+                case "unpublish":
+                    if (!topicId)
+                        usageError("topic unpublish requires an ID");
+                    await topicUnpublish(config, topicId, flags);
+                    break;
+                case "edit-public":
+                    if (!topicId)
+                        usageError("topic edit-public requires an ID");
+                    await topicEditPublic(config, topicId, flags);
+                    break;
+                case "reorder":
+                    await topicReorder(config, positionals.slice(2), flags);
+                    break;
+                case "announce":
+                    if (!topicId)
+                        usageError("topic announce requires an ID");
+                    await topicAnnounce(config, topicId, flags);
+                    break;
+                case "unannounce":
+                    if (!topicId)
+                        usageError("topic unannounce requires an ID");
+                    await topicUnannounce(config, topicId, flags);
+                    break;
+                default:
+                    usageError(subcommand
+                        ? `Unknown topic command: ${subcommand}`
+                        : "topic requires a subcommand");
+            }
+            break;
+        }
+        case "--help":
+        case "help":
+            showHelp();
+        default:
+            usageError(`Unknown command: ${command}`);
+    }
+}
+catch (err) {
+    printError(0, err instanceof Error ? err.message : String(err), 5);
+    process.exit(5);
+}

package/dist/client.d.ts

@@ -0,0 +1,23 @@
+import type { Config } from "./config.js";
+export interface ApiError {
+    status: number;
+    message: string;
+}
+export interface ApiResult<T = unknown> {
+    ok: true;
+    status: number;
+    data: T;
+}
+export interface ApiFailure {
+    ok: false;
+    status: number;
+    message: string;
+    data?: unknown;
+}
+export type ApiResponse<T = unknown> = ApiResult<T> | ApiFailure;
+export declare function api<T = unknown>(config: Config, path: string, options?: {
+    method?: string;
+    body?: unknown;
+    query?: Record<string, string | undefined>;
+}): Promise<ApiResponse<T>>;
+export declare function exitCodeForStatus(status: number): number;

package/dist/client.js

@@ -0,0 +1,62 @@
+export async function api(config, path, options = {}) {
+    const { method = "GET", body, query } = options;
+    const url = new URL(path, config.url);
+    if (query) {
+        for (const [k, v] of Object.entries(query)) {
+            if (v !== undefined && v !== "")
+                url.searchParams.set(k, v);
+        }
+    }
+    const headers = {
+        authorization: `Bearer ${config.token}`,
+        accept: "application/json",
+    };
+    if (body !== undefined) {
+        headers["content-type"] = "application/json";
+    }
+    let res;
+    try {
+        res = await fetch(url, {
+            method,
+            headers,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+    }
+    catch (err) {
+        return {
+            ok: false,
+            status: 0,
+            message: err instanceof Error ? err.message : "Network error",
+        };
+    }
+    const text = await res.text();
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        data = text;
+    }
+    if (res.ok) {
+        return { ok: true, status: res.status, data: data };
+    }
+    const message = typeof data === "object" &&
+        data !== null &&
+        "message" in data &&
+        typeof data.message === "string"
+        ? data.message
+        : typeof data === "string"
+            ? data
+            : `HTTP ${res.status}`;
+    return { ok: false, status: res.status, message, data };
+}
+export function exitCodeForStatus(status) {
+    if (status === 401 || status === 403)
+        return 2;
+    if (status === 409)
+        return 3;
+    if (status === 404)
+        return 4;
+    // 400, 415, 429, 5xx, network (0)
+    return 5;
+}

package/dist/commands.d.ts

@@ -0,0 +1,34 @@
+import type { Config } from "./config.js";
+type Flags = Record<string, string | boolean | undefined>;
+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>;
+/** 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 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>;
+export declare function reportAssign(config: Config, id: string, flags: Flags): Promise<void>;
+export declare function reportAck(config: Config, id: string, flags: Flags): Promise<void>;
+export declare function reportResolve(config: Config, id: string, flags: Flags): Promise<void>;
+export declare function reportReopen(config: Config, id: string, flags: Flags): Promise<void>;
+export declare function reportLink(config: Config, id: string, flags: Flags): Promise<void>;
+export declare function reportComment(config: Config, id: string, flags: Flags): Promise<void>;
+export declare function topicList(config: Config, flags: Flags): Promise<void>;
+export declare function topicShow(config: Config, id: string, flags: Flags): Promise<void>;
+export declare function topicCreate(config: Config, flags: Flags): Promise<void>;
+export declare function topicTransition(config: Config, id: string, event: string, flags: Flags): Promise<void>;
+export declare function topicNote(config: Config, id: string, flags: Flags): Promise<void>;
+export declare function topicEdit(config: Config, id: string, flags: Flags): Promise<void>;
+export declare function topicLinkReport(config: Config, id: string, flags: Flags): Promise<void>;
+export declare function topicUnlinkReport(config: Config, id: string, flags: Flags): Promise<void>;
+export declare function topicLinkWork(config: Config, id: string, flags: Flags): Promise<void>;
+export declare function topicUnlinkWork(config: Config, id: string, flags: Flags): Promise<void>;
+export declare function topicPublish(config: Config, id: string, flags: Flags): Promise<void>;
+export declare function topicUnpublish(config: Config, id: string, flags: Flags): Promise<void>;
+export declare function topicEditPublic(config: Config, id: string, flags: Flags): Promise<void>;
+export declare function topicReorder(config: Config, topicIds: string[], flags: Flags): Promise<void>;
+export declare function topicAnnounce(config: Config, id: string, flags: Flags): Promise<void>;
+export declare function topicUnannounce(config: Config, id: string, flags: Flags): Promise<void>;
+export {};