biaws 0.1.0

package/src/core/wizard.js

@@ -0,0 +1,279 @@
+import { Flags } from "@oclif/core";
+
+import { CliError } from "./errors.js";
+import {
+  NonInteractivePromptAdapter,
+  PromptCancelledError,
+  createPromptAdapter,
+} from "./prompts.js";
+import { redactValue } from "./redaction.js";
+
+const REDACTED = "[REDACTED]";
+
+export const wizardFlags = Object.freeze({
+  defaults: Flags.boolean({
+    description: "aplica somente os defaults declarados pelo comando",
+  }),
+  interactive: Flags.boolean({
+    description: "solicita em um TTY os campos que não foram informados",
+    exclusive: ["non-interactive"],
+  }),
+  json: Flags.boolean({
+    description: "emite o resumo estruturado em JSON",
+  }),
+  "non-interactive": Flags.boolean({
+    description: "não solicita entradas e falha se campos estiverem ausentes",
+    exclusive: ["interactive"],
+  }),
+  yes: Flags.boolean({
+    char: "y",
+    description: "pula somente a confirmação do plano validado",
+  }),
+});
+
+function hasValue(value) {
+  return value !== undefined && value !== null && value !== "";
+}
+
+function clone(value) {
+  if (Array.isArray(value)) return value.map(clone);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [key, clone(item)]),
+    );
+  }
+  return value;
+}
+
+function deepFreeze(value) {
+  if (!value || typeof value !== "object" || Object.isFrozen(value))
+    return value;
+  for (const item of Object.values(value)) deepFreeze(item);
+  return Object.freeze(value);
+}
+
+export class MissingWizardInputError extends CliError {
+  constructor(fields) {
+    const names = fields.map((field) => field.name);
+    super(`Campos obrigatórios ausentes: ${names.join(", ")}.`, {
+      code: "MISSING_REQUIRED_INPUT",
+      exitCode: 2,
+      details: { fields: names },
+    });
+    this.name = "MissingWizardInputError";
+    this.fields = names;
+  }
+}
+
+export class ExecutionPlan {
+  #values;
+
+  constructor(kind, values, questions) {
+    this.#values = deepFreeze(clone(values));
+    const secretNames = new Set(
+      questions
+        .filter((question) => question.secret)
+        .map((question) => question.name),
+    );
+    const secretValues = [...secretNames]
+      .map((name) => values[name])
+      .filter(hasValue)
+      .map(String);
+    this.kind = kind;
+    this.values = deepFreeze(
+      Object.fromEntries(
+        Object.entries(values).map(([name, value]) => [
+          name,
+          secretNames.has(name) && hasValue(value)
+            ? REDACTED
+            : redactValue(clone(value), secretValues),
+        ]),
+      ),
+    );
+    Object.freeze(this);
+  }
+
+  get(name) {
+    return this.#values[name];
+  }
+
+  toJSON() {
+    return { kind: this.kind, values: this.values };
+  }
+}
+
+export function normalizeWizardOptions(options = {}, terminal = {}) {
+  const nonInteractive = Boolean(
+    options.nonInteractive || options["non-interactive"],
+  );
+  if (options.interactive && nonInteractive) {
+    throw new CliError(
+      "--interactive e --non-interactive são mutuamente exclusivos.",
+      {
+        code: "INTERACTION_MODE_CONFLICT",
+        exitCode: 2,
+      },
+    );
+  }
+  return Object.freeze({
+    defaults: Boolean(options.defaults),
+    interactive: Boolean(
+      !nonInteractive &&
+      terminal.isInteractive &&
+      (options.interactive || !nonInteractive),
+    ),
+    json: Boolean(options.json),
+    yes: Boolean(options.yes),
+  });
+}
+
+function sourceValue(question, flags, environment) {
+  const flagName = question.flag || question.name;
+  if (hasValue(flags[flagName])) return flags[flagName];
+  if (question.environment && hasValue(environment[question.environment])) {
+    return environment[question.environment];
+  }
+  return undefined;
+}
+
+async function isApplicable(question, values) {
+  return question.when
+    ? Boolean(await question.when(Object.freeze({ ...values })))
+    : true;
+}
+
+async function validateAnswer(question, value, values) {
+  if (!question.validate) return;
+  const result = await question.validate(value, Object.freeze({ ...values }));
+  if (result === true || result === undefined) return;
+  const message =
+    typeof result === "string"
+      ? result
+      : `Valor inválido para ${question.name}.`;
+  throw new CliError(message, {
+    code: "WIZARD_VALIDATION_FAILED",
+    exitCode: 2,
+    details: { field: question.name },
+  });
+}
+
+export async function collectWizardValues(definition, input = {}) {
+  const terminal = input.terminal || {};
+  const options = normalizeWizardOptions(input.options, terminal);
+  const adapter =
+    input.promptAdapter ||
+    (options.interactive
+      ? createPromptAdapter(terminal, input.promptOptions)
+      : new NonInteractivePromptAdapter());
+  const values = {};
+  const missing = [];
+  const questions = definition.questions || [];
+
+  for (const question of questions) {
+    if (!(await isApplicable(question, values))) continue;
+    let value = sourceValue(
+      question,
+      input.flags || {},
+      input.environment || {},
+    );
+    const hasDefault = Object.hasOwn(question, "default");
+    const defaultValue = hasDefault
+      ? typeof question.default === "function"
+        ? await question.default(Object.freeze({ ...values }))
+        : question.default
+      : undefined;
+    if (!hasValue(value) && options.defaults && hasDefault) {
+      value = defaultValue;
+    }
+    if (!hasValue(value) && options.interactive) {
+      try {
+        value = await adapter.ask(
+          hasDefault ? { ...question, default: defaultValue } : question,
+          {
+            signal: input.signal,
+            values: Object.freeze({ ...values }),
+          },
+        );
+      } catch (error) {
+        if (error instanceof PromptCancelledError) throw error;
+        if (error?.name === "AbortError") throw new PromptCancelledError();
+        throw error;
+      }
+    }
+    if (!hasValue(value)) {
+      if (question.required !== false) missing.push(question);
+      continue;
+    }
+    await validateAnswer(question, value, values);
+    values[question.name] = value;
+  }
+
+  if (missing.length > 0) throw new MissingWizardInputError(missing);
+  return Object.freeze({ options, questions, values: deepFreeze(values) });
+}
+
+export function createExecutionPlan(definition, collected) {
+  if (!definition?.kind) {
+    throw new CliError("O wizard deve definir um identificador de plano.", {
+      code: "WIZARD_DEFINITION_INVALID",
+      exitCode: 2,
+    });
+  }
+  return new ExecutionPlan(
+    definition.kind,
+    collected.values,
+    collected.questions,
+  );
+}
+
+export function summarizeExecutionPlan(plan) {
+  return plan.toJSON();
+}
+
+export async function confirmExecutionPlan(plan, input = {}) {
+  if (input.options?.yes) return true;
+  if (!input.terminal?.isInteractive || !input.promptAdapter?.isInteractive) {
+    throw new CliError(
+      "Confirmação necessária. Use --yes em modo não interativo.",
+      {
+        code: "CONFIRMATION_REQUIRED",
+        exitCode: 2,
+      },
+    );
+  }
+  let confirmed;
+  try {
+    confirmed = await input.promptAdapter.ask(
+      {
+        name: "confirmation",
+        type: "confirm",
+        message: input.message || `Executar o plano ${plan.kind}?`,
+        default: false,
+      },
+      { signal: input.signal, values: plan.values },
+    );
+  } catch (error) {
+    if (error instanceof PromptCancelledError) throw error;
+    if (error?.name === "AbortError") throw new PromptCancelledError();
+    throw error;
+  }
+  if (!confirmed) throw new PromptCancelledError();
+  return true;
+}
+
+export async function executeExecutionPlan(plan, executor, input = {}) {
+  if (typeof executor !== "function") {
+    throw new CliError("Executor do plano não informado.", {
+      code: "PLAN_EXECUTOR_INVALID",
+    });
+  }
+  await confirmExecutionPlan(plan, input);
+  return executor(plan, { signal: input.signal });
+}
+
+export async function buildExecutionPlan(definition, input = {}) {
+  return createExecutionPlan(
+    definition,
+    await collectWizardValues(definition, input),
+  );
+}

