biaws 0.1.0

package/src/compatibilityCommands.js

@@ -0,0 +1,107 @@
+import { Args, Flags, Help } from "@oclif/core";
+
+import { AuthenticatedApiCommand, ProjectCommand } from "./baseCommands.js";
+import {
+  configureContextFlags,
+  configureContextInput,
+  legacyAgentContext,
+} from "./configure/command.js";
+import { runAgentCommand } from "./commands/agent.js";
+import { runMonitoringCommand } from "./commands/monitoring.js";
+import { runSkillsCommand } from "./commands/skills.js";
+
+export const authenticatedFlags = Object.freeze({
+  "api-key": Flags.string({
+    description: "chave da API (prefira ISSUE_API_KEY ou --env-file)",
+  }),
+  "api-url": Flags.string({ description: "URL da API do Bondia Workspaces" }),
+  "env-file": Flags.string({ description: "arquivo privado com URL e chave" }),
+  workspace: Flags.string({ char: "w", description: "workspace da operação" }),
+  json: Flags.boolean({ description: "emite somente JSON em stdout" }),
+});
+
+function authenticatedInput(flags) {
+  return {
+    apiKey: flags["api-key"],
+    apiUrl: flags["api-url"],
+    envFile: flags["env-file"],
+    workspace: flags.workspace,
+  };
+}
+
+export function createSkillsCommand(action, definition = {}) {
+  return class SkillsAction extends AuthenticatedApiCommand {
+    static description = definition.description;
+    static args = definition.args || {};
+    static flags = { ...authenticatedFlags, ...(definition.flags || {}) };
+
+    async run() {
+      const { args, flags } = await this.parse(this.constructor);
+      const context = await this.authenticatedContext(
+        authenticatedInput(flags),
+      );
+      const positional = definition.positional
+        ? definition.positional(args)
+        : [];
+      await runSkillsCommand(context.api, action, positional, flags);
+    }
+  };
+}
+
+export function createMonitoringCommand(action, definition = {}) {
+  return class MonitoringAction extends AuthenticatedApiCommand {
+    static description = definition.description;
+    static args = definition.args || {};
+    static flags = { ...authenticatedFlags, ...(definition.flags || {}) };
+
+    async run() {
+      const { args, flags } = await this.parse(this.constructor);
+      const context = await this.authenticatedContext(
+        authenticatedInput(flags),
+      );
+      const positional = definition.positional
+        ? definition.positional(args)
+        : [];
+      await runMonitoringCommand(context.api, action, positional, flags);
+    }
+  };
+}
+
+export function createAgentCommand(action) {
+  return class AgentAction extends ProjectCommand {
+    static description = `${action === "configure" ? "configura" : "diagnostica"} Codex ou Claude (alias legado)`;
+    static args = {
+      client: Args.string({
+        description: "cliente de agente",
+        options: ["codex", "claude"],
+        required: true,
+      }),
+    };
+    static flags = configureContextFlags;
+
+    async run() {
+      const { args, flags } = await this.parse(this.constructor);
+      const context = await this.projectContext(configureContextInput(flags));
+      await runAgentCommand(
+        context.api,
+        action,
+        [args.client],
+        { ...flags, project: context.projectDirectory },
+        legacyAgentContext(context),
+      );
+    }
+  };
+}
+
+export async function showTopic(command, topic) {
+  await command.parse(command.constructor);
+  await new Help(command.config).showHelp([topic]);
+}
+
+export const optionalSkillArgument = Args.string({
+  description: "ID da skill",
+});
+export const runtimeArgument = Args.string({
+  description: "UUID ou caminho aplicação.componente.deployment.runtime",
+  required: true,
+});

package/src/configure/command.js

@@ -0,0 +1,50 @@
+import path from "node:path";
+
+import { Args, Flags } from "@oclif/core";
+
+export const configureContextFlags = Object.freeze({
+  project: Flags.string({
+    char: "p",
+    description: "diretório do projeto a configurar",
+  }),
+  workspace: Flags.string({
+    char: "w",
+    description: "workspace associado ao projeto",
+  }),
+  "api-url": Flags.string({ description: "URL da API do Bondia Workspaces" }),
+  "env-file": Flags.string({
+    description: "arquivo privado com URL e chave da API",
+  }),
+  force: Flags.boolean({
+    char: "f",
+    description: "substitui somente a configuração BIAWS conflitante",
+  }),
+  json: Flags.boolean({ description: "emite somente JSON em stdout" }),
+});
+
+export const clientArgument = Args.string({
+  description: "cliente a diagnosticar",
+  options: ["codex", "claude"],
+  required: false,
+});
+
+export function configureContextInput(flags) {
+  return {
+    apiUrl: flags["api-url"],
+    envFile: flags["env-file"],
+    project: flags.project,
+    workspace: flags.workspace,
+  };
+}
+
+export function legacyAgentContext(context) {
+  return {
+    apiKey: context.apiKey,
+    apiUrl: context.apiUrl,
+    envFile: context.envFile,
+    toolDirectory: context.repositoryRoot
+      ? path.join(context.repositoryRoot, "biaws-cli")
+      : context.toolDirectory,
+    workspaceId: context.workspaceId,
+  };
+}

