@mnemom/mnemom 0.9.1 → 0.11.0

package/dist/commands/advisories.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `mnemom advisories ...` commands — Piece 6 of T1-3.1 (ADR-040, ADR-045, ADR-047).
+ *
+ *   mnemom advisories list --agent <agent_id> [--source <source>] [--limit <n>] [--since <ISO>] [--json]
+ *   mnemom advisories list --team  <team_id>  [--source <source>] [--limit <n>] [--since <ISO>] [--json]
+ *   mnemom advisories show <advisory_id> [--agent <agent_id> | --team <team_id>] [--json]
+ *
+ * Surfaces the customer-facing read paths over `pending_advisories` rows
+ * with `source LIKE 'sideband.%'`. Detector firings — coherence,
+ * fault-line, fleet, drift — land here as the cross-turn carryover the
+ * gateway injects on the agent's next request.
+ *
+ * Either --agent or --team is required. Source filter accepts the closed
+ * enum values from ADR-047 §6 (sideband.coherence, sideband.fault_line,
+ * sideband.fleet, sideband.drift, manual.admin) — unknown values are
+ * accepted and applied verbatim (forward-compat for ADR-047 amendments).
+ */
+interface ListOpts {
+    agent?: string;
+    team?: string;
+    source?: string;
+    limit?: string;
+    since?: string;
+    json?: boolean;
+}
+export declare function advisoriesListCommand(opts: ListOpts): Promise<void>;
+export declare function advisoriesShowCommand(advisoryId: string, opts: {
+    agent?: string;
+    team?: string;
+    json?: boolean;
+}): Promise<void>;
+export {};

package/dist/commands/advisories.js

