biaws 0.4.0 → 0.5.0

package/README.md

@@ -15,8 +15,8 @@ Uma execução descartável pode usar `npx biaws help`. Em um checkout de
 desenvolvimento, `npm --prefix biaws-cli link` cria o mesmo comando global.
 
 O pacote requer Node.js 20.19 ou superior. Operações administrativas de
-instância também exigem Git, Docker e Docker Compose. Windows é suportado por
-WSL2, não de forma nativa.
+instância também exigem Git, Bash, `curl`, OpenSSL, `tar`, Docker e Docker
+Compose. Windows é suportado por WSL2, não de forma nativa.
 
 ## Organização
 
@@ -123,7 +123,7 @@ biaws workspace api PATCH /recurso/ID --body '{"status":"Ativo"}'
 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 agent doctor codex --env-file /caminho/instancia.env
 biaws workspace skills list
 biaws workspace skills install SKILL_ID
 biaws workspace skills update
@@ -158,13 +158,14 @@ Diagnostique os pré-requisitos e baixe uma release verificada:
 
 ```bash
 biaws admin doctor
-biaws admin install --version 1.0.0 --dry-run
-biaws admin install --version 1.0.0 --directory /opt/biaws
+biaws admin install --version <versão> --dry-run
+biaws admin install --version <versão> --directory /opt/biaws
 ```
 
 O instalador busca `biaws-<versão>.tar.gz` e seu arquivo `.sha256` na release do
 GitHub. Ele recusa diretórios não vazios e extrai somente depois de verificar o
-checksum.
+checksum. Use somente uma versão que possua esses dois assets publicados; o
+pacote npm isolado não contém o runtime Docker.
 
 Gerencie as instâncias:
 

package/docs/instance-lifecycle.md

@@ -52,10 +52,18 @@ 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.
+O resultado informa `currentVersion`, `newVersion`, `updateRequired`,
+`legacyInstallation`, `installedRelease`, `availableRelease` e `differences`.
+Cada diferença contém `field`, `current` e `available`; a saída textual também
+mostra as alterações. O manifesto `release.json` do checkout descreve a versão
+da plataforma, a revisão de implantação e as versões de API, UI e executor.
+Qualquer diferença nesses campos exige atualização, mesmo com a mesma versão
+geral. A versão do CLI e a do MCP não participam dessa comparação.
+
+Instâncias sem `instances/<nome>/release.json` são legadas e exigem atualização,
+mesmo com `BIAWS_VERSION` igual. Um snapshot inválido causa erro explícito.
+Quando o manifesto é igual, não há backup nem reconstrução; `--force` permite
+repetir o deploy. `--check` é somente leitura e não precisa executar Docker.
 
 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