package/src/domain/readCommand.js

@@ -0,0 +1,65 @@
+import { Flags } from "@oclif/core";
+import { AuthenticatedApiCommand } from "../baseCommands.js";
+import { asCliError, DomainReadService, readEnvelope } from "./readService.js";
+
+export const connectionFlags = {
+  "api-url": Flags.string({ description: "URL da API" }),
+  instance: Flags.string({ description: "instância local configurada" }),
+  json: Flags.boolean({ description: "emite somente JSON v1 em stdout" }),
+  workspace: Flags.string({ description: "ID do workspace" }),
+};
+
+export const listFlags = {
+  limit: Flags.integer({ min: 1, description: "quantidade por página" }),
+  page: Flags.integer({ min: 1, description: "página" }),
+  search: Flags.string({ description: "busca textual" }),
+  status: Flags.string({ description: "filtra por status" }),
+};
+
+export class ReadCommand extends AuthenticatedApiCommand {
+  async read(flags, operation, options = {}) {
+    try {
+      const context = await this.authenticatedContext(
+        {
+          apiUrl: flags["api-url"],
+          instance: flags.instance,
+          workspace: flags.workspace,
+        },
+        { requireWorkspace: Boolean(options.requireWorkspace) },
+      );
+      const service = new DomainReadService(context.api);
+      const payload = await operation(service, context);
+      return {
+        context,
+        envelope: readEnvelope(
+          options.resource,
+          options.operation,
+          payload,
+          options.scope?.(context) || { workspaceId: context.workspaceId },
+        ),
+        payload,
+      };
+    } catch (error) {
+      throw asCliError(error, options.resource);
+    }
+  }
+
+  emit(flags, result, human) {
+    if (flags.json) {
+      this.output({ json: true }).result(result.envelope);
+      return;
+    }
+    const lines = [human(result.payload)];
+    const scope = result.envelope.scope;
+    lines.push(
+      `Escopo: workspace=${scope.workspaceId || "não informado"}${scope.applicationId ? ` application=${scope.applicationId}` : ""}${scope.requestId ? ` demand=${scope.requestId}` : ""}`,
+    );
+    if (result.envelope.pagination) {
+      const page = result.envelope.pagination;
+      lines.push(
+        `Paginação: page=${page.page ?? "não informada"} limit=${page.limit ?? "não informado"} returned=${page.returned ?? "desconhecido"} total=${page.total ?? "desconhecido"} truncated=${page.truncated}`,
+      );
+    }
+    this.output().result(lines.join("\n"));
+  }
+}

