requestshield 0.1.4 → 0.1.5

package/src/commands/agent-setup.mjs

@@ -1,185 +1,185 @@
-// @ts-check
-
-import { cp, lstat, mkdir, realpath, rename, rm, writeFile } from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { randomUUID } from "node:crypto";
-import { createInterface } from "node:readline/promises";
-import { CliError } from "../errors.mjs";
-import { detectAgents } from "../agent-detector.mjs";
-import { getAsset, isSea } from "node:sea";
-
-const skillAsset = "requestshield-skill.md";
-
-/**
- * @param {{ agent?: "codex" | "claude", force: boolean }} options
- * @param {{ env?: NodeJS.ProcessEnv, homeDir?: string, log: (message: string) => void, sourceDir?: string, executablePath?: string, detectAgents?: () => Promise<Array<"codex" | "claude">>, selectAgent?: (detected: Array<"codex" | "claude">) => Promise<"codex" | "claude"> }} deps
- */
-export async function setupAgent(options, deps) {
-  const agent = await resolveAgent(options.agent, deps);
-  const homeDir = deps.homeDir ?? os.homedir();
-
-  // Codex and Claude discover personal skills from different directories.
-  const skillsRoot = agent === "codex"
-    ? path.join(homeDir, ".agents", "skills")
-    : path.join(homeDir, ".claude", "skills");
-  const destination = path.join(skillsRoot, "requestshield");
-  await mkdir(skillsRoot, { recursive: true });
-
-  const exists = await pathExists(destination);
-  if (exists && !options.force) {
-    throw new CliError(`RequestShield skill already exists at ${destination}; use --force to replace it`, {
-      code: "SKILL_EXISTS",
-      exitCode: 2,
-    });
-  }
-
-  // Copy into a staging directory so an interrupted copy cannot leave a
-  // partially installed skill at the final destination.
-  const staging = path.join(skillsRoot, `.requestshield-${randomUUID()}.tmp`);
-  const backup = `${destination}.${randomUUID()}.backup`;
-  try {
-    if (deps.sourceDir) {
-      // Tests and alternate packagers can provide an explicit skill source.
-      await cp(deps.sourceDir, staging, {
-        recursive: true,
-        errorOnExist: true,
-      });
-    } else if (isSea()) {
-      // A single-executable build reads the skill from its embedded assets.
-      await mkdir(staging);
-
-      await writeFile(
-          path.join(staging, "SKILL.md"),
-          Buffer.from(getAsset(skillAsset)),
-      );
-    } else {
-      // Source, npm, and on-disk CJS builds keep the skill beside the program.
-      //
-      // src/main.mjs                 -> ../skills/requestshield
-      // dist/requestshield.cjs      -> ../skills/requestshield
-      // npm link and global npm installs expose a symlink in their bin folder.
-      // Follow it before resolving the adjacent packaged skills directory.
-      const executable = await realpath(deps.executablePath ?? process.argv[1]);
-      const executableDir = path.dirname(executable);
-      const source = path.resolve(
-          executableDir,
-          "../skills/requestshield",
-      );
-
-      await cp(source, staging, {
-        recursive: true,
-        errorOnExist: true,
-      });
-    }
-
-    // Keep the old installation recoverable until the staged copy is in place.
-    if (exists) await rename(destination, backup);
-    await rename(staging, destination);
-    if (exists) await rm(backup, { recursive: true, force: true });
-  } catch (error) {
-    await rm(staging, { recursive: true, force: true });
-    if (await pathExists(backup)) {
-      await rm(destination, { recursive: true, force: true });
-      await rename(backup, destination);
-    }
-    throw error;
-  }
-  const agentLabel = agent === "codex" ? "Codex" : "Claude";
-  deps.log(`Installed RequestShield skill for ${agentLabel} at ${destination}`);
-  deps.log(`Restart ${agentLabel} or start a new task before using the skill.`);
-}
-
-/**
- * Explicit selection bypasses detection. Automatic setup selects a single
- * detected agent or asks the user when both agents are present.
- *
- * @param {"codex" | "claude" | undefined} requested
- * @param {{ env?: NodeJS.ProcessEnv, homeDir?: string, detectAgents?: () => Promise<Array<"codex" | "claude">>, selectAgent?: (detected: Array<"codex" | "claude">) => Promise<"codex" | "claude"> }} deps
- * @returns {Promise<"codex" | "claude">}
- */
-async function resolveAgent(requested, deps) {
-  // A command-line choice is authoritative and avoids probing the machine.
-  if (requested) return requested;
-
-  const detected = deps.detectAgents
-    ? await deps.detectAgents()
-    : await detectAgents({ env: deps.env, homeDir: deps.homeDir });
-
-  if (detected.length === 1) return detected[0];
-  if (detected.length === 0) {
-    throw new CliError(
-      [
-        "No supported coding agent detected.",
-        "",
-        "Choose one explicitly:",
-        "  requestshield agent setup --codex",
-        "  requestshield agent setup --claude",
-      ].join("\n"),
-      { code: "AGENT_NOT_FOUND", exitCode: 2 },
-    );
-  }
-
-  // Never choose silently when both agents are present. Interactive users get
-  // a prompt; non-interactive callers receive a stable conflict error.
-  const selectAgent = deps.selectAgent ?? promptForAgent;
-  const selected = await selectAgent(detected);
-  if (!detected.includes(selected)) {
-    throw new CliError(`Selected agent is not available: ${selected}`, {
-      code: "INVALID_AGENT",
-      exitCode: 2,
-    });
-  }
-  return selected;
-}
-
-/**
- * Ask an interactive user which detected agent should receive the skill.
- *
- * @returns {Promise<"codex" | "claude">}
- */
-async function promptForAgent() {
-  if (process.stdin.isTTY !== true || process.stdout.isTTY !== true) {
-    throw new CliError(
-      [
-        "Multiple coding agents detected.",
-        "",
-        "Choose one explicitly:",
-        "  requestshield agent setup --codex",
-        "  requestshield agent setup --claude",
-      ].join("\n"),
-      { code: "INSTALL_CONFLICT", exitCode: 2 },
-    );
-  }
-
-  const prompt = createInterface({
-    input: process.stdin,
-    output: process.stdout,
-  });
-  try {
-    process.stdout.write(
-      "Multiple coding agents detected.\n\n  1. Codex\n  2. Claude\n\n",
-    );
-    while (true) {
-      const answer = (await prompt.question("Select an agent [1-2]: "))
-        .trim()
-        .toLowerCase();
-      if (answer === "1" || answer === "codex") return "codex";
-      if (answer === "2" || answer === "claude") return "claude";
-      process.stdout.write("Enter 1 for Codex or 2 for Claude.\n");
-    }
-  } finally {
-    prompt.close();
-  }
-}
-
-/** @param {string} target */
-async function pathExists(target) {
-  try {
-    await lstat(target);
-    return true;
-  } catch (error) {
-    if (/** @type {NodeJS.ErrnoException} */ (error).code === "ENOENT") return false;
-    throw error;
-  }
-}
+// @ts-check
+
+import { cp, lstat, mkdir, realpath, rename, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { createInterface } from "node:readline/promises";
+import { CliError } from "../errors.mjs";
+import { detectAgents } from "../agent-detector.mjs";
+import { getAsset, isSea } from "node:sea";
+
+const skillAsset = "requestshield-skill.md";
+
+/**
+ * @param {{ agent?: "codex" | "claude", force: boolean }} options
+ * @param {{ env?: NodeJS.ProcessEnv, homeDir?: string, log: (message: string) => void, sourceDir?: string, executablePath?: string, detectAgents?: () => Promise<Array<"codex" | "claude">>, selectAgent?: (detected: Array<"codex" | "claude">) => Promise<"codex" | "claude"> }} deps
+ */
+export async function setupAgent(options, deps) {
+  const agent = await resolveAgent(options.agent, deps);
+  const homeDir = deps.homeDir ?? os.homedir();
+
+  // Codex and Claude discover personal skills from different directories.
+  const skillsRoot = agent === "codex"
+    ? path.join(homeDir, ".agents", "skills")
+    : path.join(homeDir, ".claude", "skills");
+  const destination = path.join(skillsRoot, "requestshield");
+  await mkdir(skillsRoot, { recursive: true });
+
+  const exists = await pathExists(destination);
+  if (exists && !options.force) {
+    throw new CliError(`RequestShield skill already exists at ${destination}; use --force to replace it`, {
+      code: "SKILL_EXISTS",
+      exitCode: 2,
+    });
+  }
+
+  // Copy into a staging directory so an interrupted copy cannot leave a
+  // partially installed skill at the final destination.
+  const staging = path.join(skillsRoot, `.requestshield-${randomUUID()}.tmp`);
+  const backup = `${destination}.${randomUUID()}.backup`;
+  try {
+    if (deps.sourceDir) {
+      // Tests and alternate packagers can provide an explicit skill source.
+      await cp(deps.sourceDir, staging, {
+        recursive: true,
+        errorOnExist: true,
+      });
+    } else if (isSea()) {
+      // A single-executable build reads the skill from its embedded assets.
+      await mkdir(staging);
+
+      await writeFile(
+          path.join(staging, "SKILL.md"),
+          Buffer.from(getAsset(skillAsset)),
+      );
+    } else {
+      // Source, npm, and on-disk CJS builds keep the skill beside the program.
+      //
+      // src/main.mjs                 -> ../skills/requestshield
+      // dist/requestshield.cjs      -> ../skills/requestshield
+      // npm link and global npm installs expose a symlink in their bin folder.
+      // Follow it before resolving the adjacent packaged skills directory.
+      const executable = await realpath(deps.executablePath ?? process.argv[1]);
+      const executableDir = path.dirname(executable);
+      const source = path.resolve(
+          executableDir,
+          "../skills/requestshield",
+      );
+
+      await cp(source, staging, {
+        recursive: true,
+        errorOnExist: true,
+      });
+    }
+
+    // Keep the old installation recoverable until the staged copy is in place.
+    if (exists) await rename(destination, backup);
+    await rename(staging, destination);
+    if (exists) await rm(backup, { recursive: true, force: true });
+  } catch (error) {
+    await rm(staging, { recursive: true, force: true });
+    if (await pathExists(backup)) {
+      await rm(destination, { recursive: true, force: true });
+      await rename(backup, destination);
+    }
+    throw error;
+  }
+  const agentLabel = agent === "codex" ? "Codex" : "Claude";
+  deps.log(`Installed RequestShield skill for ${agentLabel} at ${destination}`);
+  deps.log(`Restart ${agentLabel} or start a new task before using the skill.`);
+}
+
+/**
+ * Explicit selection bypasses detection. Automatic setup selects a single
+ * detected agent or asks the user when both agents are present.
+ *
+ * @param {"codex" | "claude" | undefined} requested
+ * @param {{ env?: NodeJS.ProcessEnv, homeDir?: string, detectAgents?: () => Promise<Array<"codex" | "claude">>, selectAgent?: (detected: Array<"codex" | "claude">) => Promise<"codex" | "claude"> }} deps
+ * @returns {Promise<"codex" | "claude">}
+ */
+async function resolveAgent(requested, deps) {
+  // A command-line choice is authoritative and avoids probing the machine.
+  if (requested) return requested;
+
+  const detected = deps.detectAgents
+    ? await deps.detectAgents()
+    : await detectAgents({ env: deps.env, homeDir: deps.homeDir });
+
+  if (detected.length === 1) return detected[0];
+  if (detected.length === 0) {
+    throw new CliError(
+      [
+        "No supported coding agent detected.",
+        "",
+        "Choose one explicitly:",
+        "  requestshield agent setup --codex",
+        "  requestshield agent setup --claude",
+      ].join("\n"),
+      { code: "AGENT_NOT_FOUND", exitCode: 2 },
+    );
+  }
+
+  // Never choose silently when both agents are present. Interactive users get
+  // a prompt; non-interactive callers receive a stable conflict error.
+  const selectAgent = deps.selectAgent ?? promptForAgent;
+  const selected = await selectAgent(detected);
+  if (!detected.includes(selected)) {
+    throw new CliError(`Selected agent is not available: ${selected}`, {
+      code: "INVALID_AGENT",
+      exitCode: 2,
+    });
+  }
+  return selected;
+}
+
+/**
+ * Ask an interactive user which detected agent should receive the skill.
+ *
+ * @returns {Promise<"codex" | "claude">}
+ */
+async function promptForAgent() {
+  if (process.stdin.isTTY !== true || process.stdout.isTTY !== true) {
+    throw new CliError(
+      [
+        "Multiple coding agents detected.",
+        "",
+        "Choose one explicitly:",
+        "  requestshield agent setup --codex",
+        "  requestshield agent setup --claude",
+      ].join("\n"),
+      { code: "INSTALL_CONFLICT", exitCode: 2 },
+    );
+  }
+
+  const prompt = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  try {
+    process.stdout.write(
+      "Multiple coding agents detected.\n\n  1. Codex\n  2. Claude\n\n",
+    );
+    while (true) {
+      const answer = (await prompt.question("Select an agent [1-2]: "))
+        .trim()
+        .toLowerCase();
+      if (answer === "1" || answer === "codex") return "codex";
+      if (answer === "2" || answer === "claude") return "claude";
+      process.stdout.write("Enter 1 for Codex or 2 for Claude.\n");
+    }
+  } finally {
+    prompt.close();
+  }
+}
+
+/** @param {string} target */
+async function pathExists(target) {
+  try {
+    await lstat(target);
+    return true;
+  } catch (error) {
+    if (/** @type {NodeJS.ErrnoException} */ (error).code === "ENOENT") return false;
+    throw error;
+  }
+}

package/src/commands/apps-get.mjs

@@ -0,0 +1,64 @@
+// @ts-check
+
+import { CliError } from "../errors.mjs";
+import { objectString } from "../api-client.mjs";
+
+const APPLICATION_STATUSES = new Set(["ready", "active", "deactivated"]);
+
+/**
+ * @param {{ appKey: string }} options
+ * @param {{ api: { getApp(accessToken: string, appKey: string): Promise<{body: unknown}> }, sessions: { loadToken(): Promise<string> }, log: (message: string) => void }} deps
+ */
+export async function getApp(options, deps) {
+  const accessToken =
+    await deps.sessions.loadToken();
+  
+  const result =
+    await deps.api.getApp(accessToken, options.appKey);
+  
+  const app =
+    parseApp(result.body, options.appKey);
+  
+  deps.log(JSON.stringify({ ok: true, data: app }, null, 2));
+}
+
+/** @param {unknown} body @param {string} requestedAppKey */
+function parseApp(body, requestedAppKey) {
+  const ok = body && typeof body === "object" ?
+    Reflect.get(body, "ok") : undefined;
+  
+  const data = body && typeof body === "object" ?
+    Reflect.get(body, "data") : undefined;
+  
+  if (ok !== true || !data || typeof data !== "object" || Array.isArray(data)) {
+    throw invalidResponse(
+      "The application response did not contain ok=true and data"
+    );
+  }
+
+  const appKey = objectString(data, "app_key");
+  const appName = objectString(data, "name");
+  const status = objectString(data, "status");
+
+  if (appKey !== requestedAppKey) {
+    throw invalidResponse("The application response did not match the requested App Key");
+  }
+
+  if (!appName) {
+    throw invalidResponse("The application response did not contain name");
+  }
+
+  if (!status || !APPLICATION_STATUSES.has(status)) {
+    throw invalidResponse(
+      "The application response status must be ready, active, or deactivated",
+    );
+  }
+
+  // Construct a new object so unexpected response fields, especially secrets, cannot be printed.
+  return { app_key: appKey, name: appName, status };
+}
+
+/** @param {string} message */
+function invalidResponse(message) {
+  return new CliError(message, { code: "INVALID_RESPONSE" });
+}

package/src/commands/apps-list.mjs

@@ -0,0 +1,90 @@
+// @ts-check
+
+import { CliError } from "../errors.mjs";
+import { objectString } from "../api-client.mjs";
+
+const HEADERS = ["APP KEY", "NAME", "STATUS"];
+
+/** @typedef {{ appKey: string, name: string, status: string, createdAt: string, updatedAt: string }} App */
+
+/**
+ * @param {{ json: boolean }} options
+ * @param {{ api: { listApps(accessToken: string): Promise<{body: unknown}> }, sessions: { loadToken(): Promise<string> }, log: (message: string) => void }} deps
+ */
+export async function listApps(options, deps) {
+  const accessToken =
+    await deps.sessions.loadToken();
+  
+  const result =
+    await deps.api.listApps(accessToken);
+  
+  const { data: apps, nextCursor } = parseApps(result.body);
+
+  if (options.json) {
+    deps.log(JSON.stringify({ data: apps, nextCursor }, null, 2));
+    return;
+  }
+
+  if (apps.length === 0) {
+    deps.log("No applications are available to this account.");
+    return;
+  }
+
+  for (const line of formatTable(apps)) deps.log(line);
+}
+
+/** @param {unknown} body @returns {{ data: App[], nextCursor: string | null }} */
+function parseApps(body) {
+  const data = body && typeof body === "object" ?
+    Reflect.get(body, "data") : undefined;
+
+  const nextCursor = body && typeof body === "object" ?
+    Reflect.get(body, "nextCursor") : undefined;
+
+  if (!Array.isArray(data)) {
+    throw new CliError("The applications response did not contain a data array", {
+      code: "INVALID_RESPONSE",
+    });
+  }
+
+  if (nextCursor !== null && (typeof nextCursor !== "string" || nextCursor.length === 0)) {
+    throw new CliError("The applications response contained an invalid nextCursor", {
+      code: "INVALID_RESPONSE",
+    });
+  }
+
+  // Rebuild every item from approved metadata so unexpected API fields never reach output.
+  const apps = data.map((entry, index) => {
+    const appKey = objectString(entry, "appKey");
+    const name = objectString(entry, "name");
+    const status = objectString(entry, "status");
+    const createdAt = objectString(entry, "createdAt");
+    const updatedAt = objectString(entry, "updatedAt");
+
+    if (!appKey || !name || !status || !createdAt || !updatedAt) {
+      throw new CliError(
+        `Application at position ${index + 1} is missing appKey, name, status, createdAt, or updatedAt`,
+        { code: "INVALID_RESPONSE" },
+      );
+    }
+
+    return { appKey, name, status, createdAt, updatedAt };
+  });
+
+  return { data: apps, nextCursor };
+}
+
+/** @param {App[]} apps @returns {string[]} */
+function formatTable(apps) {
+  const rows = [HEADERS, ...apps.map((app) =>
+    [app.appKey, app.name, app.status])];
+  
+  const widths = HEADERS.map((_, column) =>
+    Math.max(...rows.map((row) => row[column].length)));
+  
+  return rows.map((row) =>
+    row
+      .map((cell, column) => (column === HEADERS.length - 1 ? cell : cell.padEnd(widths[column])))
+      .join("  "),
+  );
+}

package/src/commands/billing-get.mjs

@@ -0,0 +1,110 @@
+// @ts-check
+
+import { CliError } from "../errors.mjs";
+import { objectString } from "../api-client.mjs";
+
+/**
+ * @param {{ appKey: string }} options
+ * @param {{ api: { getBilling(accessToken: string, appKey: string): Promise<{body: unknown}> }, sessions: { loadToken(): Promise<string> }, log: (message: string) => void }} deps
+ */
+export async function showBilling(options, deps) {
+  const accessToken =
+    await deps.sessions.loadToken();
+  
+  const result =
+    await deps.api.getBilling(accessToken, options.appKey);
+  
+  const billing = parseBilling(result.body);
+
+  deps.log(JSON.stringify({ ok: true, data: billing }, null, 2));
+}
+
+/** @param {unknown} body */
+function parseBilling(body) {
+  const ok = body && typeof body === "object" ?
+    Reflect.get(body, "ok") : undefined;
+  
+  const data = objectValue(body, "data");
+
+  const plan = objectValue(data, "plan");
+
+  const usage = objectValue(data, "usage");
+
+  if (ok !== true || !data || !plan || !usage) {
+    throw invalidResponse("The billing response did not contain ok=true, data.plan, and data.usage");
+  }
+
+  const tier = objectString(plan, "tier");
+  const currentCycle = Reflect.get(plan, "current_cycle");
+  const billing = Reflect.get(plan, "billing");
+  const nextCharge = objectString(plan, "next_charge");
+  const monthlyQuota = Reflect.get(usage, "monthly_quota");
+  const currentUsage = Reflect.get(usage, "current_usage");
+  const overageCharge = Reflect.get(usage, "overage_charge");
+
+  if (!tier) throw invalidResponse("The billing response did not contain plan.tier");
+  if (
+    !Array.isArray(currentCycle)
+    || currentCycle.length !== 2
+    || !currentCycle.every((value) =>
+      typeof value === "string" && isIsoDateTime(value))
+    || Date.parse(currentCycle[0]) > Date.parse(currentCycle[1])
+  ) {
+    throw invalidResponse("The billing response contained an invalid plan.current_cycle");
+  }
+  if (!nonNegativeNumber(billing)) {
+    throw invalidResponse("The billing response contained an invalid plan.billing");
+  }
+  if (!nextCharge || !isIsoDateTime(nextCharge)) {
+    throw invalidResponse("The billing response contained an invalid plan.next_charge");
+  }
+  if (!nonNegativeInteger(monthlyQuota) || !nonNegativeInteger(currentUsage)) {
+    throw invalidResponse("The billing response contained invalid quota or usage values");
+  }
+  if (!nonNegativeNumber(overageCharge)) {
+    throw invalidResponse("The billing response contained an invalid usage.overage_charge");
+  }
+
+  // Rebuild nested output so unexpected response fields cannot reach the terminal.
+  return {
+    plan: {
+      tier,
+      current_cycle: currentCycle,
+      billing,
+      next_charge: nextCharge,
+    },
+    usage: {
+      monthly_quota: monthlyQuota,
+      current_usage: currentUsage,
+      overage_charge: overageCharge,
+    },
+  };
+}
+
+/** @param {unknown} value @param {string} property */
+function objectValue(value, property) {
+  if (!value || typeof value !== "object") return undefined;
+  const found = Reflect.get(value, property);
+  return found && typeof found === "object" && !Array.isArray(found) ? found : undefined;
+}
+
+/** @param {unknown} value */
+function nonNegativeNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+/** @param {unknown} value */
+function nonNegativeInteger(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+
+/** @param {string} value */
+function isIsoDateTime(value) {
+  return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})?$/.test(value)
+    && Number.isFinite(Date.parse(value));
+}
+
+/** @param {string} message */
+function invalidResponse(message) {
+  return new CliError(message, { code: "INVALID_RESPONSE" });
+}