@@ -70,10 +78,19 @@ 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`.
+O manifesto aplicado só é registrado depois que `up -d --build --wait` termina
+com sucesso. O update inclui o executor local já existente no projeto Compose;
+executores externos continuam sendo atualizados separadamente. Cada arquivo de
+estado é substituído atomicamente, preservando o `.env` e suas permissões
+privadas. Se o deploy falhar, o snapshot anterior permanece. Se a gravação do
+estado falhar após o deploy, o comando falha e deve ser repetido para reconciliar.
+
+`release.json` vem da raiz selecionada por `--root`/`BIAWS_ROOT` e deve estar
+sincronizado com os pacotes. Sua `version` é exposta pelo `/api/health` e pelos
+labels de API e UI. O setup registra o mesmo snapshot após o bootstrap; com
+`--skip-bootstrap`, ele não registra uma release. O restore invalida o snapshot
+porque não restaura imagens: execute update no checkout desejado depois dele.
+Consulte [o guia de versões](../../docs/versions.md) para preparar uma release.
 
 ## Smoke test Docker real
 

package/docs/releasing.md

@@ -84,9 +84,10 @@ ordem, em uma instância isolada:
 
 1. `biaws --help` e `biaws --version` pela instalação empacotada;
 2. `biaws admin instance setup` e `biaws workspace agent configure codex|claude` com `BIAWS_ROOT`;
-3. uma consulta `workspaces list --json` e outra por código, como
-   `demands get <código> --json`;
-4. uma escrita idempotente com `demands task-status ... --yes --json`, seguida
+3. uma consulta `biaws workspace list --json` e outra por código, como
+   `biaws workspace demands get <código> --json`;
+4. uma escrita idempotente com `biaws workspace demands task-status ... --yes
+--json`, seguida
    de nova leitura;
 5. `biaws admin instance backup`, restore em uma instância de destino e validação de
    API/UI;

package/package.json

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

package/shared/skillPackage.js

@@ -15,11 +15,8 @@ async function collectFiles(root, current = root, result = []) {
   entries.sort((a, b) => a.name.localeCompare(b.name));
   for (const entry of entries) {
     const absolutePath = path.join(current, entry.name);
-    const relativePath = normalizeRelativePath(
-      path.relative(root, absolutePath),
-    );
-    if (entry.isSymbolicLink())
-      throw new Error(`Links simbólicos não são permitidos: ${relativePath}`);
+    const relativePath = normalizeRelativePath(path.relative(root, absolutePath));
+    if (entry.isSymbolicLink()) throw new Error(`Links simbólicos não são permitidos: ${relativePath}`);
     if (entry.isDirectory()) await collectFiles(root, absolutePath, result);
     else if (entry.isFile()) result.push({ absolutePath, path: relativePath });
   }
@@ -43,38 +40,28 @@ function extractFrontmatter(markdown) {
 export async function buildSkillPayload(directory, options = {}) {
   const root = path.resolve(directory);
   const stats = await lstat(root);
-  if (!stats.isDirectory())
-    throw new Error(`Diretório de skill inválido: ${root}`);
+  if (!stats.isDirectory()) throw new Error(`Diretório de skill inválido: ${root}`);
   const entries = await collectFiles(root);
   if (!entries.some((entry) => entry.path === "SKILL.md")) {
     throw new Error(`SKILL.md não encontrado em ${root}`);
   }
-  if (entries.length > MAX_FILES)
-    throw new Error(`A skill excede o limite de ${MAX_FILES} arquivos`);
+  if (entries.length > MAX_FILES) throw new Error(`A skill excede o limite de ${MAX_FILES} arquivos`);
 
   let totalBytes = 0;
   const files = [];
   for (const entry of entries) {
     const content = await readFile(entry.absolutePath);
-    if (content.length > MAX_FILE_BYTES)
-      throw new Error(`Arquivo excede ${MAX_FILE_BYTES} bytes: ${entry.path}`);
+    if (content.length > MAX_FILE_BYTES) throw new Error(`Arquivo excede ${MAX_FILE_BYTES} bytes: ${entry.path}`);
     totalBytes += content.length;
-    if (totalBytes > MAX_PACKAGE_BYTES)
-      throw new Error(`A skill excede o limite de ${MAX_PACKAGE_BYTES} bytes`);
+    if (totalBytes > MAX_PACKAGE_BYTES) throw new Error(`A skill excede o limite de ${MAX_PACKAGE_BYTES} bytes`);
     files.push({ path: entry.path, contentBase64: content.toString("base64") });
   }
   const skillMarkdown = await readFile(path.join(root, "SKILL.md"), "utf8");
   const frontmatter = extractFrontmatter(skillMarkdown);
-  const skillId = String(
-    options.id || frontmatter.name || path.basename(root),
-  ).trim();
-  const description = String(
-    options.description || frontmatter.description || "",
-  ).trim();
+  const skillId = String(options.id || frontmatter.name || path.basename(root)).trim();
+  const description = String(options.description || frontmatter.description || "").trim();
   if (!description) {
-    throw new Error(
-      "Descrição ausente; informe --description ou adicione description ao SKILL.md",
-    );
+    throw new Error("Descrição ausente; informe --description ou adicione description ao SKILL.md");
   }
   return {
     skillId,

package/src/admin/commands.js

@@ -50,6 +50,10 @@ export class AdminDoctorCommand extends BaseCommand {
     const checks = [
       { name: "Node.js", command: "node", args: ["--version"] },
       { name: "Git", command: "git", args: ["--version"] },
+      { name: "Bash", command: "bash", args: ["--version"] },
+      { name: "curl", command: "curl", args: ["--version"] },
+      { name: "OpenSSL", command: "openssl", args: ["version"] },
+      { name: "tar", command: "tar", args: ["--version"] },
       { name: "Docker", command: "docker", args: ["--version"] },
       {
         name: "Docker Compose",
@@ -60,11 +64,7 @@ export class AdminDoctorCommand extends BaseCommand {
     const items = [];
     for (const check of checks) {
       try {
-        const result = await this.adapters.processRunner.run(
-          check.command,
-          check.args,
-          { silent: true },
-        );
+        const result = await this.adapters.processRunner.run(check.command, check.args, { silent: true });
         items.push({
           name: check.name,
           status: "disponível",
@@ -84,12 +84,7 @@ export class AdminDoctorCommand extends BaseCommand {
       this,
       flags.json,
       { healthy, items },
-      items
-        .map(
-          (item) =>
-            `${item.name}: ${item.status}${item.version ? ` (${item.version})` : ""}`,
-        )
-        .join("\n"),
+      items.map((item) => `${item.name}: ${item.status}${item.version ? ` (${item.version})` : ""}`).join("\n"),
     );
   }
 }
@@ -103,13 +98,10 @@ async function ensureEmptyDirectory(filesystem, directory) {
   try {
     const entries = await filesystem.readdir(directory);
     if (entries.length) {
-      throw new CliError(
-        `O diretório de destino não está vazio: ${directory}.`,
-        {
-          code: "INSTALL_DIRECTORY_NOT_EMPTY",
-          exitCode: 2,
-        },
-      );
+      throw new CliError(`O diretório de destino não está vazio: ${directory}.`, {
+        code: "INSTALL_DIRECTORY_NOT_EMPTY",
+        exitCode: 2,
+      });
     }
   } catch (error) {
     if (error.code !== "ENOENT") throw error;
@@ -136,10 +128,7 @@ async function expectedChecksum(url, explicit) {
       { code: "INSTALL_CHECKSUM_REQUIRED" },
     );
   }
-  return (await response.text())
-    .trim()
-    .split(/\s+/u)[0]
-    .toLocaleLowerCase("en-US");
+  return (await response.text()).trim().split(/\s+/u)[0].toLocaleLowerCase("en-US");
 }
 
 export class AdminInstallCommand extends BaseCommand {
@@ -161,18 +150,11 @@ export class AdminInstallCommand extends BaseCommand {
   async run() {
     const { flags } = await this.parse(this.constructor);
     const version = flags.version || this.config.version;
-    const directory = path.resolve(
-      flags.directory || path.join(this.adapters.cwd(), `biaws-${version}`),
-    );
+    const directory = path.resolve(flags.directory || path.join(this.adapters.cwd(), `biaws-${version}`));
     const url = githubArchive(flags.repository, version);
     const plan = { directory, source: url, version };
     if (flags["dry-run"]) {
-      emit(
-        this,
-        flags.json,
-        { ...plan, dryRun: true },
-        `Release v${version}\nOrigem: ${url}\nDestino: ${directory}`,
-      );
+      emit(this, flags.json, { ...plan, dryRun: true }, `Release v${version}\nOrigem: ${url}\nDestino: ${directory}`);
       return;
     }
     await ensureEmptyDirectory(this.adapters.filesystem, directory);
@@ -180,24 +162,15 @@ export class AdminInstallCommand extends BaseCommand {
     const checksum = await expectedChecksum(url, flags.checksum);
     const actual = createHash("sha256").update(archive).digest("hex");
     if (actual !== checksum) {
-      throw new CliError(
-        `Checksum inválido: esperado ${checksum}, obtido ${actual}.`,
-        { code: "INSTALL_CHECKSUM_MISMATCH" },
-      );
+      throw new CliError(`Checksum inválido: esperado ${checksum}, obtido ${actual}.`, {
+        code: "INSTALL_CHECKSUM_MISMATCH",
+      });
     }
-    const temporary = await this.adapters.filesystem.mkdtemp(
-      path.join(tmpdir(), "biaws-install-"),
-    );
+    const temporary = await this.adapters.filesystem.mkdtemp(path.join(tmpdir(), "biaws-install-"));
     const archivePath = path.join(temporary, "biaws.tar.gz");
     try {
       await this.adapters.filesystem.writeFile(archivePath, archive);
-      await this.adapters.processRunner.run("tar", [
-        "-xzf",
-        archivePath,
-        "--strip-components=1",
-        "-C",
-        directory,
-      ]);
+      await this.adapters.processRunner.run("tar", ["-xzf", archivePath, "--strip-components=1", "-C", directory]);
     } finally {
       await this.adapters.filesystem.rm(temporary, {
         recursive: true,

package/src/admin/monitoringCommands.js

@@ -39,11 +39,7 @@ export function createAdminMonitoringCommand(action) {
         instance: flags.instance,
         root: flags.root,
       });
-      const script = path.join(
-        context.repositoryRoot,
-        "scripts",
-        "manage-monitoring-workspaces.sh",
-      );
+      const script = path.join(context.repositoryRoot, "scripts", "manage-monitoring-workspaces.sh");
       await this.adapters.processRunner.run("bash", [
         script,
         "--instance",
@@ -56,8 +52,7 @@ export function createAdminMonitoringCommand(action) {
 }
 
 export class AdminMonitoringProvisionCommand extends LocalInstanceCommand {
-  static description =
-    "provisiona a identidade técnica de monitoramento de um workspace";
+  static description = "provisiona a identidade técnica de monitoramento de um workspace";
   static args = {
     workspace: Args.string({
       description: "identificador local do workspace",
@@ -72,11 +67,7 @@ export class AdminMonitoringProvisionCommand extends LocalInstanceCommand {
       instance: flags.instance,
       root: flags.root,
     });
-    const script = path.join(
-      context.repositoryRoot,
-      "scripts",
-      "provision-monitoring-workspace.mjs",
-    );
+    const script = path.join(context.repositoryRoot, "scripts", "provision-monitoring-workspace.mjs");
     await this.adapters.processRunner.run("node", [
       script,
       "--instance",

package/src/apiClient.js

@@ -40,22 +40,14 @@ export function createApiClient(baseUrl, apiKey, workspaceId = "") {
   }
 
   return {
-    withWorkspace: (selectedWorkspaceId) =>
-      createApiClient(baseUrl, apiKey, selectedWorkspaceId),
+    withWorkspace: (selectedWorkspaceId) => createApiClient(baseUrl, apiKey, selectedWorkspaceId),
     request: (path, options = {}) => request(path, options, apiRoot),
     identity: () => request("/auth/me", {}, apiRoot),
-    list: (options = {}) =>
-      request(options.includeDeprecated ? "?includeDeprecated=true" : ""),
+    list: (options = {}) => request(options.includeDeprecated ? "?includeDeprecated=true" : ""),
     get: (skillId, version) =>
-      request(
-        `/${encodeURIComponent(skillId)}${version ? `?version=${encodeURIComponent(version)}` : ""}`,
-      ),
-    download: (skillId, version) =>
-      request(
-        `/${encodeURIComponent(skillId)}/${encodeURIComponent(version)}/download`,
-      ),
-    publish: (payload) =>
-      request("", { method: "POST", body: JSON.stringify(payload) }),
+      request(`/${encodeURIComponent(skillId)}${version ? `?version=${encodeURIComponent(version)}` : ""}`),
+    download: (skillId, version) => request(`/${encodeURIComponent(skillId)}/${encodeURIComponent(version)}/download`),
+    publish: (payload) => request("", { method: "POST", body: JSON.stringify(payload) }),
     monitoring: {
       describeTemplate: (templateId, version) =>
         request(

package/src/baseCommands.js

@@ -1,36 +1,16 @@
-import {
-  access,
-  chmod,
-  mkdtemp,
-  mkdir,
-  readFile,
-  readdir,
-  stat,
-  rm,
-  writeFile,
-} from "node:fs/promises";
+import { access, chmod, mkdtemp, mkdir, readFile, readdir, rename, stat, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { Command } from "@oclif/core";
 
 import { createApiClient } from "./apiClient.js";
-import {
-  resolveAuthenticatedContext,
-  resolveCommandContext,
-} from "./core/context.js";
+import { resolveAuthenticatedContext, resolveCommandContext } from "./core/context.js";
 import { ProcessRunner } from "./core/processRunner.js";
 import { createPromptAdapter } from "./core/prompts.js";
-import {
-  CliLogger,
-  CliOutput,
-  createTerminalAdapter,
-} from "./core/terminal.js";
+import { CliLogger, CliOutput, createTerminalAdapter } from "./core/terminal.js";
 
-export const TOOL_DIRECTORY = path.resolve(
-  path.dirname(fileURLToPath(import.meta.url)),
-  "..",
-);
+export const TOOL_DIRECTORY = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
 export function createCommandAdapters(overrides = {}) {
   const environment = overrides.environment || { ...process.env };
@@ -41,6 +21,7 @@ export function createCommandAdapters(overrides = {}) {
     mkdir,
     readFile,
     readdir,
+    rename,
     stat,
     rm,
     writeFile,
@@ -53,8 +34,7 @@ export function createCommandAdapters(overrides = {}) {
       stdout: terminal.stdout,
       stderr: terminal.stderr,
     });
-  const prompts =
-    overrides.prompts || createPromptAdapter(terminal, overrides.promptOptions);
+  const prompts = overrides.prompts || createPromptAdapter(terminal, overrides.promptOptions);
   return Object.freeze({
     apiFactory: overrides.apiFactory || createApiClient,
     cwd: overrides.cwd || (() => process.cwd()),
@@ -110,11 +90,7 @@ export class AuthenticatedApiCommand extends BaseCommand {
     });
     return Object.freeze({
       ...context,
-      api: this.adapters.apiFactory(
-        context.apiUrl,
-        context.apiKey,
-        context.workspaceId,
-      ),
+      api: this.adapters.apiFactory(context.apiUrl, context.apiKey, context.workspaceId),
     });
   }
 }

package/src/commandFactories.js

@@ -40,13 +40,8 @@ export function createSkillsCommand(action, definition = {}) {
 
     async run() {
       const { args, flags } = await this.parse(this.constructor);
-      const context = await this.authenticatedContext(
-        authenticatedInput(flags),
-        { requireWorkspace: true },
-      );
-      const positional = definition.positional
-        ? definition.positional(args)
-        : [];
+      const context = await this.authenticatedContext(authenticatedInput(flags), { requireWorkspace: true });
+      const positional = definition.positional ? definition.positional(args) : [];
       await runSkillsCommand(context.api, action, positional, flags);
     }
   };
@@ -60,13 +55,8 @@ export function createMonitoringCommand(action, definition = {}) {
 
     async run() {
       const { args, flags } = await this.parse(this.constructor);
-      const context = await this.authenticatedContext(
-        authenticatedInput(flags),
-        { requireWorkspace: true },
-      );
-      const positional = definition.positional
-        ? definition.positional(args)
-        : [];
+      const context = await this.authenticatedContext(authenticatedInput(flags), { requireWorkspace: true });
+      const positional = definition.positional ? definition.positional(args) : [];
       await runMonitoringCommand(context.api, action, positional, flags);
     }
   };
@@ -87,9 +77,7 @@ export function createAgentCommand(action) {
     async run() {
       const { args, flags } = await this.parse(this.constructor);
       const input =
-        action === "configure"
-          ? await interactiveConfigureInput(this, flags)
-          : configureContextInput(flags);
+        action === "configure" ? await interactiveConfigureInput(this, flags) : configureContextInput(flags);
       const context = await this.projectContext(input);
       await runAgentCommand(
         context.api,