biaws 0.2.1 → 0.3.0

package/README.md

@@ -122,6 +122,7 @@ biaws workspace api PATCH /recurso/ID --body '{"status":"Ativo"}'
 ```bash
 biaws workspace agent configure codex
 biaws workspace agent configure claude
+biaws workspace agent configure codex --no-interactive --env-file /caminho/instancia.env --workspace workspace-id
 biaws workspace agent doctor codex
 biaws workspace skills list
 biaws workspace skills install SKILL_ID
@@ -131,7 +132,9 @@ biaws workspace skills status
 
 O Codex usa `.codex/config.toml` e `.agents/skills`. O Claude Code usa
 `.mcp.json` e `.claude/skills`. Configurações de terceiros são preservadas e
-nenhuma credencial é gravada no projeto.
+nenhuma credencial é gravada no projeto. O MCP é configurado como
+`npx --yes biaws-mcp@<versão-fixada>`, sem exigir um checkout local da
+plataforma.
 
 ## Monitoramento
 
@@ -171,6 +174,7 @@ biaws admin instance list
 biaws admin instance status local
 biaws admin instance start local
 biaws admin instance stop local
+biaws admin instance update local
 biaws admin instance backup local
 ```
 

package/docs/command-taxonomy.md

@@ -10,7 +10,7 @@ biaws
 │   ├── install
 │   ├── doctor
 │   ├── config
-│   ├── instance setup|list|show|status|start|stop|backup|restore|remove
+│   ├── instance setup|list|show|status|start|stop|update|backup|restore|remove
 │   └── monitoring build|validate|start|stop|status|logs|provision
 ├── config
 │   ├── init|login|show|set|unset|doctor