@@ -0,0 +1,158 @@
+/**
+ * `mnemom advisories ...` commands — Piece 6 of T1-3.1 (ADR-040, ADR-045, ADR-047).
+ *
+ *   mnemom advisories list --agent <agent_id> [--source <source>] [--limit <n>] [--since <ISO>] [--json]
+ *   mnemom advisories list --team  <team_id>  [--source <source>] [--limit <n>] [--since <ISO>] [--json]
+ *   mnemom advisories show <advisory_id> [--agent <agent_id> | --team <team_id>] [--json]
+ *
+ * Surfaces the customer-facing read paths over `pending_advisories` rows
+ * with `source LIKE 'sideband.%'`. Detector firings — coherence,
+ * fault-line, fleet, drift — land here as the cross-turn carryover the
+ * gateway injects on the agent's next request.
+ *
+ * Either --agent or --team is required. Source filter accepts the closed
+ * enum values from ADR-047 §6 (sideband.coherence, sideband.fault_line,
+ * sideband.fleet, sideband.drift, manual.admin) — unknown values are
+ * accepted and applied verbatim (forward-compat for ADR-047 amendments).
+ */
+import chalk from "chalk";
+import { listSidebandAdvisoriesForAgent, listSidebandAdvisoriesForTeam, } from "../lib/api.js";
+import { requireAuth } from "../lib/auth.js";
+import { fmt } from "../lib/format.js";
+function statusBadge(s) {
+    switch (s) {
+        case "pending":
+            return fmt.badge("PENDING", "yellow");
+        case "consumed":
+            return chalk.dim("consumed");
+        case "expired":
+            return chalk.dim("expired");
+        default:
+            return chalk.dim(s.toUpperCase());
+    }
+}
+function shortId(id) {
+    return id.length <= 16 ? id : id.slice(0, 13) + "...";
+}
+function formatRow(a) {
+    return [
+        chalk.dim(shortId(a.id).padEnd(16)),
+        chalk.cyan(a.source.padEnd(22)),
+        statusBadge(a.status).padEnd(20),
+        chalk.dim(a.created_at.replace("T", " ").replace(/\.\d+Z$/, "Z")),
+        a.concerns_summary,
+    ].join("  ");
+}
+// ─── mnemom advisories list ──────────────────────────────────────────────
+export async function advisoriesListCommand(opts) {
+    if (!opts.agent && !opts.team) {
+        console.error(fmt.error("--agent <id> or --team <id> is required") + "\n");
+        process.exit(1);
+    }
+    if (opts.agent && opts.team) {
+        console.error(fmt.error("--agent and --team are mutually exclusive") + "\n");
+        process.exit(1);
+    }
+    await requireAuth();
+    const limit = opts.limit ? parseInt(opts.limit, 10) : undefined;
+    if (opts.limit && (Number.isNaN(limit) || (limit ?? 0) <= 0)) {
+        console.error(fmt.error(`--limit must be a positive integer (got '${opts.limit}')`) + "\n");
+        process.exit(1);
+    }
+    let result;
+    let scopeLabel;
+    try {
+        if (opts.agent) {
+            result = await listSidebandAdvisoriesForAgent(opts.agent, {
+                limit,
+                since: opts.since,
+            });
+            scopeLabel = `agent ${opts.agent}`;
+        }
+        else {
+            result = await listSidebandAdvisoriesForTeam(opts.team, {
+                limit,
+                since: opts.since,
+            });
+            scopeLabel = `team ${opts.team}`;
+        }
+    }
+    catch (err) {
+        console.error(fmt.error(err instanceof Error ? err.message : String(err)) + "\n");
+        process.exit(1);
+        return;
+    }
+    let advisories = result.advisories;
+    if (opts.source) {
+        advisories = advisories.filter((a) => a.source === opts.source);
+    }
+    if (opts.json) {
+        console.log(fmt.json({ ...result, advisories }));
+        return;
+    }
+    if (advisories.length === 0) {
+        console.log(chalk.dim(`No sideband advisories for ${scopeLabel}.`));
+        return;
+    }
+    console.log(chalk.bold(`Sideband advisories — ${scopeLabel}`));
+    console.log(chalk.dim(`(${advisories.length} row(s))`));
+    console.log();
+    console.log(chalk.dim("ID                SOURCE                  STATUS              CREATED              SUMMARY"));
+    for (const a of advisories) {
+        console.log(formatRow(a));
+    }
+}
+// ─── mnemom advisories show ──────────────────────────────────────────────
+export async function advisoriesShowCommand(advisoryId, opts) {
+    if (!opts.agent && !opts.team) {
+        console.error(fmt.error("--agent <id> or --team <id> is required (the listing endpoint scopes results)") +
+            "\n");
+        process.exit(1);
+    }
+    await requireAuth();
+    let advisories;
+    try {
+        if (opts.agent) {
+            advisories = (await listSidebandAdvisoriesForAgent(opts.agent, { limit: 200 })).advisories;
+        }
+        else {
+            advisories = (await listSidebandAdvisoriesForTeam(opts.team, { limit: 500 })).advisories;
+        }
+    }
+    catch (err) {
+        console.error(fmt.error(err instanceof Error ? err.message : String(err)) + "\n");
+        process.exit(1);
+        return;
+    }
+    const match = advisories.find((a) => a.id === advisoryId);
+    if (!match) {
+        console.error(fmt.error(`Advisory '${advisoryId}' not found in scope.`) + "\n");
+        process.exit(1);
+        return;
+    }
+    if (opts.json) {
+        console.log(fmt.json(match));
+        return;
+    }
+    console.log(chalk.bold(match.id));
+    console.log();
+    console.log(fmt.label("source       ", match.source));
+    console.log(fmt.label("status       ", match.status));
+    console.log(fmt.label("agent_id     ", match.agent_id));
+    console.log(fmt.label("created_at   ", match.created_at));
+    console.log(fmt.label("expires_at   ", match.expires_at));
+    if (match.consumed_at) {
+        console.log(fmt.label("consumed_at  ", match.consumed_at));
+    }
+    console.log();
+    console.log(chalk.bold("Concerns summary"));
+    console.log(`  ${match.concerns_summary}`);
+    console.log();
+    console.log(chalk.bold("Nudge content (injected to agent)"));
+    console.log(`  ${match.nudge_content}`);
+    if (match.source_ref) {
+        console.log();
+        console.log(chalk.bold("source_ref"));
+        console.log(fmt.json(match.source_ref));
+    }
+}

