@uic-coe-connect/cli 0.1.0 → 0.2.1

package/dist/client.d.ts

@@ -20,5 +20,9 @@ export interface Client {
     request<T>(method: string, path: string, body?: unknown): Promise<T>;
     /** Streams a text/plain response line by line — used by `deploy`. */
     stream(method: string, path: string, body: unknown, onLine: (line: string) => void): Promise<void>;
+    /** POSTs raw bytes with the filename in a header — the resource upload shape. */
+    upload<T>(path: string, filename: string, bytes: Uint8Array): Promise<T>;
+    /** GETs raw bytes — the resource download shape. */
+    download(path: string): Promise<Uint8Array>;
 }
 export declare function createClient(options?: ClientOptions): Client;

package/dist/client.js

@@ -60,6 +60,29 @@ export function createClient(options = {}) {
                 return undefined;
             return (await res.json());
         },
+        async upload(path, filename, bytes) {
+            // Raw body, not multipart — matches the server, which parses these with
+            // express.raw. The name travels url-encoded because header values can't
+            // safely carry arbitrary UTF-8.
+            const res = await fetch(`${server}${path}`, {
+                method: "POST",
+                headers: {
+                    ...headers,
+                    "Content-Type": "application/octet-stream",
+                    "X-File-Name": encodeURIComponent(filename),
+                },
+                body: bytes,
+            });
+            if (!res.ok)
+                await fail(res, server);
+            return (await res.json());
+        },
+        async download(path) {
+            const res = await fetch(`${server}${path}`, { headers });
+            if (!res.ok)
+                await fail(res, server);
+            return new Uint8Array(await res.arrayBuffer());
+        },
         async stream(method, path, body, onLine) {
             const res = await fetch(`${server}${path}`, { method, headers, ...bodyInit(body) });
             if (!res.ok)

package/dist/commands/apps.js

@@ -54,7 +54,7 @@ export function registerAppCommands() {
                     ["Branch", app.branch ?? "—"],
                     ["Pipelines", (app.pipelines ?? []).map((p) => p.name).join(", ") || "(none)"],
                     ["Dev team", (app.access?.devTeam ?? []).join(", ") || "(none)"],
-                    ["Env vars", Object.keys(app.env ?? {}).join(", ") || "(none)"],
+                    ["Env vars", (app.envKeys ?? []).join(", ") || "(none)"],
                     ["Updated", new Date(app.updatedAt).toLocaleString()],
                 ]);
             });

package/dist/commands/resources.d.ts

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

package/dist/commands/resources.js