@@ -61,9 +61,8 @@ flags > variáveis de ambiente > configuração da pasta > perfil global > defau
 ```
 
 As variáveis canônicas são `BIAWS_API_URL`, `BIAWS_API_KEY` e
-`BIAWS_WORKSPACE_ID`. Os nomes `ISSUE_*` permanecem aceitos como variáveis de
-ambiente internas durante a transição do backend, mas não representam comandos
-antigos do CLI.
+`BIAWS_WORKSPACE_ID`. Variáveis com o prefixo temporário anterior não são
+aceitas como aliases.
 
 ## Convenções
 

package/docs/instance-lifecycle.md

@@ -35,6 +35,46 @@ biaws admin instance stop local
 `status` invocam Docker Compose sem shell e com projeto, arquivo Compose e env
 da instância resolvidos explicitamente.
 
+## Atualização
+
+Depois de atualizar o checkout ou instalar uma nova release, reconstrua API,
+UI e os demais serviços com:
+
+```bash
+biaws admin instance update local
+```
+
+Antes de alterar a instância, consulte a versão efetivamente implantada e a
+versão disponível no checkout:
+
+```bash
+biaws admin instance update local --check
+biaws admin instance update local --check --json
+```
+
+O resultado informa `currentVersion`, `newVersion` e `updateRequired`.
+Instâncias criadas antes desse mecanismo começam com `currentVersion` igual a
+`unknown` e são consideradas pendentes. Se as versões forem iguais, o comando
+não cria backup nem reconstrói containers; use `--force` para repetir o deploy.
+
+Por padrão, o comando valida o arquivo Compose, solicita uma senha, cria um
+backup completo e então executa `up -d --build --wait`. Em automação, use um
+arquivo privado para a senha:
+
+```bash
+biaws admin instance update local --password-file /caminho/privado/senha
+```
+
+Se a política operacional já produz um backup externo verificável, a criação
+local pode ser dispensada explicitamente com `--skip-backup`. O update preserva
+o project name, o `.env`, os volumes e os bind mounts da instância. Ele não
+executa `git pull` nem troca a versão do checkout.
+
+A versão implantada só é registrada depois que `up -d --build --wait` termina
+com sucesso. Ela também é exposta pelo `/api/health` e pelos labels dos
+containers de API e UI. A versão nova é lida do `biaws-cli/package.json` da
+raiz selecionada por `--root`/`BIAWS_ROOT`.
+
 ## Smoke test Docker real
 
 Em um checkout descartável com Docker e OpenSSL disponíveis:

package/docs/releasing.md

@@ -69,9 +69,13 @@ não são aliases circulares. A remoção dos wrappers públicos só pode ocorre
 após aviso de depreciação em uma release `0.x`, telemetria ou evidência de
 adoção e um runbook de substituição atualizado.
 
-O pacote npm isolado cobre ajuda e API remota. Instância, MCP e catálogo local
-dependem do checkout completo; defina `BIAWS_ROOT` para sua raiz quando o
-executável global for chamado fora dela.
+O pacote npm isolado cobre ajuda, API remota, instalação das skills e
+configuração do MCP publicado. Operações de instância e publicação do catálogo
+inicial dependem do checkout completo; defina `BIAWS_ROOT` para sua raiz quando
+o executável global for chamado fora dela.
+
+Publique primeiro a versão de `biaws-mcp` fixada pelo CLI. O CLI nunca deve ser
+publicado apontando para uma versão do MCP que ainda não exista no registry.
 
 ## Exercício de release
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "biaws",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "CLI do Bondia Workspaces para administração, configuração e operação de workspaces",
   "license": "Apache-2.0",
   "repository": {

package/src/cli/admin/instance/update.js

@@ -0,0 +1 @@
+export { default } from "../../../commands/instance/update.js";

package/src/commandFactories.js

@@ -4,6 +4,7 @@ import { AuthenticatedApiCommand, ProjectCommand } from "./baseCommands.js";
 import {
   configureContextFlags,
   configureContextInput,
+  interactiveConfigureInput,
   legacyAgentContext,
 } from "./configure/command.js";
 import { runAgentCommand } from "./commands/agent.js";
@@ -85,12 +86,21 @@ export function createAgentCommand(action) {
 
     async run() {
       const { args, flags } = await this.parse(this.constructor);
-      const context = await this.projectContext(configureContextInput(flags));
+      const input =
+        action === "configure"
+          ? await interactiveConfigureInput(this, flags)
+          : configureContextInput(flags);
+      const context = await this.projectContext(input);
       await runAgentCommand(
         context.api,
         action,
         [args.client],
-        { ...flags, project: context.projectDirectory },
+        {
+          ...flags,
+          interactive: input.interactive,
+          project: context.projectDirectory,
+          prompts: this.adapters.prompts,
+        },
         legacyAgentContext(context),
       );
     }

package/src/commands/agent.js

@@ -4,11 +4,17 @@ import path from "node:path";
 
 import { BaseCommand, TOOL_DIRECTORY } from "../baseCommands.js";
 import { showTopic } from "../commandFactories.js";
+import { CliError } from "../core/errors.js";
 import { readLock } from "../localSkills.js";
 import { runSkillsCommand } from "./skills.js";
 
 const CODEX_BEGIN = "# BEGIN BIAWS MANAGED MCP";
 const CODEX_END = "# END BIAWS MANAGED MCP";
+export const MCP_PACKAGE_NAME = "biaws-mcp";
+export const MCP_PACKAGE_VERSION = "0.2.0";
+export const MCP_PACKAGE_SPEC = `${MCP_PACKAGE_NAME}@${MCP_PACKAGE_VERSION}`;
+const MCP_COMMAND = "npx";
+const MCP_ARGS = ["--yes", MCP_PACKAGE_SPEC];
 
 function skillTarget(client, projectDirectory) {
   return path.join(
@@ -18,8 +24,18 @@ function skillTarget(client, projectDirectory) {
   );
 }
 
-function mcpEntrypoint(toolDirectory) {
-  return path.resolve(toolDirectory, "..", "biaws-mcp", "src", "index.js");
+function isExpectedClaudeServer(server) {
+  if (
+    server?.command === MCP_COMMAND &&
+    JSON.stringify(server.args || []) === JSON.stringify(MCP_ARGS)
+  ) {
+    return true;
+  }
+  return (
+    server?.command === "node" &&
+    server.args?.length === 1 &&
+    /(?:^|[\\/])biaws-mcp[\\/]src[\\/]index\.js$/u.test(server.args[0])
+  );
 }
 
 async function readOptional(filePath, fallback = "") {
@@ -33,7 +49,6 @@ async function readOptional(filePath, fallback = "") {
 
 async function writeCodexConfiguration(
   projectDirectory,
-  entrypoint,
   envFile,
   workspaceId,
   force,
@@ -59,9 +74,9 @@ async function writeCodexConfiguration(
   }
   const managed = `${CODEX_BEGIN}
 [mcp_servers.biaws]