package/dist/commands/api-key.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `mnemom api-key ...` commands — capability-based API key management
+ * (ADR-049). Mirrors the dashboard scope picker and the API mint-time
+ * vocabulary; one CLI surface for the same key lifecycle operations.
+ *
+ *   mnemom api-key list                              — list active personal keys
+ *   mnemom api-key create --name <name> [--scopes a,b,c]
+ *                                                    — mint a new key
+ *   mnemom api-key rotate <key_id>                   — atomic mint-new + revoke-old
+ *   mnemom api-key revoke <key_id>                   — soft-delete
+ *
+ * Auth: any of the standard CLI auth methods — JWT (`mnemom login`),
+ * MNEMOM_API_KEY env, or a stored API key. Note the chicken-and-egg:
+ * to mint your first key you'll need a JWT (the website's create-key
+ * dialog is the alternative). After that, an `api:write` key can mint
+ * additional keys for itself.
+ */
+import { type ApiKeyScope } from "../lib/api.js";
+/**
+ * Exported for tests. Parses a comma-separated `--scopes` flag value,
+ * accepts legacy `api` for backward compat, and returns a typed array.
+ * Throws on unknown scope names so users get a clear error instead of
+ * silently dropping intent.
+ */
+export declare function parseScopes(input: string | undefined): ApiKeyScope[];
+export declare function apiKeyListCommand(opts: {
+    json?: boolean;
+}): Promise<void>;
+export declare function apiKeyCreateCommand(opts: {
+    name?: string;
+    scopes?: string;
+    json?: boolean;
+}): Promise<void>;
+export declare function apiKeyRotateCommand(keyId: string | undefined, opts: {
+    json?: boolean;
+}): Promise<void>;
+export declare function apiKeyRevokeCommand(keyId: string | undefined): Promise<void>;

package/dist/commands/api-key.js