package/src/domain/readService.js

@@ -0,0 +1,126 @@
+import { CliError } from "../core/errors.js";
+
+const SCHEMA_VERSION = "biaws.read.v1";
+
+function queryString(parameters = {}) {
+  const query = new URLSearchParams();
+  for (const [key, value] of Object.entries(parameters)) {
+    if (value === undefined || value === null || value === "") continue;
+    query.set(key, String(value));
+  }
+  return query.size ? `?${query}` : "";
+}
+
+function pagination(payload = {}) {
+  const meta = payload.meta || {};
+  return {
+    page: meta.page ?? null,
+    limit: meta.limit ?? null,
+    total: meta.total ?? meta.count ?? null,
+    returned: Array.isArray(payload.items) ? payload.items.length : null,
+    truncated: Boolean(meta.truncated),
+  };
+}
+
+export function readEnvelope(resource, operation, payload, scope = {}) {
+  const data = operation === "list" ? payload.items || [] : payload;
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    resource,
+    operation,
+    scope: {
+      workspaceId: scope.workspaceId || null,
+      applicationId: scope.applicationId || null,
+      requestId: scope.requestId || null,
+    },
+    pagination: operation === "list" ? pagination(payload) : null,
+    data,
+  };
+}
+
+export function table(items, columns) {
+  if (!items.length) return "Nenhum resultado.";
+  const rows = [columns.map(([label]) => label)];
+  for (const item of items) {
+    rows.push(columns.map(([, read]) => String(read(item) ?? "")));
+  }
+  const widths = rows[0].map((_, index) =>
+    Math.max(...rows.map((row) => row[index].length)),
+  );
+  return rows
+    .map((row) =>
+      row
+        .map((cell, index) => cell.padEnd(widths[index]))
+        .join("  ")
+        .trimEnd(),
+    )
+    .join("\n");
+}
+
+export function asCliError(error, resource) {
+  if (error instanceof CliError) return error;
+  const status = error?.statusCode;
+  const exitCode =
+    status === 404 ? 4 : status === 403 ? 3 : status === 401 ? 2 : 1;
+  const code =
+    status === 404
+      ? "RESOURCE_NOT_FOUND"
+      : status === 403
+        ? "PERMISSION_DENIED"
+        : error?.code || "API_READ_FAILED";
+  return new CliError(`${resource}: ${error.message}`, {
+    cause: error,
+    code,
+    exitCode,
+  });
+}
+
+export class DomainReadService {
+  constructor(api) {
+    this.api = api;
+  }
+  workspaces() {
+    return this.api.request("/catalog/workspaces");
+  }
+  workspace(id) {
+    return this.api.request(`/catalog/workspaces/${encodeURIComponent(id)}`);
+  }
+  applications(workspaceId, filters) {
+    return this.api.request(
+      `/catalog/workspaces/${encodeURIComponent(workspaceId)}/applications${queryString(filters)}`,
+    );
+  }
+  application(id) {
+    return this.api.request(`/catalog/applications/${encodeURIComponent(id)}`);
+  }
+  demands(filters) {
+    return this.api.request(`/requests${queryString(filters)}`);
+  }
+  async demand(id, filters = {}) {
+    try {
+      return await this.api.request(
+        `/requests/${encodeURIComponent(id)}${queryString(filters)}`,
+      );
+    } catch (error) {
+      if (error?.statusCode !== 404) throw error;
+      const payload = await this.demands({ ...filters, code: id, limit: 2 });
+      const matches = (payload.items || []).filter(
+        (item) => String(item.clientCode || "") === String(id),
+      );
+      if (matches.length === 1) return { request: matches[0] };
+      if (matches.length > 1) {
+        throw new CliError(`Código de melhoria ambíguo: ${id}.`, {
+          code: "AMBIGUOUS_DEMAND_CODE",
+          exitCode: 2,
+        });
+      }
+      throw error;
+    }
+  }
+  issues(filters) {
+    return this.api.request(`/issues${queryString(filters)}`);
+  }
+  issue(id) {
+    return this.api.request(`/issues/${encodeURIComponent(id)}`);
+  }
+}