@@ -0,0 +1,145 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { CliError } from "../client.js";
+import { details, emit, info, table } from "../output.js";
+import { register } from "../registry.js";
+import { resolveApp } from "./apps.js";
+function humanSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(0)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+/**
+ * Find one resource by name or id. Names are what people actually know, and
+ * they're unique per app because a re-upload replaces rather than duplicates.
+ */
+function find(resources, ref) {
+    const found = resources.find((r) => r.id === ref) ??
+        resources.find((r) => r.name.toLowerCase() === ref.toLowerCase());
+    if (!found) {
+        throw new CliError(`No resource "${ref}".`, 4, resources.length > 0
+            ? `Available: ${resources.map((r) => r.name).join(", ")}`
+            : "That app has no resources yet — add one with: coe files upload");
+    }
+    return found;
+}
+export function registerResourceCommands() {
+    register({
+        name: "files list",
+        summary: "List an app's resources (documents and links)",
+        usage: "files list <app>",
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const { files } = await c.request("GET", `/registered-apps/${app.id}/files`);
+            emit({ appId: app.id, files }, () => {
+                table(files.map((f) => ({
+                    kind: f.kind,
+                    name: f.name,
+                    size: f.kind === "link" ? (f.url ?? "") : humanSize(f.size),
+                    by: f.uploadedBy,
+                    description: f.description ?? "",
+                })), ["kind", "name", "size", "by", "description"]);
+            });
+        },
+    }, {
+        name: "files upload",
+        summary: "Upload a document to an app",
+        usage: "files upload <app> <path> [--description <text>]",
+        details: [
+            "Markdown, PDF, Office docs, images, CSV/JSON — up to 25 MB.",
+            "Re-uploading the same filename replaces the previous version.",
+        ],
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const filePath = args.arg(1, "path");
+            let bytes;
+            try {
+                bytes = readFileSync(filePath);
+            }
+            catch (error) {
+                throw new CliError(`Could not read ${filePath}: ${error instanceof Error ? error.message : String(error)}`, 6);
+            }
+            const file = await c.upload(`/registered-apps/${app.id}/files`, path.basename(filePath), bytes);
+            // The description is a separate PATCH — the upload carries bytes, not
+            // metadata, so keeping them apart avoids a second header to encode.
+            const description = args.flag("description");
+            if (description) {
+                await c.request("PATCH", `/registered-apps/${app.id}/files/${file.id}`, { description });
+            }
+            emit({ appId: app.id, file }, () => info(`✓ Uploaded ${file.name} (${humanSize(file.size)}) to ${app.id}`));
+        },
+    }, {
+        name: "files download",
+        summary: "Download a resource to a local file",
+        usage: "files download <app> <name> [--out <path>]",
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const { files } = await c.request("GET", `/registered-apps/${app.id}/files`);
+            const file = find(files, args.arg(1, "name"));
+            if (file.kind === "link") {
+                throw new CliError(`"${file.name}" is a link, not a stored file.`, 6, `It points at ${file.url}`);
+            }
+            const bytes = await c.download(`/registered-apps/${app.id}/files/${file.id}`);
+            const out = args.flag("out") ?? file.name;
+            writeFileSync(out, bytes);
+            emit({ appId: app.id, file: file.name, out, bytes: bytes.length }, () => info(`✓ Wrote ${out} (${humanSize(bytes.length)})`));
+        },
+    }, {
+        name: "files delete",
+        summary: "Delete a resource",
+        usage: "files delete <app> <name> --yes",
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const { files } = await c.request("GET", `/registered-apps/${app.id}/files`);
+            const file = find(files, args.arg(1, "name"));
+            if (!args.bool("yes")) {
+                throw new CliError(`This deletes "${file.name}" from ${app.id}.`, 6, "Re-run with --yes to confirm.");
+            }
+            await c.request("DELETE", `/registered-apps/${app.id}/files/${file.id}`);
+            emit({ appId: app.id, deleted: file.name }, () => info(`✓ Deleted ${file.name} from ${app.id}`));
+        },
+    }, {
+        name: "files link",
+        summary: "Add a link to material that lives elsewhere",
+        usage: 'files link <app> <url> [--name "Title"]',
+        details: ["Only http(s) URLs — a Google Doc, a wiki page, a dashboard."],
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const url = args.arg(1, "url");
+            const link = await c.request("POST", `/registered-apps/${app.id}/links`, {
+                url,
+                name: args.flag("name"),
+                description: args.flag("description"),
+            });
+            emit({ appId: app.id, link }, () => info(`✓ Linked "${link.name}" → ${link.url}`));
+        },
+    }, {
+        name: "files show",
+        summary: "Show one resource's details",
+        usage: "files show <app> <name>",
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const { files } = await c.request("GET", `/registered-apps/${app.id}/files`);
+            const file = find(files, args.arg(1, "name"));
+            emit(file, () => {
+                details([
+                    ["Name", file.name],
+                    ["Kind", file.kind],
+                    [file.kind === "link" ? "URL" : "Size", file.url ?? humanSize(file.size)],
+                    ["Type", file.contentType],
+                    ["Description", file.description ?? "—"],
+                    ["Uploaded by", file.uploadedBy],
+                    ["Uploaded at", new Date(file.uploadedAt).toLocaleString()],
+                ]);
+            });
+        },
+    });
+}

package/dist/commands/roles.d.ts

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

package/dist/commands/roles.js