-command = "node"
-args = [${JSON.stringify(entrypoint)}]
-env = {${envFile ? ` BIAWS_ENV_FILE = ${JSON.stringify(envFile)},` : ""} ISSUE_WORKSPACE_ID = ${JSON.stringify(workspaceId)} }
+command = ${JSON.stringify(MCP_COMMAND)}
+args = ${JSON.stringify(MCP_ARGS)}
+env = {${envFile ? ` BIAWS_ENV_FILE = ${JSON.stringify(envFile)},` : ""} BIAWS_WORKSPACE_ID = ${JSON.stringify(workspaceId)} }
 ${CODEX_END}
 `;
   const output = current ? `${current}\n\n${managed}` : managed;
@@ -71,7 +86,6 @@ ${CODEX_END}
 
 async function writeClaudeConfiguration(
   projectDirectory,
-  entrypoint,
   envFile,
   workspaceId,
   force,
@@ -85,31 +99,34 @@ async function writeClaudeConfiguration(
     throw new Error(`JSON inválido em ${configPath}`);
   }
   config.mcpServers ||= {};
-  if (config.mcpServers.biaws && !force) {
-    const current = config.mcpServers.biaws;
-    if (
-      current.command !== "node" ||
-      JSON.stringify(current.args || []) !== JSON.stringify([entrypoint])
-    ) {
-      throw new Error(
-        `Já existe uma configuração Claude diferente para o servidor biaws em ${configPath}; use --force para substituí-la`,
-      );
-    }
+  if (
+    config.mcpServers.biaws &&
+    !force &&
+    !isExpectedClaudeServer(config.mcpServers.biaws)
+  ) {
+    throw new Error(
+      `Já existe uma configuração Claude diferente para o servidor biaws em ${configPath}; use --force para substituí-la`,
+    );
   }
   config.mcpServers.biaws = {
     type: "stdio",
-    command: "node",
-    args: [entrypoint],
+    command: MCP_COMMAND,
+    args: MCP_ARGS,
     env: {
       ...(envFile ? { BIAWS_ENV_FILE: envFile } : {}),
-      ISSUE_WORKSPACE_ID: workspaceId,
+      BIAWS_WORKSPACE_ID: workspaceId,
     },
   };
   await writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
   return configPath;
 }
 
-async function resolveWorkspaceId(api, requestedWorkspaceId = "") {
+async function resolveWorkspaceId(
+  api,
+  requestedWorkspaceId = "",
+  interactive = false,
+  prompts,
+) {
   let identity;
   try {
     identity = await api.identity();
@@ -121,7 +138,22 @@ async function resolveWorkspaceId(api, requestedWorkspaceId = "") {
     }
     throw error;
   }
-  const workspaceId = requestedWorkspaceId || identity?.actor?.workspaceId;
+  const workspaces = identity?.actor?.workspaces || [];
+  let workspaceId = requestedWorkspaceId || identity?.actor?.workspaceId;
+  if (interactive && workspaces.length > 0) {
+    workspaceId = await prompts.ask({
+      name: "workspaceId",
+      type: "select",
+      message: "Workspace do projeto",
+      choices: workspaces.map((workspace) => ({
+        name: workspace.name
+          ? `${workspace.name} (${workspace.id})`
+          : workspace.id,
+        value: workspace.id,
+      })),
+      ...(workspaceId ? { default: workspaceId } : {}),
+    });
+  }
   if (!workspaceId) {
     if ((identity?.actor?.workspaces?.length || 0) > 1) {
       throw new Error(
@@ -142,21 +174,40 @@ async function configure(api, client, options, context) {
     );
   }
   const projectDirectory = path.resolve(options.project || process.cwd());
-  const { workspaceId } = await resolveWorkspaceId(api, context.workspaceId);
+  const { workspaceId } = await resolveWorkspaceId(
+    api,
+    context.workspaceId,
+    options.interactive,
+    options.prompts,
+  );
+  if (options.interactive) {
+    const confirmed = await options.prompts.ask({
+      name: "confirmConfiguration",
+      type: "confirm",
+      message: `Configurar ${client} em ${projectDirectory} para o workspace ${workspaceId}?`,
+      default: true,
+    });
+    if (!confirmed) {
+      throw new CliError(
+        "Configuração cancelada antes de qualquer alteração.",
+        {
+          code: "PROMPT_CANCELLED",
+          exitCode: 130,
+        },
+      );
+    }
+  }
   const target = skillTarget(client, projectDirectory);
-  const entrypoint = mcpEntrypoint(context.toolDirectory);
   const configPath =
     client === "codex"
       ? await writeCodexConfiguration(
           projectDirectory,
-          entrypoint,
           context.envFile,
           workspaceId,
           options.force,
         )
       : await writeClaudeConfiguration(
           projectDirectory,
-          entrypoint,
           context.envFile,
           workspaceId,
           options.force,
@@ -173,6 +224,7 @@ async function configure(api, client, options, context) {
     configPath,
     skillTarget: target,
     installation,
+    mcpPackage: MCP_PACKAGE_SPEC,
     workspaceId,
   };
   if (options.json) console.log(JSON.stringify(result, null, 2));
@@ -197,14 +249,14 @@ async function requestStatus(url, headers = {}) {
   }
 }
 
-async function mcpStatus(entrypoint, envFile, workspaceId) {
+async function mcpStatus(envFile, workspaceId) {
   return new Promise((resolve) => {
-    const child = spawn(process.execPath, [entrypoint], {
+    const child = spawn(MCP_COMMAND, MCP_ARGS, {
       stdio: ["pipe", "pipe", "pipe"],
       env: {
         ...process.env,
         ...(envFile ? { BIAWS_ENV_FILE: envFile } : {}),
-        ISSUE_WORKSPACE_ID: workspaceId,
+        BIAWS_WORKSPACE_ID: workspaceId,
       },
     });
     let output = "";
@@ -222,9 +274,9 @@ async function mcpStatus(entrypoint, envFile, workspaceId) {
       () =>
         finish({
           ok: false,
-          detail: errorOutput.trim() || "MCP não respondeu em 5 segundos",
+          detail: errorOutput.trim() || "MCP não respondeu em 30 segundos",
         }),
-      5_000,
+      30_000,
     );
     child.stderr.on("data", (chunk) => {
       errorOutput += chunk;
@@ -283,22 +335,17 @@ async function mcpStatus(entrypoint, envFile, workspaceId) {
   });
 }
 
-function configurationStatus(
-  client,
-  contents,
-  entrypoint,
-  envFile,
-  workspaceId,
-) {
+function configurationStatus(client, contents, envFile, workspaceId) {
   if (typeof contents !== "string") {
     return { ok: false, detail: "Configuração MCP não encontrada" };
   }
   if (client === "codex") {
     const ok =
       contents.includes("[mcp_servers.biaws]") &&
-      contents.includes(JSON.stringify(entrypoint)) &&
+      contents.includes(`command = ${JSON.stringify(MCP_COMMAND)}`) &&
+      contents.includes(`args = ${JSON.stringify(MCP_ARGS)}`) &&
       (!envFile || contents.includes(JSON.stringify(envFile))) &&
-      contents.includes(`ISSUE_WORKSPACE_ID = ${JSON.stringify(workspaceId)}`);
+      contents.includes(`BIAWS_WORKSPACE_ID = ${JSON.stringify(workspaceId)}`);
     return {
       ok,
       detail: ok
@@ -309,10 +356,10 @@ function configurationStatus(
   try {
     const server = JSON.parse(contents).mcpServers?.biaws;
     const ok =
-      server?.command === "node" &&
-      JSON.stringify(server.args || []) === JSON.stringify([entrypoint]) &&
+      server?.command === MCP_COMMAND &&
+      JSON.stringify(server.args || []) === JSON.stringify(MCP_ARGS) &&
       (!envFile || server.env?.BIAWS_ENV_FILE === envFile) &&
-      server.env?.ISSUE_WORKSPACE_ID === workspaceId;
+      server.env?.BIAWS_WORKSPACE_ID === workspaceId;
     return {
       ok,
       detail: ok
@@ -336,11 +383,10 @@ async function doctor(api, client, options, context) {
     client === "codex"
       ? path.join(projectDirectory, ".codex", "config.toml")
       : path.join(projectDirectory, ".mcp.json");
-  const entrypoint = mcpEntrypoint(context.toolDirectory);
   const resolved = await resolveWorkspaceId(api, context.workspaceId);
   const [health, mcp, configContents, lock] = await Promise.all([
     requestStatus(`${context.apiUrl}/api/health`),
-    mcpStatus(entrypoint, context.envFile, resolved.workspaceId),
+    mcpStatus(context.envFile, resolved.workspaceId),
     readOptional(configPath, null),
     readLock(target),
   ]);
@@ -354,7 +400,6 @@ async function doctor(api, client, options, context) {
       ...configurationStatus(
         client,
         configContents,
-        entrypoint,
         context.envFile,
         resolved.workspaceId,
       ),

package/src/commands/configure/claude.js

@@ -1,7 +1,7 @@
 import { ProjectCommand } from "../../baseCommands.js";
 import {
   configureContextFlags,
-  configureContextInput,
+  interactiveConfigureInput,
   legacyAgentContext,
 } from "../../configure/command.js";
 import { runAgentCommand } from "../agent.js";
@@ -13,12 +13,18 @@ export default class ConfigureClaude extends ProjectCommand {
 
   async run() {
     const { flags } = await this.parse(ConfigureClaude);
-    const context = await this.projectContext(configureContextInput(flags));
+    const input = await interactiveConfigureInput(this, flags);
+    const context = await this.projectContext(input);
     await runAgentCommand(
       context.api,
       "configure",
       ["claude"],
-      { ...flags, project: context.projectDirectory },
+      {
+        ...flags,
+        interactive: input.interactive,
+        project: context.projectDirectory,
+        prompts: this.adapters.prompts,
+      },
       legacyAgentContext(context),
     );
   }

package/src/commands/configure/codex.js

@@ -1,7 +1,7 @@
 import { ProjectCommand } from "../../baseCommands.js";
 import {
   configureContextFlags,
-  configureContextInput,
+  interactiveConfigureInput,
   legacyAgentContext,
 } from "../../configure/command.js";
 import { runAgentCommand } from "../agent.js";
@@ -13,12 +13,18 @@ export default class ConfigureCodex extends ProjectCommand {
 
   async run() {
     const { flags } = await this.parse(ConfigureCodex);
-    const context = await this.projectContext(configureContextInput(flags));
+    const input = await interactiveConfigureInput(this, flags);
+    const context = await this.projectContext(input);
     await runAgentCommand(
       context.api,
       "configure",
       ["codex"],
-      { ...flags, project: context.projectDirectory },
+      {
+        ...flags,
+        interactive: input.interactive,
+        project: context.projectDirectory,
+        prompts: this.adapters.prompts,
+      },
       legacyAgentContext(context),
     );
   }

package/src/commands/instance/update.js

@@ -0,0 +1,164 @@
+import { Flags } from "@oclif/core";
+
+import { LocalInstanceCommand } from "../../baseCommands.js";
+import {
+  contextFlags,
+  contextInput,
+  instanceArgument,
+} from "../../instance/command.js";
+import {
+  backupArguments,
+  executeInstanceScript,
+  getInstance,
+  getInstanceUpdateStatus,
+  updateInstance,
+  validateInstanceUpdate,
+  withPasswordFile,
+} from "../../instance/service.js";
+
+function versionCheckResult(instance, versionStatus, json) {
+  if (json) return versionStatus;
+  return [
+    `Instância: ${instance.name}`,
+    `Versão atual: ${versionStatus.currentVersion}`,
+    `Nova versão: ${versionStatus.newVersion}`,
+    `Atualização necessária: ${versionStatus.updateRequired ? "sim" : "não"}`,
+  ].join("\n");
+}
+
+function unchangedResult(instance, versionStatus, json) {
+  return json
+    ? { ...versionStatus, updated: false, backupCreated: false }
+    : `Instância ${instance.name} já está na versão ${versionStatus.newVersion}.`;
+}
+
+async function createUpdateBackup(command, instance, context, flags) {
+  if (flags["skip-backup"]) return "";
+
+  let password;
+  if (!flags["password-file"]) {
+    if (!context.isInteractive) {
+      command.error(
+        "Atualização exige --password-file ou --skip-backup em modo não interativo.",
+        { code: "BACKUP_PASSWORD_REQUIRED", exit: 2 },
+      );
+    }
+    password = await command.adapters.prompts.ask({
+      name: "password",
+      type: "password",
+      message: "Senha do backup anterior à atualização",
+    });
+  }
+
+  return withPasswordFile(
+    command.adapters.filesystem,
+    password,
+    flags["password-file"],
+    async (passwordFile) =>
+      executeInstanceScript(
+        backupArguments(instance, context, {
+          output: flags["backup-output"],
+          passwordFile,
+        }),
+        context,
+        command.adapters.processRunner,
+        { secrets: password ? [password] : [], silent: flags.json },
+      ),
+  );
+}
+
+function updatedResult(instance, versionStatus, flags, backupOutput) {
+  if (!flags.json) {
+    return `Instância ${instance.name} atualizada de ${versionStatus.currentVersion} para ${versionStatus.newVersion}. UI: ${instance.publicUrl}`;
+  }
+  return {
+    instance: instance.name,
+    operation: "update",
+    currentVersion: versionStatus.currentVersion,
+    newVersion: versionStatus.newVersion,
+    updateRequired: versionStatus.updateRequired,
+    updated: true,
+    backupCreated: !flags["skip-backup"],
+    backupOutput,
+    ui: instance.publicUrl,
+  };
+}
+
+export default class InstanceUpdate extends LocalInstanceCommand {
+  static description =
+    "reconstrói e atualiza os serviços preservando os dados da instância";
+  static args = { instance: instanceArgument };
+  static flags = {
+    ...contextFlags,
+    "backup-output": Flags.string({
+      description: "arquivo de destino do backup anterior à atualização",
+    }),
+    "password-file": Flags.string({
+      description: "arquivo privado contendo a senha do backup",
+    }),
+    "skip-backup": Flags.boolean({
+      description: "atualiza sem criar o backup de segurança",
+      exclusive: ["backup-output", "password-file"],
+    }),
+    check: Flags.boolean({
+      description: "compara a versão instalada com a versão da release",
+      exclusive: ["backup-output", "password-file", "skip-backup", "force"],
+    }),
+    force: Flags.boolean({
+      description: "reconstrói mesmo quando a instância já está na versão nova",
+      exclusive: ["check"],
+    }),
+    json: Flags.boolean({ description: "emite resultado JSON" }),
+  };
+
+  async run() {
+    const { args, flags } = await this.parse(InstanceUpdate);
+    const context = await this.localContext(contextInput(flags, args.instance));
+    const instance = await getInstance(
+      context,
+      this.adapters.filesystem,
+      args.instance,
+    );
+    const versionStatus = await getInstanceUpdateStatus(
+      instance,
+      context,
+      this.adapters.filesystem,
+    );
+    if (flags.check) {
+      this.output({ json: flags.json }).result(
+        versionCheckResult(instance, versionStatus, flags.json),
+      );
+      return;
+    }
+    if (!versionStatus.updateRequired && !flags.force) {
+      this.output({ json: flags.json }).result(
+        unchangedResult(instance, versionStatus, flags.json),
+      );
+      return;
+    }
+
+    await validateInstanceUpdate(
+      instance,
+      context,
+      this.adapters.processRunner,
+    );
+    const backupOutput = await createUpdateBackup(
+      this,
+      instance,
+      context,
+      flags,
+    );
+
+    await updateInstance(
+      instance,
+      context,
+      this.adapters.filesystem,
+      this.adapters.processRunner,
+      versionStatus.newVersion,
+      this.adapters.environment,
+    );
+    this.output({ json: flags.json }).result(
+      updatedResult(instance, versionStatus, flags, backupOutput),
+    );
+  }
+}

package/src/commands/instance.js

@@ -8,6 +8,7 @@ export default class Instance extends LocalInstanceCommand {
   static examples = [
     "<%= config.bin %> instance setup",
     "<%= config.bin %> instance status",
+    "<%= config.bin %> instance update",
     "<%= config.bin %> instance backup",
   ];
 

package/src/configuration/commands.js

@@ -52,7 +52,7 @@ function credentialsWithKey(configuration, name, apiKey) {
 async function requiredApiKey(command) {
   const fromEnvironment = String(
     command.adapters.environment.BIAWS_API_KEY ||
-      command.adapters.environment.ISSUE_API_KEY ||
+      command.adapters.environment.BIAWS_API_KEY ||
       "",
   ).trim();
   if (fromEnvironment) return fromEnvironment;

package/src/configure/command.js

@@ -2,6 +2,8 @@ import path from "node:path";
 
 import { Args, Flags } from "@oclif/core";
 
+import { CliError } from "../core/errors.js";
+
 export const configureContextFlags = Object.freeze({
   project: Flags.string({
     char: "p",
@@ -16,6 +18,12 @@ export const configureContextFlags = Object.freeze({
   "env-file": Flags.string({
     description: "arquivo privado com URL e chave de API",
   }),
+  interactive: Flags.boolean({
+    char: "i",
+    allowNo: true,
+    description:
+      "usa o modo assistente (padrão em terminais; use --no-interactive para desativar)",
+  }),
   force: Flags.boolean({
     char: "f",
     description: "substitui somente a configuração BIAWS conflitante",
@@ -23,6 +31,46 @@ export const configureContextFlags = Object.freeze({
   json: Flags.boolean({ description: "emite somente JSON em stdout" }),
 });
 
+export async function interactiveConfigureInput(command, flags) {
+  const interactive =
+    flags.interactive === true ||
+    (flags.interactive !== false && command.adapters.terminal.isInteractive);
+  if (!interactive) {
+    return { ...configureContextInput(flags), interactive: false };
+  }
+  if (!command.adapters.prompts.isInteractive) {
+    throw new CliError("O modo assistente exige um terminal interativo.", {
+      code: "INTERACTIVE_INPUT_UNAVAILABLE",
+      exitCode: 2,
+    });
+  }
+  const project = String(
+    await command.adapters.prompts.ask({
+      name: "project",
+      message: "Diretório do projeto",
+      default: flags.project || command.adapters.cwd(),
+    }),
+  ).trim();
+  const envFile = String(
+    await command.adapters.prompts.ask({
+      name: "envFile",
+      message: "Arquivo privado da instância (BIAWS_ENV_FILE)",
+      default:
+        flags["env-file"] || command.adapters.environment.BIAWS_ENV_FILE || "",
+    }),
+  ).trim();
+  if (!envFile) {
+    throw new CliError("Informe o arquivo privado da instância.", {
+      code: "ENV_FILE_REQUIRED",
+      exitCode: 2,
+    });
+  }
+  return {
+    ...configureContextInput({ ...flags, project, "env-file": envFile }),
+    interactive: true,
+  };
+}
+
 export const clientArgument = Args.string({
   description: "cliente a diagnosticar",
   options: ["codex", "claude"],

package/src/core/context.js

@@ -126,32 +126,31 @@ export async function resolveCommandContext(options) {
   const configuredApiUrl =
     input.apiUrl ||
     explicitFileEnv.BIAWS_API_URL ||
-    explicitFileEnv.ISSUE_API_URL ||
+    explicitFileEnv.BIAWS_API_URL ||
+    environment.BIAWS_API_URL ||
     environment.BIAWS_API_URL ||
-    environment.ISSUE_API_URL ||
-    environment.ISSUE_API_BASE_URL ||
+    environment.BIAWS_API_BASE_URL ||
     workspaceConfiguration.apiUrl ||
     profile.config.apiUrl ||
-    effectiveEnv.ISSUE_API_URL ||
-    effectiveEnv.ISSUE_API_BASE_URL ||
+    effectiveEnv.BIAWS_API_URL ||
+    effectiveEnv.BIAWS_API_BASE_URL ||
     DEFAULT_API_URL;
   const configuredApiKey = String(
     input.apiKey ||
       explicitFileEnv.BIAWS_API_KEY ||
-      explicitFileEnv.ISSUE_API_KEY ||
+      explicitFileEnv.BIAWS_API_KEY ||
+      environment.BIAWS_API_KEY ||
       environment.BIAWS_API_KEY ||
-      environment.ISSUE_API_KEY ||
       profile.credentials.apiKey ||
-      effectiveEnv.ISSUE_API_KEY ||
+      effectiveEnv.BIAWS_API_KEY ||
       "",
   );
   const configuredWorkspaceId = String(
     input.workspaceId ||
       input.workspace ||
       environment.BIAWS_WORKSPACE_ID ||
-      environment.ISSUE_WORKSPACE_ID ||
       workspaceConfiguration.workspaceId ||
-      effectiveEnv.ISSUE_WORKSPACE_ID ||
+      effectiveEnv.BIAWS_WORKSPACE_ID ||
       "",
   ).trim();
 

package/src/instance/service.js

@@ -6,8 +6,8 @@ import { parseEnv } from "../core/context.js";
 
 const PORT_FIELDS = Object.freeze({
   mongoPort: "MONGO_PORT",
-  apiPort: "ISSUE_API_PORT",
-  uiPort: "ISSUE_UI_PORT",
+  apiPort: "BIAWS_API_PORT",
+  uiPort: "BIAWS_UI_PORT",
 });
 
 const STORAGE_FIELDS = Object.freeze({
@@ -18,6 +18,8 @@ const STORAGE_FIELDS = Object.freeze({
   secretPath: "BIAWS_SECRET_FILES_PATH",
 });
 
+const UNKNOWN_VERSION = "unknown";
+
 function usageError(message, code, details) {
   throw new CliError(message, { code, details, exitCode: 2 });
 }
@@ -141,11 +143,11 @@ export async function listInstances(context, filesystem) {
       directory,
       envFile: path.join(directory, ".env"),
       mongoPort: Number(env.MONGO_PORT || 27_017),
-      apiPort: Number(env.ISSUE_API_PORT || 3_100),
-      uiPort: Number(env.ISSUE_UI_PORT || 4_400),
+      apiPort: Number(env.BIAWS_API_PORT || 3_100),
+      uiPort: Number(env.BIAWS_UI_PORT || 4_400),
       publicUrl:
         env.BIAWS_PUBLIC_URL ||
-        `http://localhost:${env.ISSUE_UI_PORT || 4_400}`,
+        `http://localhost:${env.BIAWS_UI_PORT || 4_400}`,
       storage: Object.values(STORAGE_FIELDS).some((key) => env[key])
         ? "directories"
         : "volumes",
