@uic-coe-connect/cli 0.9.0 → 0.10.0

package/dist/commands/apps.js

@@ -50,6 +50,8 @@ export function registerAppCommands() {
                 details([
                     ["Id", app.id],
                     ["Name", app.name],
+                    ["Description", app.description || "(none — required; set it before other edits)"],
+                    ["Visibility", app.stage === "dev" ? "development (dev team only)" : "live"],
                     ["VM", app.vmId ?? "—"],
                     ["URL", app.url],
                     ["Repo", app.repo ?? "—"],

package/dist/commands/events.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Events and alarms from the terminal.
+ *
+ * The read side matters most here: an agent investigating "why is this app
+ * behaving oddly" wants the event names, a series, and which alarms are
+ * currently firing, and none of that should require a browser.
+ */
+export declare function registerEventCommands(): void;

package/dist/commands/events.js

@@ -0,0 +1,135 @@
+import { details, emit, info, table } from "../output.js";
+import { register } from "../registry.js";
+import { resolveApp } from "./apps.js";
+/**
+ * Events and alarms from the terminal.
+ *
+ * The read side matters most here: an agent investigating "why is this app
+ * behaving oddly" wants the event names, a series, and which alarms are
+ * currently firing, and none of that should require a browser.
+ */
+export function registerEventCommands() {
+    register({
+        name: "events list",
+        summary: "Event names an app reports, and anything refused today",
+        usage: "events list <app>",
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const data = await c.request("GET", `/registered-apps/${app.id}/events/names`);
+            emit(data, () => {
+                if (data.names.length === 0) {
+                    info(`${app.id} has not reported any events.`);
+                }
+                else {
+                    table(data.names.map((n) => ({
+                        name: n.name,
+                        "first seen": n.firstSeen.slice(0, 10),
+                        "last seen": n.lastSeen.slice(0, 16).replace("T", " "),
+                    })), ["name", "first seen", "last seen"]);
+                }
+                const dropped = Object.values(data.drops).reduce((a, b) => a + b, 0);
+                if (dropped > 0) {
+                    info("");
+                    info(`${dropped} refused today — rate ${data.drops.rate ?? 0}, ` +
+                        `over the name cap ${data.drops.names ?? 0}, unusable name ${data.drops.invalid ?? 0}.`);
+                }
+                info("");
+                info(`Limits: ${data.limits.ratePerMin}/min, ${data.limits.maxNames} distinct names, 30-day retention.`);
+            });
+        },
+    }, {
+        name: "events series",
+        summary: "One event name as a time series",
+        usage: "events series <app> <name> [--days <n>] [--bucket <min>] [--agg <a>]",
+        details: [
+            "  --days    How far back. Default 7, max 30.",
+            "  --bucket  Bucket width in minutes. Default 60.",
+            "  --agg     count | sum | avg | max | min. Default count.",
+        ],
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const name = args.arg(1, "name");
+            const params = new URLSearchParams({ name });
+            for (const [flag, key] of [["days", "days"], ["bucket", "bucket"], ["agg", "agg"]]) {
+                const v = args.flag(flag);
+                if (v)
+                    params.set(key, v);
+            }
+            const data = await c.request("GET", `/registered-apps/${app.id}/events/series?${params}`);
+            emit(data, () => {
+                if (data.points.length === 0) {
+                    info(`No "${name}" events in that window.`);
+                    return;
+                }
+                table(data.points.map((p) => ({
+                    when: p.ts.slice(0, 16).replace("T", " "),
+                    value: String(Math.round(p.value * 100) / 100),
+                })), ["when", "value"]);
+            });
+        },
+    }, {
+        name: "events recent",
+        summary: "The most recent raw events",
+        usage: "events recent <app> [--name <event>] [--limit <n>]",
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const params = new URLSearchParams();
+            if (args.flag("name"))
+                params.set("name", args.flag("name"));
+            if (args.flag("limit"))
+                params.set("limit", args.flag("limit"));
+            const data = await c.request("GET", `/registered-apps/${app.id}/events/recent?${params}`);
+            emit(data, () => table(data.events.map((e) => ({
+                when: e.ts.slice(0, 19).replace("T", " "),
+                name: e.name,
+                value: String(e.value),
+                props: e.props ? JSON.stringify(e.props) : "",
+            })), ["when", "name", "value", "props"]));
+        },
+    }, {
+        name: "alarms list",
+        summary: "An app's alarms and what each is currently reading",
+        usage: "alarms list <app>",
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const data = await c.request("GET", `/registered-apps/${app.id}/alarms`);
+            emit(data, () => {
+                if (data.alarms.length === 0) {
+                    info(`${app.id} has no alarms. Add one in the portal's Events tab.`);
+                    return;
+                }
+                table(data.alarms.map((a) => ({
+                    state: a.enabled ? a.state : "off",
+                    name: a.name,
+                    condition: a.description,
+                    now: a.lastValue === null ? "—" : String(Math.round(a.lastValue * 100) / 100),
+                    emails: a.recipients.join(","),
+                })), ["state", "name", "condition", "now", "emails"]);
+                const firing = data.alarms.filter((a) => a.enabled && a.state === "firing");
+                if (firing.length > 0) {
+                    info("");
+                    info(`${firing.length} firing: ${firing.map((a) => a.name).join(", ")}`);
+                }
+            });
+        },
+    }, {
+        name: "alarms check",
+        summary: "Evaluate one alarm now, without emailing anyone",
+        usage: "alarms check <app> <alarm-id>",
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const id = args.arg(1, "alarm-id");
+            const data = await c.request("POST", `/registered-apps/${app.id}/alarms/${id}/evaluate`);
+            emit(data, () => details([
+                ["Condition", data.description],
+                ["Value", data.measurable ? String(Math.round((data.value ?? 0) * 100) / 100) : "not measurable"],
+                ["Would fire", data.wouldFire ? "yes" : "no"],
+            ]));
+        },
+    });
+}

