@uic-coe-connect/cli 0.2.1 → 0.3.1

package/dist/commands/deploy.js

@@ -5,6 +5,12 @@ import { resolveApp } from "./apps.js";
 /** Sentinels the deploy stream ends with — the server's own success signal. */
 const OK = "__DEPLOY_OK__";
 const FAILED = "__DEPLOY_FAILED__";
+/**
+ * Machine markers the server interleaves for the web UI's pipeline diagram.
+ * They're meaningless here and read as debug noise, so they never reach the
+ * console or the JSON log — the stream already carries a human line for each.
+ */
+const MARKER = /^__(NODE|COMMIT)__:/;
 export function registerDeployCommands() {
     register({
         name: "deploy",
@@ -49,11 +55,19 @@ export function registerDeployCommands() {
             info(`Deploying ${app.id} · pipeline "${chosen.name}"${branch ? ` · branch ${branch}` : ""}`);
             const lines = [];
             const sentinels = [];
+            let commit;
             await c.stream("POST", `/registered-apps/${app.id}/deploy`, body, (line) => {
                 if (line === OK || line === FAILED) {
                     sentinels.push(line);
                     return;
                 }
+                if (MARKER.test(line)) {
+                    // Keep the one piece of information a marker carries that the
+                    // human stream doesn't structure: which commit got deployed.
+                    if (line.startsWith("__COMMIT__:"))
+                        commit = line.split(":")[1];
+                    return;
+                }
                 lines.push(line);
                 // In JSON mode the log is part of the final payload instead, so stdout
                 // stays parseable; progress still shows on stderr.
@@ -70,7 +84,7 @@ export function registerDeployCommands() {
                 : sentinels.includes(FAILED)
                     ? "failed"
                     : "unknown";
-            emit({ appId: app.id, pipeline: chosen.name, status: outcome, log: lines }, () => {
+            emit({ appId: app.id, pipeline: chosen.name, status: outcome, commit, log: lines }, () => {
                 info(outcome === "ok" ? `\n✓ Deploy succeeded` : `\n✗ Deploy ${outcome}`);
             });
             // A stream that ended without a sentinel means the connection dropped

package/dist/commands/logs.d.ts

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

package/dist/commands/logs.js

@@ -0,0 +1,79 @@
+import { CliError } from "../client.js";
+import { emit, info } from "../output.js";
+import { register } from "../registry.js";
+import { resolveApp } from "./apps.js";
+const FOLLOW_INTERVAL_MS = 2_000;
+export function registerLogCommands() {
+    register({
+        name: "logs",
+        summary: "Read an app's pm2 logs (why it crashed, what it printed)",
+        usage: "logs <app> [--out] [--tail <n>] [--follow]",
+        details: [
+            "Defaults to the error log — that's where a startup crash lands.",
+            "  --out       stdout instead of stderr",
+            "  --tail <n>  how many lines (default 100, max 2000)",
+            "  --follow    keep polling and print new lines until Ctrl-C",
+            "",
+            "These are root's pm2 logs on the VM, which you otherwise can't read",
+            "without SSH. If a deploy just failed a health check it already printed",
+            "the tail inline — this is for looking further back.",
+        ],
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const stream = args.bool("out") ? "out" : "err";
+            const tail = Number(args.flag("tail") ?? 100);
+            if (!Number.isFinite(tail) || tail < 1) {
+                throw new CliError(`--tail must be a positive number, got "${args.flag("tail")}".`, 6);
+            }
+            const path = `/registered-apps/${app.id}/logs?stream=${stream}&lines=${Math.min(tail, 2000)}`;
+            const fetchLogs = () => c.request("GET", path);
+            const first = await fetchLogs();
+            if (first.logs.length === 0) {
+                emit(first, () => {
+                    info(first.note ?? `No pm2 process found for ${app.id}.`);
+                    info("  Deploy it first, or check the pipeline's pm2 step names.");
+                });
+                return;
+            }
+            if (args.bool("json")) {
+                emit(first, () => undefined);
+                return;
+            }
+            const render = (block, lines) => {
+                for (const line of lines) {
+                    info(first.logs.length > 1 ? `[${block.process}] ${line}` : line);
+                }
+            };
+            for (const block of first.logs) {
+                info(`── ${block.process} (${block.status}, ${block.restarts} restarts) · ${stream === "out" ? "stdout" : "stderr"} ──`);
+                if (block.lines.length === 0) {
+                    info("  (empty)");
+                }
+                else {
+                    render(block, block.lines);
+                }
+            }
+            if (!args.bool("follow"))
+                return;
+            // Poll rather than hold a connection open: a deploy can restart the app
+            // (and rotate the file) underneath us, and re-reading the tail each time
+            // survives that where a held stream wouldn't.
+            const seen = new Map(first.logs.map((b) => [b.process, b.lines.at(-1)]));
+            info("── following (Ctrl-C to stop) ──");
+            for (;;) {
+                await new Promise((resolve) => setTimeout(resolve, FOLLOW_INTERVAL_MS));
+                const next = await fetchLogs();
+                for (const block of next.logs) {
+                    const last = seen.get(block.process);
+                    const index = last === undefined ? -1 : block.lines.lastIndexOf(last);
+                    const fresh = index >= 0 ? block.lines.slice(index + 1) : block.lines;
+                    if (fresh.length > 0) {
+                        render(block, fresh);
+                        seen.set(block.process, fresh.at(-1));
+                    }
+                }
+            }
+        },
+    });
+}

package/dist/commands/pipelines.js

@@ -7,7 +7,7 @@ import { resolveApp } from "./apps.js";
  * Steps are written as a compact `type:arg` list so a pipeline can be created
  * in one command instead of hand-authoring JSON:
  *
- *   pull  scan  npm:ci@backend  npm:build@backend  migrate:backend  chown  pm2:restart@my-api
+ *   pull  scan  env:backend  npm:ci@backend  migrate:backend  chown  pm2:restart@my-api
  *
  * `--steps-file` takes the raw JSON array instead, for anything this shorthand
  * can't express.
@@ -22,6 +22,8 @@ function parseStep(token) {
             return { type: "scan" };
         case "chown":
             return { type: "chown" };
+        case "env":
+            return { type: "env", subdir: arg || subdir || undefined };
         case "npm":
             if (!arg)
                 throw new CliError(`npm step needs a script: npm:ci or npm:build@subdir`, 6);
@@ -33,7 +35,7 @@ function parseStep(token) {
                 throw new CliError(`pm2 step needs an action: pm2:restart@process-name`, 6);
             return { type: "pm2", action: arg, process: subdir || undefined };
         default:
-            throw new CliError(`Unknown step "${token}".`, 6, "Valid: pull, scan, chown, npm:<script>[@subdir], migrate[:subdir], pm2:<action>[@process]");
+            throw new CliError(`Unknown step "${token}".`, 6, "Valid: pull, scan, env[:subdir], chown, npm:<script>[@subdir], migrate[:subdir], pm2:<action>[@process]");
     }
 }
 function describeStep(step) {
@@ -42,6 +44,8 @@ function describeStep(step) {
             return `npm ${step.script}${step.subdir ? ` (${step.subdir})` : ""}`;
         case "migrate":
             return `migrate${step.subdir ? ` (${step.subdir})` : ""}`;
+        case "env":
+            return `write .env${step.subdir ? ` (${step.subdir})` : ""}`;
         case "pm2":
             return `pm2 ${step.action}${step.process ? ` ${step.process}` : ""}`;
         default:
@@ -114,7 +118,7 @@ export function registerPipelineCommands() {
         summary: "Create a pipeline from a step list",
         usage: 'pipelines create <app> --name "Full deploy" <step>... | --steps-file <f.json>',
         details: [
-            "Steps: pull, scan, chown, npm:<script>[@subdir], migrate[:subdir], pm2:<action>[@process]",
+            "Steps: pull, scan, env[:subdir], chown, npm:<script>[@subdir], migrate[:subdir], pm2:<action>[@process]",
             'Example: coe pipelines create myapp --name "Full" pull scan npm:ci@backend pm2:restart@myapp-api',
         ],
         async run({ args, client }) {

package/dist/commands/roles.js

@@ -184,6 +184,75 @@ export function registerRoleCommands() {
                 rules.forEach((rule, i) => info(`  [${i}] ${describeRule(rule)}`));
             });
         },
+    }, {
+        name: "roles token",
+        summary: "Show, issue, or rotate the app's role-resolve token",
+        usage: "roles token <app> [--issue | --rotate | --revoke]",
+        details: [
+            "The token your app puts in COE_ROLES_TOKEN so the SDK can resolve roles.",
+            "It is stored hashed and shown ONCE, at issue — there is no way to read it",
+            "back later. Lost it? Rotate and update the app's env.",
+            "",
+            "  coe roles token myapp --issue      # first time",
+            "  coe roles token myapp --rotate     # replace a live one",
+            "",
+            "Then: coe env set myapp COE_ROLES_TOKEN=<value>, and deploy.",
+        ],
+        async run({ args, client }) {
+            const c = client();
+            const app = await resolveApp(c, args.arg(0, "app"));
+            const path = `/registered-apps/${app.id}/roles/token`;
+            if (args.bool("revoke")) {
+                await c.request("DELETE", path);
+                emit({ appId: app.id, revoked: true }, () => {
+                    info(`✓ Revoked ${app.id}'s roles token`);
+                    info("  Role resolution now fails for this app until you issue a new one,");
+                    info("  and users sign in with rolesResolved: false.");
+                });
+                return;
+            }
+            const issuing = args.bool("issue") || args.bool("rotate");
+            if (!issuing) {
+                const { token } = await c.request("GET", path);
+                emit({ appId: app.id, token }, () => {
+                    if (!token) {
+                        info(`${app.id} has no roles token.`);
+                        info(`  Issue one with: coe roles token ${app.id} --issue`);
+                        return;
+                    }
+                    details([
+                        ["App", app.id],
+                        ["Token", `${token.prefix}… (stored hashed; issue a new one to see a value)`],
+                        ["Created", `${new Date(token.createdAt).toLocaleString()} by ${token.createdBy}`],
+                        [
+                            "Last used",
+                            token.lastUsedAt
+                                ? new Date(token.lastUsedAt).toLocaleString()
+                                : "never — the app hasn't resolved a role yet",
+                        ],
+                    ]);
+                });
+                return;
+            }
+            // Rotating invalidates the value the deployed app is holding, so it
+            // can't be something you do by reaching for the wrong flag.
+            const existing = await c.request("GET", path);
+            if (existing.token && !args.bool("rotate")) {
+                throw new CliError(`${app.id} already has a roles token (${existing.token.prefix}…).`, 6, "Re-run with --rotate to replace it. The deployed app will fail to resolve roles until you update COE_ROLES_TOKEN and redeploy.");
+            }
+            const result = await c.request("POST", path);
+            emit(result, () => {
+                info(`✓ ${result.rotated ? "Rotated" : "Issued"} ${app.id}'s roles token`);
+                info("");
+                info(`  ${result.token}`);
+                info("");
+                info("  This is the only time it is shown. Store it now:");
+                info(`    coe env set ${app.id} COE_ROLES_TOKEN=${result.token}`);
+                if (result.rotated) {
+                    info("  The previous token stopped working immediately — deploy to pick this one up.");
+                }
+            });
+        },
     }, {
         name: "roles remove-rule",
         summary: "Remove a rule by its index (see roles show)",

package/dist/index.js

@@ -5,6 +5,7 @@ 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 { registerLogCommands } from "./commands/logs.js";
 import { registerPipelineCommands } from "./commands/pipelines.js";
 import { registerResourceCommands } from "./commands/resources.js";
 import { registerRoleCommands } from "./commands/roles.js";
@@ -18,6 +19,7 @@ registerAccessCommands();
 registerEnvCommands();
 registerResourceCommands();
 registerRoleCommands();
+registerLogCommands();
 function parseArgs(argv) {
     const positional = [];
     const flags = {};

package/dist/types.d.ts

@@ -12,6 +12,9 @@ export type DeployStep = {
     type: "npm";
     script: string;
     subdir?: string;
+} | {
+    type: "env";
+    subdir?: string;
 } | {
     type: "migrate";
     subdir?: string;
@@ -61,6 +64,15 @@ export interface AppAccess {
     devTeam: string[];
     staff: StaffAccess;
 }
+/** An app's role-resolve token, minus anything that could reconstruct it. */
+export interface RolesTokenInfo {
+    appId: string;
+    /** Leading characters only — enough to recognise which token is deployed. */
+    prefix: string;
+    createdAt: string;
+    createdBy: string;
+    lastUsedAt?: string;
+}
 export interface RegisteredApp {
     id: string;
     name: string;

package/package.json

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