@@ -176,6 +178,50 @@ export async function getInstance(context, filesystem, name) {
   return instance;
 }
 
+function normalizeVersion(value, label) {
+  const version = String(value || "").trim();
+  if (
+    !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u.test(version)
+  ) {
+    throw new CliError(`${label} inválida: ${version || "ausente"}.`, {
+      code: "INVALID_RELEASE_VERSION",
+    });
+  }
+  return version;
+}
+
+export async function getInstanceUpdateStatus(instance, context, filesystem) {
+  const manifestPath = path.join(
+    context.repositoryRoot,
+    "biaws-cli",
+    "package.json",
+  );
+  let manifest;
+  try {
+    manifest = JSON.parse(await filesystem.readFile(manifestPath, "utf8"));
+  } catch (error) {
+    throw new CliError(
+      `Não foi possível ler a versão da release em ${manifestPath}.`,
+      {
+        code: "RELEASE_VERSION_READ_FAILED",
+        cause: error,
+      },
+    );
+  }
+  const newVersion = normalizeVersion(manifest.version, "Versão da release");
+  const installed = String(instance.env.BIAWS_VERSION || "").trim();
+  const currentVersion =
+    installed && installed !== UNKNOWN_VERSION
+      ? normalizeVersion(installed, "Versão instalada")
+      : UNKNOWN_VERSION;
+  return Object.freeze({
+    instance: instance.name,
+    currentVersion,
+    newVersion,
+    updateRequired: currentVersion !== newVersion,
+  });
+}
+
 function resolveStorage(values, existing) {
   if (values.storage === "volumes") {
     if (Object.keys(STORAGE_FIELDS).some((field) => values[field])) {
@@ -396,6 +442,8 @@ export function composeArguments(instance, context, operation) {
     `biaws-${instance.name}`,
   ];
   if (operation === "start") return [...base, "up", "-d", "--wait"];
+  if (operation === "update") return [...base, "up", "-d", "--build", "--wait"];
+  if (operation === "validate") return [...base, "config", "--quiet"];
   if (operation === "stop") return [...base, "stop"];
   return [...base, "ps", "--format", "json"];
 }
@@ -405,15 +453,49 @@ export async function operateInstance(
   context,
   processRunner,
   operation,
+  options = {},
 ) {
   const result = await processRunner.run(
     "docker",
     composeArguments(instance, context, operation),
-    { cwd: context.repositoryRoot, silent: true },
+    {
+      cwd: context.repositoryRoot,
+      env: options.environment,
+      silent: true,
+    },
   );
   return { instance: instance.name, operation, output: result.stdout.trim() };
 }
 
+export async function validateInstanceUpdate(instance, context, processRunner) {
+  return operateInstance(instance, context, processRunner, "validate");
+}
+
+export async function updateInstance(
+  instance,
+  context,
+  filesystem,
+  processRunner,
+  version,
+  environment = {},
+) {
+  const normalizedVersion = normalizeVersion(version, "Nova versão");
+  const result = await operateInstance(
+    instance,
+    context,
+    processRunner,
+    "update",
+    { environment: { ...environment, BIAWS_VERSION: normalizedVersion } },
+  );
+  const envContents = await filesystem.readFile(instance.envFile, "utf8");
+  const versionLine = `BIAWS_VERSION=${normalizedVersion}`;
+  const nextEnv = /^BIAWS_VERSION=.*$/mu.test(envContents)
+    ? envContents.replace(/^BIAWS_VERSION=.*$/gmu, versionLine)
+    : `${envContents.replace(/\s*$/u, "")}\n${versionLine}\n`;
+  await filesystem.writeFile(instance.envFile, nextEnv, { mode: 0o600 });
+  return result;
+}
+
 export function validateArchivePath(value) {
   const archive = path.resolve(String(value || ""));
   if (!value || archive === path.parse(archive).root) {