package/src/domain/writeCommand.js

@@ -0,0 +1,91 @@
+import { Flags } from "@oclif/core";
+import { AuthenticatedApiCommand } from "../baseCommands.js";
+import { CliError } from "../core/errors.js";
+import {
+  asWriteCliError,
+  DomainWriteService,
+  writeEnvelope,
+} from "./writeService.js";
+
+export const writeFlags = {
+  "api-url": Flags.string({ description: "URL da API" }),
+  instance: Flags.string({ description: "instância local configurada" }),
+  json: Flags.boolean({ description: "emite somente JSON v1 em stdout" }),
+  workspace: Flags.string({ description: "ID do workspace" }),
+  yes: Flags.boolean({ char: "y", description: "confirma a alteração" }),
+};
+
+export class WriteCommand extends AuthenticatedApiCommand {
+  async write(flags, resource, resolve, mutate) {
+    try {
+      const context = await this.authenticatedContext(
+        {
+          apiUrl: flags["api-url"],
+          instance: flags.instance,
+          workspace: flags.workspace,
+        },
+        { requireWorkspace: true },
+      );
+      const service = new DomainWriteService(context.api);
+      const plan = await resolve(service, context);
+      if (plan.currentStatus === plan.status) {
+        return this.emit(flags, {
+          ...plan,
+          workspaceId: context.workspaceId,
+          changed: false,
+          previousStatus: plan.currentStatus,
+          data: plan.entity,
+        });
+      }
+      await this.confirm(flags, plan);
+      const payload = await mutate(service, plan, context);
+      return this.emit(flags, {
+        ...plan,
+        workspaceId: context.workspaceId,
+        changed: true,
+        previousStatus: plan.currentStatus,
+        data: payload,
+      });
+    } catch (error) {
+      throw asWriteCliError(error, resource);
+    }
+  }
+
+  async confirm(flags, plan) {
+    if (flags.yes) return;
+    if (!this.adapters.terminal.isInteractive) {
+      throw new CliError(
+        "Confirmação necessária. Use --yes em modo não interativo.",
+        {
+          code: "CONFIRMATION_REQUIRED",
+          exitCode: 2,
+        },
+      );
+    }
+    const confirmed = await this.adapters.prompts.ask({
+      name: "confirmation",
+      type: "confirm",
+      default: false,
+      message: `${plan.label}: alterar status de ${plan.currentStatus} para ${plan.status}?`,
+    });
+    if (!confirmed) {
+      throw new CliError("Alteração cancelada.", {
+        code: "OPERATION_CANCELLED",
+        exitCode: 2,
+      });
+    }
+  }
+
+  emit(flags, result) {
+    const envelope = writeEnvelope(result.resource, result.operation, result);
+    if (flags.json) this.output({ json: true }).result(envelope);
+    else {
+      this.output().result(
+        result.changed
+          ? `${result.label}: ${result.previousStatus} -> ${result.status}`
+          : `${result.label}: já está em ${result.status}; nenhuma alteração realizada.`,
+      );
+    }
+    return envelope;
+  }
+}