@@ -0,0 +1,206 @@
+import { readFileSync } from "node:fs";
+import { CliError } from "../client.js";
+import { details, emit, info, table } from "../output.js";
+import { register } from "../registry.js";
+import { resolveApp } from "./apps.js";
+const OPERATORS = ["equals", "contains", "startsWith", "regex"];
+/** Comma- or space-separated NetIDs, deduped. */
+function netids(raw) {
+    return [...new Set(raw.split(/[,\s]+/).map((s) => s.trim()).filter(Boolean))];
+}
+function findRole(app, key) {
+    const roles = app.roles ?? [];
+    const found = roles.find((r) => r.key === key) ?? roles.find((r) => r.key.toLowerCase() === key.toLowerCase());
+    if (!found) {
+        throw new CliError(`No role "${key}" on ${app.id}.`, 4, roles.length > 0
+            ? `Defined: ${roles.map((r) => r.key).join(", ")}`
+            : "That app has no roles yet — create one with: coe roles create");
+    }
+    return found;
+}
+/** Saves the whole set back — the API replaces the array wholesale. */
+async function saveRoles(client, appId, roles) {
+    return client.request("PUT", `/registered-apps/${appId}/roles`, { roles });
+}
+function describeRule(rule) {
+    return rule.all.map((c) => `${c.attribute} ${c.operator} "${c.value}"`).join(" AND ");
+}
+export function registerRoleCommands() {
+    register({
+        name: "roles list",
+        summary: "List an app's custom roles",
+        usage: "roles list <app>",
+        async run({ args, client }) {
+            const app = await resolveApp(client(), args.arg(0, "app"));
+            const roles = app.roles ?? [];
+            emit({ appId: app.id, roles }, () => {
+                table(roles.map((r) => ({
+                    key: r.key,
+                    label: r.label,
+                    members: String(r.members.length),
+                    rules: String(r.rules.length),
+                })), ["key", "label", "members", "rules"]);
+            });
+        },
+    }, {
+        name: "roles show",
+        summary: "Show one role's members and rules",
+        usage: "roles show <app> <key>",
+        async run({ args, client }) {
+            const app = await resolveApp(client(), args.arg(0, "app"));
+            const role = findRole(app, args.arg(1, "key"));
+            emit(role, () => {
+                details([
+                    ["Key", role.key],
+                    ["Label", role.label],
+                    ["Description", role.description ?? "—"],
+                    ["Members", role.members.join(", ") || "(none)"],
+                ]);
+                if (role.rules.length === 0) {
+                    info("Rules       (none)");
+                    return;
+                }
+                info("Rules       grant if ANY matches:");
+                role.rules.forEach((rule, i) => info(`  [${i}] ${describeRule(rule)}`));
+            });
+        },
+    }, {
+        name: "roles create",
+        summary: "Create a role",
+        usage: 'roles create <app> <key> --label "Grant Reviewer" [--description <text>]',
+        details: [
+            "<key> is what the app sees in user.roles — keep it short and lowercase.",
+            "Members and rules are added afterwards with add-member / add-rule.",
+        ],
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const key = args.arg(1, "key").trim();
+            const label = args.flag("label");
+            if (!label)
+                throw new CliError("--label is required.", 6);
+            const roles = [...(app.roles ?? [])];
+            if (roles.some((r) => r.key.toLowerCase() === key.toLowerCase())) {
+                throw new CliError(`${app.id} already has a role "${key}".`, 6);
+            }
+            const role = {
+                key,
+                label,
+                description: args.flag("description"),
+                members: [],
+                rules: [],
+            };
+            await saveRoles(c, app.id, [...roles, role]);
+            emit({ appId: app.id, role }, () => info(`✓ Created role "${key}" on ${app.id} — grants nothing until you add members or a rule`));
+        },
+    }, {
+        name: "roles delete",
+        summary: "Delete a role",
+        usage: "roles delete <app> <key> --yes",
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const role = findRole(app, args.arg(1, "key"));
+            if (!args.bool("yes")) {
+                throw new CliError(`This deletes role "${role.key}" from ${app.id}; anyone holding it loses it on their next login.`, 6, "Re-run with --yes to confirm.");
+            }
+            await saveRoles(c, app.id, (app.roles ?? []).filter((r) => r.key !== role.key));
+            emit({ appId: app.id, deleted: role.key }, () => info(`✓ Deleted role "${role.key}" from ${app.id}`));
+        },
+    }, {
+        name: "roles add-member",
+        summary: "Grant a role to NetIDs directly",
+        usage: "roles add-member <app> <key> <netid>[,<netid>...]",
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const role = findRole(app, args.arg(1, "key"));
+            const toAdd = netids(args.arg(2, "netid"));
+            const members = [...new Set([...role.members, ...toAdd])];
+            await saveRoles(c, app.id, (app.roles ?? []).map((r) => (r.key === role.key ? { ...r, members } : r)));
+            emit({ appId: app.id, role: role.key, members, added: toAdd }, () => info(`✓ "${role.key}" members: ${members.join(", ")}`));
+        },
+    }, {
+        name: "roles remove-member",
+        summary: "Revoke a directly-granted role",
+        usage: "roles remove-member <app> <key> <netid>[,<netid>...]",
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const role = findRole(app, args.arg(1, "key"));
+            const toRemove = new Set(netids(args.arg(2, "netid")));
+            const members = role.members.filter((m) => !toRemove.has(m));
+            await saveRoles(c, app.id, (app.roles ?? []).map((r) => (r.key === role.key ? { ...r, members } : r)));
+            emit({ appId: app.id, role: role.key, members, removed: [...toRemove] }, () => {
+                info(`✓ "${role.key}" members: ${members.join(", ") || "(none)"}`);
+                if (role.rules.length > 0) {
+                    info("  note: attribute rules can still grant this role — see: coe roles show");
+                }
+            });
+        },
+    }, {
+        name: "roles add-rule",
+        summary: "Auto-grant a role to anyone whose login attributes match",
+        usage: 'roles add-rule <app> <key> <attribute> <operator> <value> | --rules-file <f.json>',
+        details: [
+            "Operators: equals, contains, startsWith, regex.",
+            'Example: coe roles add-rule myapp admin isMemberOf contains "gg-engr-admins"',
+            "A rule added this way has one condition. For multi-condition rules (ANDed),",
+            "pass --rules-file with a JSON array of { all: [{attribute,operator,value}] }.",
+        ],
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const role = findRole(app, args.arg(1, "key"));
+            let added;
+            const file = args.flag("rules-file");
+            if (file) {
+                let parsed;
+                try {
+                    parsed = JSON.parse(readFileSync(file, "utf8"));
+                }
+                catch (error) {
+                    throw new CliError(`Could not read ${file}: ${error instanceof Error ? error.message : String(error)}`, 6);
+                }
+                if (!Array.isArray(parsed)) {
+                    throw new CliError(`${file} must contain a JSON array of rules.`, 6);
+                }
+                added = parsed;
+            }
+            else {
+                const attribute = args.arg(2, "attribute");
+                const operator = args.arg(3, "operator");
+                const value = args.arg(4, "value");
+                if (!OPERATORS.includes(operator)) {
+                    throw new CliError(`"${operator}" isn't a valid operator.`, 6, `Use one of: ${OPERATORS.join(", ")}`);
+                }
+                const condition = { attribute, operator, value };
+                added = [{ all: [condition] }];
+            }
+            const rules = [...role.rules, ...added];
+            await saveRoles(c, app.id, (app.roles ?? []).map((r) => (r.key === role.key ? { ...r, rules } : r)));
+            emit({ appId: app.id, role: role.key, rules }, () => {
+                info(`✓ "${role.key}" now has ${rules.length} rule(s):`);
+                rules.forEach((rule, i) => info(`  [${i}] ${describeRule(rule)}`));
+            });
+        },
+    }, {
+        name: "roles remove-rule",
+        summary: "Remove a rule by its index (see roles show)",
+        usage: "roles remove-rule <app> <key> <index>",
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const role = findRole(app, args.arg(1, "key"));
+            const index = Number(args.arg(2, "index"));
+            if (!Number.isInteger(index) || index < 0 || index >= role.rules.length) {
+                throw new CliError(`"${role.key}" has no rule at index ${args.arg(2, "index")}.`, 6, role.rules.length > 0
+                    ? `Valid indexes: 0–${role.rules.length - 1}. See: coe roles show ${app.id} ${role.key}`
+                    : "That role has no rules.");
+            }
+            const rules = role.rules.filter((_, i) => i !== index);
+            await saveRoles(c, app.id, (app.roles ?? []).map((r) => (r.key === role.key ? { ...r, rules } : r)));
+            emit({ appId: app.id, role: role.key, rules }, () => info(`✓ Removed rule [${index}] from "${role.key}" (${rules.length} left)`));
+        },
+    });
+}