package/src/core/context.js

@@ -0,0 +1,162 @@
+import path from "node:path";
+
+import { CliError } from "./errors.js";
+
+const DEFAULT_API_URL = "http://127.0.0.1:3100";
+
+export function parseEnv(contents) {
+  const parsed = {};
+  for (const rawLine of String(contents || "").split(/\r?\n/u)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const separator = line.indexOf("=");
+    if (separator < 1) continue;
+    const key = line.slice(0, separator).trim();
+    let value = line.slice(separator + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    parsed[key] = value.replace(/\\n/gu, "\n");
+  }
+  return parsed;
+}
+
+async function readEnvFile(filesystem, filePath) {
+  if (!filePath) return {};
+  try {
+    return parseEnv(await filesystem.readFile(filePath, "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") return {};
+    throw new CliError(`Não foi possível ler a configuração em ${filePath}.`, {
+      code: "ENV_FILE_READ_FAILED",
+      cause: error,
+    });
+  }
+}
+
+function normalizeApiUrl(value) {
+  let parsed;
+  try {
+    parsed = new URL(String(value));
+  } catch {
+    throw new CliError("A URL da API é inválida.", {
+      code: "INVALID_API_URL",
+      exitCode: 2,
+    });
+  }
+  if (
+    !["http:", "https:"].includes(parsed.protocol) ||
+    parsed.username ||
+    parsed.password
+  ) {
+    throw new CliError(
+      "A URL da API deve usar HTTP(S) e não conter credenciais.",
+      {
+        code: "INVALID_API_URL",
+        exitCode: 2,
+      },
+    );
+  }
+  parsed.password = "";
+  return parsed.toString().replace(/\/+$/u, "");
+}
+
+export async function resolveCommandContext(options) {
+  const input = options.input || {};
+  const environment = { ...(options.environment || {}) };
+  const toolDirectory = path.resolve(options.toolDirectory);
+  const repositoryRoot = path.resolve(
+    input.root || environment.BIAWS_ROOT || toolDirectory,
+    input.root || environment.BIAWS_ROOT ? "." : "..",
+  );
+  const instancesDirectory = path.resolve(
+    input.instancesDirectory ||
+      environment.BIAWS_INSTANCES_DIR ||
+      path.join(repositoryRoot, "instances"),
+  );
+  const instanceName = String(
+    input.instance || environment.BIAWS_INSTANCE || "",
+  ).trim();
+  const instanceDirectory = path.resolve(
+    input.instanceDirectory ||
+      environment.BIAWS_INSTANCE_DIR ||
+      (instanceName
+        ? path.join(instancesDirectory, instanceName)
+        : instancesDirectory),
+  );
+  const explicitEnvFile = String(
+    input.envFile || environment.BIAWS_ENV_FILE || "",
+  ).trim();
+  const envFile = explicitEnvFile
+    ? path.resolve(explicitEnvFile)
+    : instanceName
+      ? path.join(instanceDirectory, ".env")
+      : "";
+  const rootEnv = await readEnvFile(
+    options.filesystem,
+    path.join(repositoryRoot, ".env"),
+  );
+  const toolEnv = await readEnvFile(
+    options.filesystem,
+    path.join(toolDirectory, ".env"),
+  );
+  const instanceEnv = await readEnvFile(options.filesystem, envFile);
+  const effectiveEnv = {
+    ...rootEnv,
+    ...environment,
+    ...toolEnv,
+    ...instanceEnv,
+  };
+  const apiUrl = normalizeApiUrl(
+    input.apiUrl ||
+      effectiveEnv.ISSUE_API_URL ||
+      effectiveEnv.ISSUE_API_BASE_URL ||
+      DEFAULT_API_URL,
+  );
+  const apiKey = String(input.apiKey || effectiveEnv.ISSUE_API_KEY || "");
+  const workspaceId = String(
+    input.workspaceId ||
+      input.workspace ||
+      effectiveEnv.ISSUE_WORKSPACE_ID ||
+      "",
+  ).trim();
+  const projectDirectory = path.resolve(
+    input.project || options.cwd || repositoryRoot,
+  );
+
+  return Object.freeze({
+    apiKey,
+    apiUrl,
+    env: Object.freeze(effectiveEnv),
+    envFile,
+    instanceDirectory,
+    instanceName,
+    instancesDirectory,
+    isCI: Boolean(options.terminal.isCI),
+    isInteractive: Boolean(options.terminal.isInteractive),
+    projectDirectory,
+    repositoryRoot,
+    toolDirectory,
+    workspaceId,
+  });
+}
+
+export async function resolveAuthenticatedContext(options) {
+  const context = await resolveCommandContext(options);
+  if (!context.apiKey) {
+    throw new CliError(
+      "Chave da API ausente. Defina ISSUE_API_KEY em um ambiente privado.",
+      { code: "AUTHENTICATION_REQUIRED", exitCode: 2 },
+    );
+  }
+  if (options.requireWorkspace && !context.workspaceId) {
+    throw new CliError(
+      "Workspace ausente. Informe --workspace ou defina ISSUE_WORKSPACE_ID.",
+      { code: "WORKSPACE_REQUIRED", exitCode: 2 },
+    );
+  }
+  return context;
+}

package/src/core/errors.js

@@ -0,0 +1,25 @@
+export class CliError extends Error {
+  constructor(message, options = {}) {
+    super(message, { cause: options.cause });
+    this.name = "CliError";
+    this.code = options.code || "CLI_ERROR";
+    this.exitCode = options.exitCode ?? 1;
+    this.oclif = { exit: this.exitCode };
+    this.details = options.details;
+  }
+}
+
+export class ProcessExecutionError extends CliError {
+  constructor(message, options = {}) {
+    super(message, {
+      ...options,
+      code: options.code || "PROCESS_EXECUTION_FAILED",
+      exitCode: options.exitCode ?? 1,
+    });
+    this.name = "ProcessExecutionError";
+    this.command = options.command;
+    this.processExitCode = options.processExitCode ?? null;
+    this.signal = options.signal ?? null;
+    this.stderr = options.stderr || "";
+  }
+}

package/src/core/processRunner.js

@@ -0,0 +1,119 @@
+import { spawn as nodeSpawn } from "node:child_process";
+
+import { ProcessExecutionError } from "./errors.js";
+import { redactText } from "./redaction.js";
+
+function attachOutput(stream, target, chunks, shouldBuffer) {
+  if (!stream) return;
+  stream.on("data", (chunk) => {
+    const value = String(chunk);
+    chunks.push(value);
+    if (!shouldBuffer && target) target.write(value);
+  });
+}
+
+export class ProcessRunner {
+  constructor(options = {}) {
+    this.spawn = options.spawn || nodeSpawn;
+    this.signalSource = options.signalSource || process;
+    this.stdout = options.stdout || process.stdout;
+    this.stderr = options.stderr || process.stderr;
+  }
+
+  run(command, args = [], options = {}) {
+    if (typeof command !== "string" || !command || !Array.isArray(args)) {
+      throw new TypeError("ProcessRunner exige comando e array de argumentos.");
+    }
+    const secrets = options.secrets || [];
+    const shouldBuffer =
+      Boolean(options.silent) || secrets.some((secret) => String(secret || ""));
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    let child;
+    try {
+      child = this.spawn(command, args.map(String), {
+        cwd: options.cwd,
+        env: options.env,
+        shell: false,
+        stdio: [
+          options.input === undefined ? "ignore" : "pipe",
+          "pipe",
+          "pipe",
+        ],
+      });
+    } catch (cause) {
+      throw new ProcessExecutionError(
+        `Falha ao iniciar ${redactText(command, secrets)}.`,
+        { cause, command: redactText(command, secrets) },
+      );
+    }
+    attachOutput(child.stdout, this.stdout, stdoutChunks, shouldBuffer);
+    attachOutput(child.stderr, this.stderr, stderrChunks, shouldBuffer);
+    if (options.input !== undefined) child.stdin.end(options.input);
+
+    return new Promise((resolve, reject) => {
+      const forwardedSignals = ["SIGINT", "SIGTERM", "SIGHUP"];
+      const handlers = new Map(
+        forwardedSignals.map((signal) => [
+          signal,
+          () => {
+            if (!child.killed) child.kill(signal);
+          },
+        ]),
+      );
+      for (const [signal, handler] of handlers) {
+        this.signalSource.on?.(signal, handler);
+      }
+      const cleanup = () => {
+        for (const [signal, handler] of handlers) {
+          this.signalSource.off?.(signal, handler);
+        }
+      };
+      const output = () => ({
+        stdout: redactText(stdoutChunks.join(""), secrets),
+        stderr: redactText(stderrChunks.join(""), secrets),
+      });
+      const flush = (result) => {
+        if (!shouldBuffer || options.silent) return;
+        if (result.stdout && this.stdout) this.stdout.write(result.stdout);
+        if (result.stderr && this.stderr) this.stderr.write(result.stderr);
+      };
+
+      child.once("error", (cause) => {
+        cleanup();
+        reject(
+          new ProcessExecutionError(
+            `Falha ao iniciar ${redactText(command, secrets)}.`,
+            { cause, command: redactText(command, secrets) },
+          ),
+        );
+      });
+      child.once("close", (processExitCode, signal) => {
+        cleanup();
+        const result = { ...output(), processExitCode, signal: signal || null };
+        flush(result);
+        if (processExitCode === 0 && !signal) {
+          resolve(result);
+          return;
+        }
+        const renderedCommand = redactText(
+          [command, ...args].join(" "),
+          secrets,
+        );
+        reject(
+          new ProcessExecutionError(
+            signal
+              ? `Processo interrompido por ${signal}: ${renderedCommand}`
+              : `Processo encerrou com código ${processExitCode}: ${renderedCommand}`,
+            {
+              command: renderedCommand,
+              processExitCode,
+              signal,
+              stderr: result.stderr,
+            },
+          ),
+        );
+      });
+    });
+  }
+}

package/src/core/prompts.js

@@ -0,0 +1,138 @@
+import { confirm, input, number, password, select } from "@inquirer/prompts";
+
+import { CliError } from "./errors.js";
+
+export class PromptCancelledError extends CliError {
+  constructor(
+    message = "Operação cancelada antes de qualquer alteração.",
+    options = {},
+  ) {
+    super(message, {
+      ...options,
+      code: "PROMPT_CANCELLED",
+      exitCode: options.exitCode ?? 130,
+    });
+    this.name = "PromptCancelledError";
+  }
+}
+
+function isPromptCancellation(error) {
+  return (
+    error?.name === "ExitPromptError" ||
+    error?.name === "AbortPromptError" ||
+    error?.name === "AbortError"
+  );
+}
+
+export class PromptAdapter {
+  constructor(options = {}) {
+    this.isInteractive = Boolean(options.isInteractive);
+  }
+
+  async ask() {
+    throw new CliError("O adapter de prompt não implementa ask().", {
+      code: "PROMPT_ADAPTER_INVALID",
+    });
+  }
+}
+
+export class InteractivePromptAdapter extends PromptAdapter {
+  constructor(options = {}) {
+    super({ isInteractive: true });
+    this.prompts = options.prompts || {
+      confirm,
+      input,
+      number,
+      password,
+      select,
+    };
+    this.context = options.context || {};
+  }
+
+  async ask(question, state = {}) {
+    const handler = this.prompts[question.type || "input"];
+    if (!handler) {
+      throw new CliError(`Tipo de pergunta não suportado: ${question.type}.`, {
+        code: "PROMPT_TYPE_UNSUPPORTED",
+        exitCode: 2,
+      });
+    }
+    const config = {
+      message: question.message || question.name,
+      ...(question.choices ? { choices: question.choices } : {}),
+      ...(Object.hasOwn(question, "default")
+        ? { default: question.default }
+        : {}),
+    };
+    try {
+      return await handler(config, {
+        ...this.context,
+        signal: state.signal || this.context.signal,
+      });
+    } catch (error) {
+      if (isPromptCancellation(error)) throw new PromptCancelledError();
+      throw error;
+    }
+  }
+}
+
+export class NonInteractivePromptAdapter extends PromptAdapter {
+  constructor() {
+    super({ isInteractive: false });
+  }
+
+  async ask() {
+    throw new CliError(
+      "Não é possível solicitar entrada sem terminal interativo.",
+      {
+        code: "INTERACTIVE_INPUT_UNAVAILABLE",
+        exitCode: 2,
+      },
+    );
+  }
+}
+
+export class ProgrammedPromptAdapter extends PromptAdapter {
+  constructor(responses = {}, options = {}) {
+    super({ isInteractive: options.isInteractive ?? true });
+    this.responses = Array.isArray(responses)
+      ? [...responses]
+      : { ...responses };
+    this.questions = [];
+  }
+
+  async ask(question, state = {}) {
+    this.questions.push(question.name);
+    let response;
+    if (Array.isArray(this.responses)) {
+      if (this.responses.length === 0) {
+        throw new CliError(
+          `Resposta programada ausente para ${question.name}.`,
+          {
+            code: "PROGRAMMED_RESPONSE_MISSING",
+          },
+        );
+      }
+      response = this.responses.shift();
+    } else if (Object.hasOwn(this.responses, question.name)) {
+      response = this.responses[question.name];
+    } else {
+      throw new CliError(`Resposta programada ausente para ${question.name}.`, {
+        code: "PROGRAMMED_RESPONSE_MISSING",
+      });
+    }
+    if (typeof response === "function")
+      response = await response(question, state);
+    if (response instanceof Error) throw response;
+    return response;
+  }
+}
+
+export function createPromptAdapter(terminal, options = {}) {
+  if (options.adapter) return options.adapter;
+  if (!terminal?.isInteractive) return new NonInteractivePromptAdapter();
+  return new InteractivePromptAdapter({
+    context: { input: terminal.stdin, output: terminal.stdout },
+    prompts: options.prompts,
+  });
+}

package/src/core/redaction.js

@@ -0,0 +1,29 @@
+const SECRET_KEY_PATTERN =
+  /(?:api[-_]?key|authorization|cookie|credential|password|secret|token)/iu;
+
+export function redactText(value, secrets = []) {
+  let output = String(value ?? "");
+  for (const secret of secrets) {
+    const normalized = String(secret ?? "");
+    if (normalized) output = output.split(normalized).join("[REDACTED]");
+  }
+  return output;
+}
+
+export function redactValue(value, secrets = [], seen = new WeakSet()) {
+  if (typeof value === "string") return redactText(value, secrets);
+  if (value === null || typeof value !== "object") return value;
+  if (seen.has(value)) return "[CIRCULAR]";
+  seen.add(value);
+  if (Array.isArray(value)) {
+    return value.map((item) => redactValue(item, secrets, seen));
+  }
+  return Object.fromEntries(
+    Object.entries(value).map(([key, item]) => [
+      key,
+      SECRET_KEY_PATTERN.test(key)
+        ? "[REDACTED]"
+        : redactValue(item, secrets, seen),
+    ]),
+  );
+}

package/src/core/terminal.js

@@ -0,0 +1,72 @@
+import { redactText, redactValue } from "./redaction.js";
+
+function writeLine(stream, value) {
+  stream.write(`${value}\n`);
+}
+
+export function createTerminalAdapter(options = {}) {
+  const stdin = options.stdin || process.stdin;
+  const stdout = options.stdout || process.stdout;
+  const stderr = options.stderr || process.stderr;
+  const environment = options.environment || process.env;
+  return Object.freeze({
+    stdin,
+    stdout,
+    stderr,
+    isInteractive: Boolean(stdin.isTTY && stdout.isTTY),
+    isCI: Boolean(environment.CI),
+  });
+}
+
+export class CliOutput {
+  constructor(terminal, options = {}) {
+    this.terminal = terminal;
+    this.json = Boolean(options.json);
+    this.secrets = options.secrets || [];
+  }
+
+  result(value) {
+    if (this.json) {
+      writeLine(
+        this.terminal.stdout,
+        JSON.stringify(redactValue(value, this.secrets), null, 2),
+      );
+      return;
+    }
+    writeLine(this.terminal.stdout, redactText(value, this.secrets));
+  }
+
+  diagnostic(value) {
+    writeLine(this.terminal.stderr, redactText(value, this.secrets));
+  }
+}
+
+export class CliLogger {
+  constructor(terminal, options = {}) {
+    this.terminal = terminal;
+    this.secrets = options.secrets || [];
+    this.verbose = Boolean(options.verbose);
+  }
+
+  event(level, event, fields = {}) {
+    if (level === "debug" && !this.verbose) return;
+    const entry = redactValue({ ...fields, level, event }, this.secrets);
+    writeLine(this.terminal.stderr, JSON.stringify(entry));
+  }
+
+  debug(event, fields) {
+    this.event("debug", event, fields);
+  }
+
+  info(event, fields) {
+    this.event("info", event, fields);
+  }
+
+  warn(event, fields) {
+    this.event("warn", event, fields);
+  }
+
+  error(event, fields) {
+    this.event("error", event, fields);
+  }
+}