package/src/domain/writeService.js

@@ -0,0 +1,122 @@
+import { CliError } from "../core/errors.js";
+
+const SCHEMA_VERSION = "biaws.write.v1";
+
+function referenceOf(item) {
+  return String(item?.id || item?._id || item?.code || "");
+}
+
+export function findTask(payload, reference) {
+  const request = payload.request || payload;
+  const matches = (request.tasks || []).filter(
+    (task) =>
+      referenceOf(task) === String(reference) ||
+      String(task.code || "") === String(reference),
+  );
+  if (matches.length === 0) {
+    throw new CliError(`Tarefa ${reference} não encontrada na melhoria.`, {
+      code: "TASK_NOT_FOUND",
+      exitCode: 4,
+    });
+  }
+  if (matches.length > 1) {
+    throw new CliError(
+      `A referência ${reference} identifica mais de uma tarefa.`,
+      {
+        code: "AMBIGUOUS_TASK_REFERENCE",
+        exitCode: 2,
+      },
+    );
+  }
+  return { request, task: matches[0] };
+}
+
+export function writeEnvelope(resource, operation, result) {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    resource,
+    operation,
+    scope: {
+      workspaceId: result.workspaceId || null,
+      applicationId: result.applicationId || null,
+      requestId: result.requestId || null,
+    },
+    changed: result.changed,
+    previousStatus: result.previousStatus,
+    status: result.status,
+    data: result.data,
+  };
+}
+
+export function asWriteCliError(error, resource) {
+  if (error instanceof CliError) return error;
+  const status = error?.statusCode;
+  const exitCode =
+    status === 404
+      ? 4
+      : status === 403
+        ? 3
+        : status === 401 || status === 422 || status === 409
+          ? 2
+          : 1;
+  const fallback =
+    status === 404
+      ? "RESOURCE_NOT_FOUND"
+      : status === 403
+        ? "PERMISSION_DENIED"
+        : status === 409
+          ? "WRITE_CONFLICT"
+          : status === 422
+            ? "INVALID_TRANSITION"
+            : "API_WRITE_FAILED";
+  return new CliError(`${resource}: ${error.message}`, {
+    cause: error,
+    code: error?.code || fallback,
+    exitCode,
+  });
+}
+
+export class DomainWriteService {
+  constructor(api) {
+    this.api = api;
+  }
+
+  async demand(id) {
+    try {
+      return await this.api.request(`/requests/${encodeURIComponent(id)}`);
+    } catch (error) {
+      if (error?.statusCode !== 404) throw error;
+      const query = new URLSearchParams({ code: String(id), limit: "2" });
+      const payload = await this.api.request(`/requests?${query}`);
+      const matches = (payload.items || []).filter(
+        (item) => String(item.clientCode || "") === String(id),
+      );
+      if (matches.length === 1) return { request: matches[0] };
+      if (matches.length > 1) {
+        throw new CliError(`Código de melhoria ambíguo: ${id}.`, {
+          code: "AMBIGUOUS_DEMAND_CODE",
+          exitCode: 2,
+        });
+      }
+      throw error;
+    }
+  }
+
+  issue(id) {
+    return this.api.request(`/issues/${encodeURIComponent(id)}`);
+  }
+
+  updateTaskStatus(demandId, taskId, status) {
+    return this.api.request(
+      `/requests/${encodeURIComponent(demandId)}/tasks/${encodeURIComponent(taskId)}`,
+      { method: "PUT", body: JSON.stringify({ status }) },
+    );
+  }
+
+  updateIssueStatus(issueId, status) {
+    return this.api.request(`/issues/${encodeURIComponent(issueId)}`, {
+      method: "PATCH",
+      body: JSON.stringify({ status }),
+    });
+  }
+}

package/src/index.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { execute } from "@oclif/core";
+
+await execute({ dir: import.meta.url });