package/dist/index.js

@@ -6,6 +6,8 @@ import { registerAuthCommands } from "./commands/auth.js";
 import { registerDeployCommands } from "./commands/deploy.js";
 import { registerEnvCommands } from "./commands/env.js";
 import { registerPipelineCommands } from "./commands/pipelines.js";
+import { registerResourceCommands } from "./commands/resources.js";
+import { registerRoleCommands } from "./commands/roles.js";
 import { info, setJsonMode } from "./output.js";
 import { allCommands, findCommand, register } from "./registry.js";
 registerAuthCommands();
@@ -14,6 +16,8 @@ registerPipelineCommands();
 registerDeployCommands();
 registerAccessCommands();
 registerEnvCommands();
+registerResourceCommands();
+registerRoleCommands();
 function parseArgs(argv) {
     const positional = [];
     const flags = {};

package/dist/types.d.ts

@@ -30,13 +30,26 @@ export interface NamedPipeline {
     name: string;
     config: DeployConfig;
 }
+export type RoleOperator = "equals" | "contains" | "startsWith" | "regex";
 export interface RoleCondition {
     attribute: string;
-    operator: "equals" | "contains" | "startsWith" | "regex";
+    operator: RoleOperator;
     value: string;
 }
+/**
+ * A rule matches when ALL its conditions hold; a role is granted when ANY rule
+ * matches. The property is `all`, not `conditions` — the server reads `.all`
+ * and silently drops rules shaped any other way.
+ */
 export interface RoleRule {
-    conditions: RoleCondition[];
+    all: RoleCondition[];
+}
+export interface AppRole {
+    key: string;
+    label: string;
+    description?: string;
+    members: string[];
+    rules: RoleRule[];
 }
 export interface StaffAccess {
     everyone: boolean;
@@ -54,8 +67,14 @@ export interface RegisteredApp {
     url: string;
     repo?: string;
     branch?: string;
-    env: Record<string, string>;
+    /**
+     * Names of the app's env vars. Values are deliberately absent — read them
+     * with `coe env list --show`, so a secret only ever appears when it was
+     * asked for by name.
+     */
+    envKeys: string[];
     pipelines?: NamedPipeline[];
+    roles?: AppRole[];
     access?: AppAccess;
     createdAt: string;
     updatedAt: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uic-coe-connect/cli",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "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": {