package/dist/commands/integration.d.ts

@@ -0,0 +1 @@
+export declare function registerIntegrationCommands(): void;

package/dist/commands/integration.js

@@ -0,0 +1,193 @@
+import { details, emit, info } from "../output.js";
+import { register } from "../registry.js";
+import { resolveApp } from "./apps.js";
+/**
+ * Everything the SDK reads, and what each one turns on. The CLI knows the
+ * *names* rather than the values — env values live behind their own route on
+ * purpose (see `coe env`), and an integration check should never be the thing
+ * that prints a secret into a terminal scrollback.
+ */
+const REQUIRED_ENV = [
+    { key: "SHIB_MODE", enables: "real SAML instead of the dev login form" },
+    { key: "SHIB_DOMAIN", enables: "the app's own hostname, for the SP endpoints" },
+    { key: "SHIB_VM_HOST", enables: "which VM's SP entity the app authenticates under" },
+    { key: "SESSION_SECRET", enables: "signing the session cookie" },
+    { key: "COE_URL", enables: "reaching COEConnect" },
+    { key: "COE_APP_ID", enables: "identifying this app to COEConnect" },
+    { key: "COE_APP_TOKEN", enables: "access enforcement and login reporting" },
+    {
+        key: "SHIB_PRIVATE_KEY_PATH",
+        enables: "a non-default SP key path",
+        optional: true,
+    },
+];
+/** The legacy fleet-wide credentials, still honoured but worth moving off. */
+const LEGACY_ENV = ["COE_ACCESS_TOKEN", "COE_EVENTS_TOKEN", "COE_NOTIFY_TOKEN"];
+export function registerIntegrationCommands() {
+    register({
+        name: "integration show",
+        summary: "Full integration status for an app — what's wired up and what's missing",
+        usage: "integration show <app>",
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const token = await c
+                .request("GET", `/registered-apps/${app.id}/token`)
+                .then((r) => r.token)
+                .catch(() => null);
+            const usage = await c
+                .request("GET", `/registered-apps/${app.id}/logins?days=30`)
+                .catch(() => null);
+            const envKeys = new Set(app.envKeys ?? []);
+            const missing = REQUIRED_ENV.filter((e) => !e.optional && !envKeys.has(e.key));
+            const legacy = LEGACY_ENV.filter((k) => envKeys.has(k));
+            // Stored env only reaches the VM through a pipeline's `env` step. An
+            // app can look perfectly configured here and have none of it on disk,
+            // which is the single most common reason an integration "doesn't work".
+            const pipelines = app.pipelines ?? [];
+            const writesEnv = pipelines.some((p) => p.config.steps.some((s) => s.type === "env"));
+            const catalogOnly = app.integration === "catalog";
+            const next = nextSteps({
+                catalogOnly,
+                hasToken: Boolean(token),
+                tokenUsed: Boolean(token?.lastUsedAt),
+                missing: missing.map((m) => m.key),
+                legacy,
+                hasPipeline: pipelines.length > 0,
+                writesEnv,
+                reporting: usage?.reporting ?? false,
+            });
+            emit({
+                appId: app.id,
+                integration: app.integration ?? "coeconnect",
+                url: app.url,
+                vmId: app.vmId,
+                token,
+                env: {
+                    present: REQUIRED_ENV.filter((e) => envKeys.has(e.key)).map((e) => e.key),
+                    missing: missing.map((e) => e.key),
+                    legacy,
+                },
+                pipeline: { count: pipelines.length, writesEnv },
+                usage: usage && {
+                    reporting: usage.reporting,
+                    distinctUsers30d: usage.distinctUsers,
+                },
+                nextSteps: next,
+            }, () => {
+                details([
+                    ["App", `${app.id} (${app.url})`],
+                    ["Integration", catalogOnly ? "catalogue entry — the app does not call COEConnect" : "coeconnect"],
+                    [
+                        "Service token",
+                        token
+                            ? `${token.preview}… created ${token.createdAt.slice(0, 10)} by ${token.createdBy}` +
+                                (token.lastUsedAt ? `, last used ${token.lastUsedAt.slice(0, 16).replace("T", " ")}` : ", NEVER USED")
+                            : "none — run: coe token generate " + app.id,
+                    ],
+                    ["Env present", REQUIRED_ENV.filter((e) => envKeys.has(e.key)).map((e) => e.key).join(", ") || "(none)"],
+                    ["Env missing", missing.map((e) => e.key).join(", ") || "(none)"],
+                    ["Legacy env", legacy.join(", ") || "(none)"],
+                    ["Pipelines", `${pipelines.length}${pipelines.length > 0 ? (writesEnv ? ", writes .env" : ", NO env step") : ""}`],
+                    ["Login reporting", usage ? (usage.reporting ? `yes — ${usage.distinctUsers} people in 30d` : "no logins reported yet") : "unknown"],
+                ]);
+                if (next.length > 0) {
+                    info("");
+                    info("NEXT STEPS");
+                    for (const step of next)
+                        info(`  • ${step}`);
+                }
+            });
+        },
+    }, {
+        name: "token show",
+        summary: "Show an app's service token metadata (never the token itself)",
+        usage: "token show <app>",
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const { token } = await c.request("GET", `/registered-apps/${app.id}/token`);
+            emit({ appId: app.id, token }, () => {
+                if (!token) {
+                    info(`No service token for ${app.id}. Run: coe token generate ${app.id}`);
+                    return;
+                }
+                details([
+                    ["Token", `${token.preview}…`],
+                    ["Created", `${token.createdAt} by ${token.createdBy}`],
+                    ["Last used", token.lastUsedAt ?? "never — the app has not called COEConnect"],
+                ]);
+            });
+        },
+    }, {
+        name: "token generate",
+        summary: "Mint a new service token, printing the three env lines an app needs",
+        usage: "token generate <app>",
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const existing = await c
+                .request("GET", `/registered-apps/${app.id}/token`)
+                .then((r) => r.token)
+                .catch(() => null);
+            const { token } = await c.request("POST", `/registered-apps/${app.id}/token`);
+            const env = {
+                COE_URL: c.server,
+                COE_APP_ID: app.id,
+                COE_APP_TOKEN: token,
+            };
+            emit({ appId: app.id, token, env, rotated: Boolean(existing) }, () => {
+                if (existing) {
+                    info(`Rotated ${app.id}'s token — the previous one no longer works.`);
+                }
+                info("Shown once. Add these to the app's environment:");
+                info("");
+                for (const [k, v] of Object.entries(env))
+                    info(`  ${k}=${v}`);
+                info("");
+                info(`Set them with:  coe env set ${app.id} ${Object.entries(env).map(([k, v]) => `${k}=${v}`).join(" ")}`);
+                info("They reach the VM on the next deploy, and only if a pipeline has an env step.");
+            });
+        },
+    });
+}
+/**
+ * Turns the facts into an ordered list of things to actually do.
+ *
+ * Ordered by dependency, not severity: telling someone to redeploy before they
+ * have a token to deploy is noise. An agent reads this top-down and stops
+ * having to infer the sequence from a pile of booleans.
+ */
+function nextSteps(f) {
+    const steps = [];
+    if (f.catalogOnly) {
+        steps.push("This is a catalogue entry: it has a dev team but no staff access, and cannot enforce " +
+            "or report anything. Integrate it with @uic-coe-connect/auth first, then change its " +
+            "integration setting in the portal.");
+        return steps;
+    }
+    if (!f.hasToken)
+        steps.push("Generate a service token: coe token generate <app>");
+    if (f.missing.length > 0) {
+        steps.push(`Set the missing environment variables: ${f.missing.join(", ")}`);
+    }
+    if (f.legacy.length > 0) {
+        steps.push(`Replace the legacy fleet-wide credentials (${f.legacy.join(", ")}) with COE_APP_TOKEN. ` +
+            "They still work, but they authenticate against every app at once.");
+    }
+    if (!f.hasPipeline) {
+        steps.push("Create a deploy pipeline: coe pipelines create <app> ...");
+    }
+    else if (!f.writesEnv) {
+        steps.push("Add an env step to the pipeline, or stored variables never reach the VM: " +
+            "coe pipelines create <app> --name Deploy pull scan env:backend ...");
+    }
+    if (f.hasToken && !f.tokenUsed) {
+        steps.push("The token has never been used, so the app has not called COEConnect. Deploy it, then " +
+            "check the app's startup log for the [coe-auth] lines.");
+    }
+    else if (!f.reporting) {
+        steps.push("No logins reported yet. Sign in to the app once, then re-check.");
+    }
+    return steps;
+}

