biaws 0.2.1 → 0.2.2

package/README.md

@@ -131,7 +131,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 +173,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

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.2.2",
   "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/commands/agent.js

@@ -9,6 +9,11 @@ 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.1.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 +23,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 +48,6 @@ async function readOptional(filePath, fallback = "") {
 
 async function writeCodexConfiguration(
   projectDirectory,
-  entrypoint,
   envFile,
   workspaceId,
   force,
@@ -59,8 +73,8 @@ async function writeCodexConfiguration(
   }
   const managed = `${CODEX_BEGIN}
 [mcp_servers.biaws]
-command = "node"
-args = [${JSON.stringify(entrypoint)}]
+command = ${JSON.stringify(MCP_COMMAND)}
+args = ${JSON.stringify(MCP_ARGS)}
 env = {${envFile ? ` BIAWS_ENV_FILE = ${JSON.stringify(envFile)},` : ""} ISSUE_WORKSPACE_ID = ${JSON.stringify(workspaceId)} }
 ${CODEX_END}
 `;
@@ -71,7 +85,6 @@ ${CODEX_END}
 
 async function writeClaudeConfiguration(
   projectDirectory,
-  entrypoint,
   envFile,
   workspaceId,
   force,
@@ -85,21 +98,19 @@ 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,
@@ -144,19 +155,16 @@ async function configure(api, client, options, context) {
   const projectDirectory = path.resolve(options.project || process.cwd());
   const { workspaceId } = await resolveWorkspaceId(api, context.workspaceId);
   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 +181,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,9 +206,9 @@ 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,
@@ -222,9 +231,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,20 +292,15 @@ 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)}`);
     return {
@@ -309,8 +313,8 @@ 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;
     return {
@@ -336,11 +340,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 +357,6 @@ async function doctor(api, client, options, context) {
       ...configurationStatus(
         client,
         configContents,
-        entrypoint,
         context.envFile,
         resolved.workspaceId,
       ),

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/instance/service.js

@@ -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 });
 }
@@ -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) {