@@ -0,0 +1,181 @@
+/**
+ * `mnemom api-key ...` commands — capability-based API key management
+ * (ADR-049). Mirrors the dashboard scope picker and the API mint-time
+ * vocabulary; one CLI surface for the same key lifecycle operations.
+ *
+ *   mnemom api-key list                              — list active personal keys
+ *   mnemom api-key create --name <name> [--scopes a,b,c]
+ *                                                    — mint a new key
+ *   mnemom api-key rotate <key_id>                   — atomic mint-new + revoke-old
+ *   mnemom api-key revoke <key_id>                   — soft-delete
+ *
+ * Auth: any of the standard CLI auth methods — JWT (`mnemom login`),
+ * MNEMOM_API_KEY env, or a stored API key. Note the chicken-and-egg:
+ * to mint your first key you'll need a JWT (the website's create-key
+ * dialog is the alternative). After that, an `api:write` key can mint
+ * additional keys for itself.
+ */
+import { listApiKeys, createApiKey, rotateApiKey, revokeApiKey, isLegacyScopeSet, API_KEY_SCOPES, DEFAULT_API_KEY_SCOPES, } from "../lib/api.js";
+import { requireAuth } from "../lib/auth.js";
+import { fmt } from "../lib/format.js";
+// ─── Helpers ─────────────────────────────────────────────────────────────
+/**
+ * Exported for tests. Parses a comma-separated `--scopes` flag value,
+ * accepts legacy `api` for backward compat, and returns a typed array.
+ * Throws on unknown scope names so users get a clear error instead of
+ * silently dropping intent.
+ */
+export function parseScopes(input) {
+    if (!input)
+        return [...DEFAULT_API_KEY_SCOPES];
+    const raw = input
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    if (raw.length === 0)
+        return [...DEFAULT_API_KEY_SCOPES];
+    const valid = new Set(API_KEY_SCOPES);
+    // Accept legacy 'api' input here so users who copy-paste from older
+    // docs/scripts get a clean canonicalization. The API also aliases.
+    valid.add("api");
+    const unknown = raw.filter((s) => !valid.has(s));
+    if (unknown.length > 0) {
+        throw new Error(`Unknown scope(s): ${unknown.join(", ")}. ` +
+            `Valid: ${Array.from(API_KEY_SCOPES).join(", ")}`);
+    }
+    return raw;
+}
+function renderScopeBadge(scope) {
+    // Admin scopes get a visual marker so the audit trail in the CLI
+    // makes elevated keys obvious at a glance.
+    if (scope === "admin:platform" || scope === "admin:org") {
+        return fmt.warn(`[${scope}]`);
+    }
+    return `[${scope}]`;
+}
+function formatRow(key) {
+    const created = key.created_at
+        ? new Date(key.created_at).toISOString().slice(0, 10)
+        : "?";
+    const lastUsed = key.last_used_at
+        ? new Date(key.last_used_at).toISOString().slice(0, 10)
+        : "never";
+    const scopes = (key.scopes ?? []).map(renderScopeBadge).join(" ");
+    const legacy = isLegacyScopeSet(key.scopes) ? fmt.dim(" (legacy)") : "";
+    return `  ${key.key_id}  ${key.key_prefix}…  ${key.name.padEnd(24)}  ${scopes}${legacy}\n    created ${created} · last used ${lastUsed}`;
+}
+// ─── mnemom api-key list ─────────────────────────────────────────────────
+export async function apiKeyListCommand(opts) {
+    await requireAuth();
+    let keys;
+    try {
+        keys = await listApiKeys();
+    }
+    catch (err) {
+        console.error(fmt.error(`Failed to list api keys: ${err instanceof Error ? err.message : err}`));
+        process.exit(1);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(keys, null, 2));
+        return;
+    }
+    if (keys.length === 0) {
+        console.log("\nNo active api keys.\n");
+        console.log("Create one with `mnemom api-key create --name <name>`.\n");
+        return;
+    }
+    console.log();
+    console.log(fmt.header(`Active api keys (${keys.length})`));
+    console.log();
+    for (const k of keys) {
+        console.log(formatRow(k));
+        console.log();
+    }
+}
+// ─── mnemom api-key create ───────────────────────────────────────────────
+export async function apiKeyCreateCommand(opts) {
+    await requireAuth();
+    if (!opts.name || opts.name.trim() === "") {
+        console.error(fmt.error("--name is required. Example: --name 'ci-prod'"));
+        process.exit(1);
+    }
+    let scopes;
+    try {
+        scopes = parseScopes(opts.scopes);
+    }
+    catch (err) {
+        console.error(fmt.error(err instanceof Error ? err.message : String(err)));
+        process.exit(1);
+    }
+    let created;
+    try {
+        created = await createApiKey(opts.name.trim(), scopes);
+    }
+    catch (err) {
+        console.error(fmt.error(`Create failed: ${err instanceof Error ? err.message : err}`));
+        process.exit(1);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(created, null, 2));
+        return;
+    }
+    console.log();
+    console.log(fmt.success(`Created ${created.key_id}`));
+    console.log();
+    console.log(fmt.label("  Name:    ", ` ${created.name}`));
+    console.log(fmt.label("  Scopes:  ", ` ${(created.scopes ?? []).join(", ")}`));
+    console.log(fmt.label("  Created: ", ` ${created.created_at}`));
+    console.log();
+    console.log(fmt.warn("  Cleartext (shown once — copy now):"));
+    console.log(`    ${created.key}`);
+    console.log();
+    console.log(fmt.dim("  This is the only time the cleartext is returned."));
+    console.log(fmt.dim("  Mnemom stores only the SHA-256 hash; the key cannot be retrieved later."));
+    console.log();
+}
+// ─── mnemom api-key rotate ───────────────────────────────────────────────
+export async function apiKeyRotateCommand(keyId, opts) {
+    await requireAuth();
+    if (!keyId) {
+        console.error(fmt.error("Usage: mnemom api-key rotate <key_id>"));
+        process.exit(1);
+    }
+    let rotated;
+    try {
+        rotated = await rotateApiKey(keyId);
+    }
+    catch (err) {
+        console.error(fmt.error(`Rotate failed: ${err instanceof Error ? err.message : err}`));
+        process.exit(1);
+    }
+    if (opts.json) {
+        console.log(JSON.stringify(rotated, null, 2));
+        return;
+    }
+    console.log();
+    console.log(fmt.success(`Rotated. Old key ${keyId} is now revoked.`));
+    console.log();
+    console.log(fmt.label("  New key id:", ` ${rotated.key_id}`));
+    console.log(fmt.label("  Name:      ", ` ${rotated.name}`));
+    console.log(fmt.label("  Scopes:    ", ` ${(rotated.scopes ?? []).join(", ")}`));
+    console.log();
+    console.log(fmt.warn("  New cleartext (shown once — copy now):"));
+    console.log(`    ${rotated.key}`);
+    console.log();
+}
+// ─── mnemom api-key revoke ───────────────────────────────────────────────
+export async function apiKeyRevokeCommand(keyId) {
+    await requireAuth();
+    if (!keyId) {
+        console.error(fmt.error("Usage: mnemom api-key revoke <key_id>"));
+        process.exit(1);
+    }
+    try {
+        await revokeApiKey(keyId);
+    }
+    catch (err) {
+        console.error(fmt.error(`Revoke failed: ${err instanceof Error ? err.message : err}`));
+        process.exit(1);
+    }
+    console.log(fmt.success(`Revoked ${keyId}.`));
+}