package/dist/commands/reports.js

@@ -200,6 +200,30 @@ export function registerReportCommands() {
             const { report } = await client().request("POST", `/reports/${id}/comments`, { body: args.flag("note") ?? "", status });
             emit({ report }, () => info(`✓ ${report.id} is now ${report.status}`));
         },
+    }, {
+        name: "reports close",
+        summary: "Close a report as done, or as won't do",
+        usage: "reports close <id> [--wont-do] [--note <message>]",
+        details: [
+            "  --wont-do  Close as declined rather than done",
+            "  --note     A message to send with it — closing in silence is how you",
+            "             teach people to stop filing reports",
+        ],
+        async run({ args, client }) {
+            const id = args.arg(0, "id");
+            const status = args.bool("wont-do") ? "declined" : "done";
+            const { report } = await client().request("POST", `/reports/${id}/comments`, { body: args.flag("note") ?? "", status });
+            emit({ report }, () => info(`✓ Closed ${report.id} as ${report.status}`));
+        },
+    }, {
+        name: "reports reopen",
+        summary: "Reopen a closed report",
+        usage: "reports reopen <id> [--note <message>]",
+        async run({ args, client }) {
+            const id = args.arg(0, "id");
+            const { report } = await client().request("POST", `/reports/${id}/comments`, { body: args.flag("note") ?? "", status: "open" });
+            emit({ report }, () => info(`✓ Reopened ${report.id}`));
+        },
     }, {
         name: "reports attach",
         summary: "Attach a file to a report",

package/dist/index.js

@@ -5,6 +5,8 @@ import { registerAppCommands } from "./commands/apps.js";
 import { registerAuthCommands } from "./commands/auth.js";
 import { registerDeployCommands } from "./commands/deploy.js";
 import { registerEnvCommands } from "./commands/env.js";
+import { registerEventCommands } from "./commands/events.js";
+import { registerIntegrationCommands } from "./commands/integration.js";
 import { registerLogCommands } from "./commands/logs.js";
 import { registerPipelineCommands } from "./commands/pipelines.js";
 import { registerReportCommands } from "./commands/reports.js";
@@ -17,6 +19,8 @@ registerAppCommands();
 registerPipelineCommands();
 registerDeployCommands();
 registerAccessCommands();
+registerIntegrationCommands();
+registerEventCommands();
 registerEnvCommands();
 registerResourceCommands();
 registerLogCommands();

package/dist/types.d.ts

@@ -64,6 +64,10 @@ export interface AppAccess {
 export interface RegisteredApp {
     id: string;
     name: string;
+    /** One line shown under the app's name in the launcher. Required on write. */
+    description: string;
+    /** "dev" hides the app from everyone but its dev team and webadmins. */
+    stage?: "production" | "dev";
     url: string;
     /** Which VM hosts this app — deploys, logs and env all act on that machine. */
     vmId: string;
@@ -77,6 +81,12 @@ export interface RegisteredApp {
     envKeys: string[];
     pipelines?: NamedPipeline[];
     access?: AppAccess;
+    /**
+     * Whether the app actually calls COEConnect, or is only listed in the
+     * portal's inventory. A catalogue entry has a dev team but can't enforce
+     * staff access or report usage. Absent means "coeconnect".
+     */
+    integration?: "coeconnect" | "catalog";
     createdAt: string;
     updatedAt: string;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@uic-coe-connect/cli",
-  "version": "0.9.0",
-  "description": "The coe CLI — manage COEConnect apps (pipelines, deploys, access, env) from a terminal, with browser-approved auth. Designed to be driven by an AI agent.",
+  "version": "0.10.0",
+  "description": "The coe CLI \u2014 manage COEConnect apps (pipelines, deploys, access, env) from a terminal, with browser-approved auth. Designed to be driven by an AI agent.",
   "type": "module",
   "bin": {
     "coe": "./dist/index.js"