package/dist/commands/governance.d.ts

@@ -0,0 +1,85 @@
+/**
+ * `mnemom governance` — operator CLI for governance signals (ADR-048).
+ *
+ * Subcommands:
+ *
+ *   signals      list | show | ack | resolve | dismiss
+ *   destinations list | add | remove | test
+ *   rules        list | add | remove
+ *
+ * The signal surface is operator-actionable: cron-driven sideband
+ * detections, future protection / posture observations. Distinct from
+ * `mnemom advisories list` (now narrowed to runtime.* / manual.* per
+ * ADR-048 §1).
+ */
+interface ListOpts {
+    org?: string;
+    team?: string;
+    agent?: string;
+    source?: string;
+    severity?: string;
+    status?: string;
+    scope?: string;
+    patternType?: string;
+    limit?: string;
+    since?: string;
+    json?: boolean;
+}
+interface AckOpts {
+    action?: string;
+    json?: boolean;
+}
+interface ResolveOpts {
+    status: string;
+    action?: string;
+    json?: boolean;
+}
+interface DismissOpts {
+    reason?: string;
+    json?: boolean;
+}
+interface DestAddOpts {
+    org: string;
+    channel: string;
+    config: string;
+    name?: string;
+    filter?: string;
+    json?: boolean;
+}
+interface RuleAddOpts {
+    org: string;
+    name: string;
+    predicate: string;
+    destinations: string;
+    json?: boolean;
+}
+export declare function governanceSignalsListCommand(opts: ListOpts): Promise<void>;
+export declare function governanceSignalsShowCommand(signalId: string, opts: {
+    json?: boolean;
+}): Promise<void>;
+export declare function governanceSignalsAckCommand(signalId: string, opts: AckOpts): Promise<void>;
+export declare function governanceSignalsResolveCommand(signalId: string, opts: ResolveOpts): Promise<void>;
+export declare function governanceSignalsDismissCommand(signalId: string, opts: DismissOpts): Promise<void>;
+export declare function governanceDestinationsListCommand(opts: {
+    org: string;
+    json?: boolean;
+}): Promise<void>;
+export declare function governanceDestinationsAddCommand(opts: DestAddOpts): Promise<void>;
+export declare function governanceDestinationsRemoveCommand(destinationId: string, opts: {
+    org: string;
+    json?: boolean;
+}): Promise<void>;
+export declare function governanceDestinationsTestCommand(destinationId: string, opts: {
+    org: string;
+    json?: boolean;
+}): Promise<void>;
+export declare function governanceRulesListCommand(opts: {
+    org: string;
+    json?: boolean;
+}): Promise<void>;
+export declare function governanceRulesAddCommand(opts: RuleAddOpts): Promise<void>;
+export declare function governanceRulesRemoveCommand(ruleId: string, opts: {
+    org: string;
+    json?: boolean;
+}): Promise<void>;
+export {};