biaws 0.1.0

package/src/commands/monitoring.js

@@ -0,0 +1,163 @@
+import { BaseCommand } from "../baseCommands.js";
+import { showTopic } from "../compatibilityCommands.js";
+
+function parseMetadata(value) {
+  if (!value) return {};
+  let metadata;
+  try {
+    metadata = JSON.parse(value);
+  } catch {
+    throw new Error("--metadata deve conter um objeto JSON válido.");
+  }
+  if (!metadata || Array.isArray(metadata) || typeof metadata !== "object") {
+    throw new Error("--metadata deve conter um objeto JSON.");
+  }
+  return metadata;
+}
+
+function parsePayload(value) {
+  if (!value) return undefined;
+  try {
+    return JSON.parse(value);
+  } catch {
+    throw new Error("--payload deve conter JSON válido.");
+  }
+}
+
+function printSignal(result) {
+  const state = result.created ? "registrado" : "já recebido";
+  console.log(
+    `Sinal ${state}: runtime ${result.signal.runtimeId} está ${result.signal.status} (${result.signal.source}).`,
+  );
+}
+
+function buildSignalPayload(options) {
+  if (!options.source) throw new Error("Informe --source.");
+  const templateId = options.template;
+  const templateVersion = options["template-version"];
+  if (Boolean(templateId) !== Boolean(templateVersion)) {
+    throw new Error("Informe --template e --template-version juntos.");
+  }
+  if (!templateId && !options.status) throw new Error("Informe --status.");
+  if (templateId && !options.payload) {
+    throw new Error("Informe --payload ao usar um template.");
+  }
+  return {
+    ...(options.status ? { status: options.status } : {}),
+    source: options.source,
+    ...(options["signal-id"] ? { signalId: options["signal-id"] } : {}),
+    ...(options["observed-at"] ? { observedAt: options["observed-at"] } : {}),
+    ...(options.message ? { message: options.message } : {}),
+    ...(options["metadata-profile"]
+      ? { metadataProfile: options["metadata-profile"] }
+      : {}),
+    ...(templateId
+      ? { templateRef: { id: templateId, version: templateVersion } }
+      : {}),
+    metadata: parseMetadata(options.metadata),
+    ...(options.payload ? { payload: parsePayload(options.payload) } : {}),
+  };
+}
+
+function requiredTemplate(options) {
+  const templateId = options.template;
+  const version = options["template-version"] || options.version;
+  if (!templateId) throw new Error("Informe --template.");
+  if (!version) throw new Error("Informe --template-version.");
+  return { templateId, version };
+}
+
+async function describeTemplate(api, _positional, options) {
+  const { templateId, version } = requiredTemplate(options);
+  const result = await api.monitoring.describeTemplate(templateId, version);
+  if (options.json) console.log(JSON.stringify(result, null, 2));
+  else {
+    const contract = result.contract;
+    console.log(
+      `${contract.name} v${contract.templateRef.version} (${contract.status})`,
+    );
+    console.log(`Entrada: ${contract.input.mediaType}`);
+    console.log(`Transformação: ${contract.transformation.language}`);
+    console.log(`Amostra: ${JSON.stringify(contract.input.sample)}`);
+    if (contract.output)
+      console.log(`Saída: ${JSON.stringify(contract.output)}`);
+  }
+  return result;
+}
+
+async function validateTemplate(api, _positional, options) {
+  const { templateId, version } = requiredTemplate(options);
+  if (!options.payload) throw new Error("Informe --payload.");
+  const result = await api.monitoring.validateTemplate(
+    templateId,
+    version,
+    parsePayload(options.payload),
+  );
+  if (options.json) console.log(JSON.stringify(result, null, 2));
+  else {
+    const validation = result.validation;
+    console.log(
+      `Payload válido: ${validation.result.status}${validation.result.message ? ` — ${validation.result.message}` : ""}`,
+    );
+  }
+  return result;
+}
+
+async function sendSignal(api, runtimeReference, options) {
+  const result = await api.monitoring.signal(
+    runtimeReference,
+    buildSignalPayload(options),
+  );
+  if (options.json) console.log(JSON.stringify(result, null, 2));
+  else printSignal(result);
+  return result;
+}
+
+function printSignals(result) {
+  if (!result.items.length) {
+    console.log("Nenhum sinal recebido.");
+    return;
+  }
+  for (const signal of result.items) {
+    console.log(
+      `${signal.observedAt}  ${signal.status.padEnd(11)}  ${signal.source}${signal.message ? `  ${signal.message}` : ""}`,
+    );
+  }
+}
+
+async function listSignals(api, runtimeReference, options) {
+  const result = await api.monitoring.listSignals(runtimeReference, options);
+  if (options.json) console.log(JSON.stringify(result, null, 2));
+  else printSignals(result);
+  return result;
+}
+
+const MONITORING_ACTIONS = {
+  describe: describeTemplate,
+  signal: sendSignal,
+  signals: listSignals,
+  validate: validateTemplate,
+};
+
+export async function runMonitoringCommand(api, action, positional, options) {
+  const handler = MONITORING_ACTIONS[action];
+  if (!handler)
+    throw new Error(
+      `Ação de monitoramento desconhecida: ${action || "(vazia)"}`,
+    );
+  if (["describe", "validate"].includes(action)) {
+    return handler(api, positional, options);
+  }
+  const runtimeReference = positional[0];
+  if (!runtimeReference)
+    throw new Error("Informe o UUID ou caminho do runtime.");
+  return handler(api, runtimeReference, options);
+}
+
+export default class Monitoring extends BaseCommand {
+  static description = "Envia e consulta sinais de monitoramento";
+
+  async run() {
+    await showTopic(this, "monitoring");
+  }
+}

package/src/commands/skills/install-all.js

@@ -0,0 +1,13 @@
+import { Flags } from "@oclif/core";
+import { createSkillsCommand } from "../../compatibilityCommands.js";
+
+export default createSkillsCommand("install-all", {
+  description: "instala todas as skills publicadas",
+  flags: {
+    target: Flags.string({ description: "diretório de instalação" }),
+    force: Flags.boolean({
+      char: "f",
+      description: "atualiza instalações existentes",
+    }),
+  },
+});

package/src/commands/skills/install.js

@@ -0,0 +1,16 @@
+import { Args, Flags } from "@oclif/core";
+import { createSkillsCommand } from "../../compatibilityCommands.js";
+
+export default createSkillsCommand("install", {
+  description: "instala uma skill publicada",
+  args: { skill: Args.string({ description: "ID da skill", required: true }) },
+  flags: {
+    target: Flags.string({ description: "diretório de instalação" }),
+    version: Flags.string({ description: "versão da skill" }),
+    force: Flags.boolean({
+      char: "f",
+      description: "substitui a instalação existente",
+    }),
+  },
+  positional: (args) => [args.skill],
+});

package/src/commands/skills/list.js

@@ -0,0 +1,5 @@
+import { createSkillsCommand } from "../../compatibilityCommands.js";
+
+export default createSkillsCommand("list", {
+  description: "lista skills publicadas",
+});

package/src/commands/skills/publish-all.js

@@ -0,0 +1,14 @@
+import { Flags } from "@oclif/core";
+import { createSkillsCommand } from "../../compatibilityCommands.js";
+
+export default createSkillsCommand("publish-all", {
+  description: "publica as skills contidas em um diretório",
+  flags: {
+    dir: Flags.string({ description: "diretório do catálogo" }),
+    "initial-version": Flags.string({
+      description: "versão inicial",
+      required: true,
+    }),
+    changelog: Flags.string({ description: "notas da versão" }),
+  },
+});

package/src/commands/skills/publish.js

@@ -0,0 +1,11 @@
+import { Flags } from "@oclif/core";
+import { createSkillsCommand } from "../../compatibilityCommands.js";
+
+export default createSkillsCommand("publish", {
+  description: "publica uma versão de skill",
+  flags: {
+    dir: Flags.string({ description: "diretório da skill", required: true }),
+    version: Flags.string({ description: "versão semântica", required: true }),
+    changelog: Flags.string({ description: "notas da versão" }),
+  },
+});

package/src/commands/skills/status.js

@@ -0,0 +1,7 @@
+import { Flags } from "@oclif/core";
+import { createSkillsCommand } from "../../compatibilityCommands.js";
+
+export default createSkillsCommand("status", {
+  description: "verifica integridade e atualização das skills instaladas",
+  flags: { target: Flags.string({ description: "diretório de instalação" }) },
+});

package/src/commands/skills/update.js

@@ -0,0 +1,12 @@
+import { Flags } from "@oclif/core";
+import {
+  createSkillsCommand,
+  optionalSkillArgument,
+} from "../../compatibilityCommands.js";
+
+export default createSkillsCommand("update", {
+  description: "atualiza uma ou todas as skills instaladas",
+  args: { skill: optionalSkillArgument },
+  flags: { target: Flags.string({ description: "diretório de instalação" }) },
+  positional: (args) => (args.skill ? [args.skill] : []),
+});

package/src/commands/skills.js

@@ -0,0 +1,303 @@
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+
+import { BaseCommand } from "../baseCommands.js";
+import { showTopic } from "../compatibilityCommands.js";
+import { buildSkillPayload } from "../skillPackage.js";
+import {
+  checksumInstalledSkill,
+  installSkillPackage,
+  readLock,
+} from "../localSkills.js";
+
+function targetFrom(options) {
+  return path.resolve(options.target || ".agents/skills");
+}
+
+function printJson(value, options) {
+  if (!options.json) return false;
+  console.log(JSON.stringify(value, null, 2));
+  return true;
+}
+
+async function install(api, skillId, version, options) {
+  const metadata = await api.get(skillId, version);
+  if (!metadata.skill) throw new Error(`Skill não encontrada: ${skillId}`);
+  const skillPackage = await api.download(skillId, metadata.skill.version);
+  return installSkillPackage(skillPackage, targetFrom(options), {
+    force: options.force,
+  });
+}
+
+async function findSkillDirectories(rootDirectory) {
+  const root = path.resolve(rootDirectory);
+  const entries = await readdir(root, { withFileTypes: true });
+  const directories = [];
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (!entry.isDirectory() || entry.isSymbolicLink()) continue;
+    const directory = path.join(root, entry.name);
+    try {
+      const children = await readdir(directory);
+      if (children.includes("SKILL.md")) directories.push(directory);
+    } catch (error) {
+      if (error.code !== "ENOENT" && error.code !== "EACCES") throw error;
+    }
+  }
+  return directories;
+}
+
+async function listSkills(api, _positional, options) {
+  const result = await api.list();
+  if (printJson(result, options)) return;
+  if (!result.items.length) {
+    console.log("Nenhuma skill publicada.");
+    return;
+  }
+  for (const item of result.items) {
+    console.log(`${item.skillId}@${item.latestVersion}  ${item.description}`);
+  }
+}
+
+async function publishSkill(api, _positional, options) {
+  if (!options.dir) throw new Error("Informe --dir <diretório-da-skill>");
+  if (!options.version) throw new Error("Informe --version <semver>");
+  const payload = await buildSkillPayload(options.dir, options);
+  const result = await api.publish(payload);
+  if (!printJson(result, options)) {
+    console.log(
+      `Publicada ${result.skill.skillId}@${result.skill.version} (${result.skill.packageSha256})`,
+    );
+  }
+}
+
+async function publishAllSkills(api, _positional, options) {
+  const rootDirectory = options.dir || ".agents/skills";
+  const version = options["initial-version"] || options.version;
+  if (!version) throw new Error("Informe --initial-version <semver>");
+  const [directories, catalog] = await Promise.all([
+    findSkillDirectories(rootDirectory),
+    api.list({ includeDeprecated: true }),
+  ]);
+  const publishedVersions = new Map(
+    catalog.items.map((item) => [
+      item.skillId,
+      new Set((item.versions || []).map((candidate) => candidate.version)),
+    ]),
+  );
+  const result = { published: [], skipped: [], failed: [] };
+
+  for (const directory of directories) {
+    try {
+      const payload = await buildSkillPayload(directory, {
+        ...options,
+        version,
+      });
+      if (publishedVersions.get(payload.skillId)?.has(version)) {
+        result.skipped.push({
+          skillId: payload.skillId,
+          version,
+          reason: "version-already-exists",
+        });
+        continue;
+      }
+      const response = await api.publish(payload);
+      result.published.push({
+        skillId: response.skill.skillId,
+        version: response.skill.version,
+        packageSha256: response.skill.packageSha256,
+      });
+    } catch (error) {
+      result.failed.push({
+        directory,
+        message: error.message,
+      });
+    }
+  }
+
+  if (printJson(result, options)) {
+    if (result.failed.length) process.exitCode = 1;
+    return;
+  }
+  for (const item of result.published)
+    console.log(`Publicada ${item.skillId}@${item.version}`);
+  for (const item of result.skipped)
+    console.log(
+      `Ignorada ${item.skillId}@${item.version}: versão já existente`,
+    );
+  for (const item of result.failed)
+    console.error(`Falha em ${item.directory}: ${item.message}`);
+  console.log(
+    `Resumo: ${result.published.length} publicada(s), ${result.skipped.length} ignorada(s), ${result.failed.length} falha(s).`,
+  );
+  if (result.failed.length) process.exitCode = 1;
+}
+
+async function installSkill(api, positional, options) {
+  const skillId = positional[0];
+  if (!skillId)
+    throw new Error("Informe a skill: biaws skills install <skill-id>");
+  const result = await install(api, skillId, options.version, options);
+  if (!printJson(result, options)) {
+    console.log(
+      `Instalada ${skillId}@${result.skill.version} em ${result.directory}`,
+    );
+  }
+}
+
+async function installCatalogSkill(api, item, lock, options, results) {
+  const localSkill = lock.skills[item.skillId];
+  if (localSkill && !options.force) {
+    results.skipped.push({
+      skillId: item.skillId,
+      version: localSkill.version,
+      reason: "already-installed",
+    });
+    return;
+  }
+
+  try {
+    const result = await install(api, item.skillId, item.latestVersion, {
+      ...options,
+      force: Boolean(localSkill),
+    });
+    results.installed.push({
+      skillId: item.skillId,
+      version: result.skill.version,
+      directory: result.directory,
+    });
+  } catch (error) {
+    results.failed.push({ skillId: item.skillId, message: error.message });
+  }
+}
+
+function printInstallAllResults(results) {
+  for (const item of results.installed)
+    console.log(
+      `Instalada ${item.skillId}@${item.version} em ${item.directory}`,
+    );
+  for (const item of results.skipped)
+    console.log(`Preservada ${item.skillId}@${item.version}`);
+  for (const item of results.failed)
+    console.error(`Falha em ${item.skillId}: ${item.message}`);
+}
+
+async function installAllSkills(api, _positional, options) {
+  const [catalog, lock] = await Promise.all([
+    api.list(),
+    readLock(targetFrom(options)),
+  ]);
+  const results = { installed: [], skipped: [], failed: [] };
+  for (const item of catalog.items) {
+    await installCatalogSkill(api, item, lock, options, results);
+  }
+  if (printJson(results, options)) {
+    if (results.failed.length) process.exitCode = 1;
+    return results;
+  }
+  if (!options.quiet) printInstallAllResults(results);
+  if (results.failed.length) process.exitCode = 1;
+  return results;
+}
+
+function skillStatus(local, installedChecksum, latestVersion) {
+  if (installedChecksum === null) return "missing";
+  if (installedChecksum !== local.packageSha256) return "modified";
+  if (!latestVersion) return "not-in-catalog";
+  return latestVersion === local.version ? "current" : "update-available";
+}
+
+async function getInstalledSkillsStatus(api, options) {
+  const lock = await readLock(targetFrom(options));
+  const catalog = await api.list();
+  const latestById = new Map(
+    catalog.items.map((item) => [item.skillId, item.latestVersion]),
+  );
+  const items = [];
+  for (const [skillId, local] of Object.entries(lock.skills)) {
+    const installedChecksum = await checksumInstalledSkill(
+      path.join(targetFrom(options), skillId),
+    );
+    const latestVersion = latestById.get(skillId) || null;
+    items.push({
+      skillId,
+      installedVersion: local.version,
+      latestVersion,
+      status: skillStatus(local, installedChecksum, latestVersion),
+    });
+  }
+  return items;
+}
+
+async function showSkillsStatus(api, _positional, options) {
+  const items = await getInstalledSkillsStatus(api, options);
+  if (printJson({ items }, options)) return;
+  if (!items.length) {
+    console.log("Nenhuma skill instalada pelo Bondia Workspaces CLI.");
+    return;
+  }
+  for (const item of items) {
+    const latest = item.latestVersion ? `; catálogo ${item.latestVersion}` : "";
+    console.log(
+      `${item.skillId}@${item.installedVersion}: ${item.status}${latest}`,
+    );
+  }
+}
+
+async function updateSkills(api, positional, options) {
+  const requestedSkillId = positional[0];
+  const lock = await readLock(targetFrom(options));
+  const catalog = await api.list();
+  if (requestedSkillId && !lock.skills[requestedSkillId]) {
+    throw new Error(
+      `Skill não instalada pelo Bondia Workspaces CLI: ${requestedSkillId}`,
+    );
+  }
+  const candidates = catalog.items.filter(
+    (item) =>
+      (!requestedSkillId || item.skillId === requestedSkillId) &&
+      lock.skills[item.skillId] &&
+      lock.skills[item.skillId].version !== item.latestVersion,
+  );
+  const results = [];
+  for (const item of candidates) {
+    results.push(
+      await install(api, item.skillId, item.latestVersion, {
+        ...options,
+        force: true,
+      }),
+    );
+  }
+  if (printJson({ items: results }, options)) return;
+  if (!results.length) console.log("Todas as skills estão atualizadas.");
+  for (const result of results) {
+    console.log(
+      `Atualizada ${path.basename(result.directory)} para ${result.skill.version}`,
+    );
+  }
+}
+
+const ACTION_HANDLERS = {
+  install: installSkill,
+  "install-all": installAllSkills,
+  list: listSkills,
+  publish: publishSkill,
+  "publish-all": publishAllSkills,
+  status: showSkillsStatus,
+  update: updateSkills,
+};
+
+export async function runSkillsCommand(api, action, positional, options) {
+  const handler = ACTION_HANDLERS[action];
+  if (!handler)
+    throw new Error(`Ação de skills desconhecida: ${action || "(ausente)"}`);
+  return handler(api, positional, options);
+}
+
+export default class Skills extends BaseCommand {
+  static description =
+    "Gerencia publicação, instalação e atualização de skills";
+
+  async run() {
+    await showTopic(this, "skills");
+  }
+}

package/src/commands/workspaces/get.js

@@ -0,0 +1,15 @@
+import { Args } from "@oclif/core";
+import { connectionFlags, ReadCommand } from "../../domain/readCommand.js";
+export default class WorkspaceGet extends ReadCommand {
+  static description = "Obtém um workspace por ID";
+  static args = { id: Args.string({ required: true }) };
+  static flags = connectionFlags;
+  async run() {
+    const { args, flags } = await this.parse(WorkspaceGet);
+    const result = await this.read(flags, (api) => api.workspace(args.id), {
+      resource: "workspace",
+      operation: "get",
+    });
+    this.emit(flags, result, (p) => JSON.stringify(p.workspace || p, null, 2));
+  }
+}

package/src/commands/workspaces/list.js

@@ -0,0 +1,20 @@
+import { connectionFlags, ReadCommand } from "../../domain/readCommand.js";
+import { table } from "../../domain/readService.js";
+export default class WorkspaceList extends ReadCommand {
+  static description = "Lista workspaces autorizados";
+  static flags = connectionFlags;
+  async run() {
+    const { flags } = await this.parse(WorkspaceList);
+    const result = await this.read(flags, (api) => api.workspaces(), {
+      resource: "workspaces",
+      operation: "list",
+    });
+    this.emit(flags, result, (p) =>
+      table(p.items || [], [
+        ["ID", (x) => x.id],
+        ["NOME", (x) => x.name],
+        ["STATUS", (x) => x.status],
+      ]),
+    );
+  }
+}

package/src/commands/workspaces.js

@@ -0,0 +1,7 @@
+import { Command } from "@oclif/core";
+export default class Workspaces extends Command {
+  static description = "Consulta workspaces autorizados pela API";
+  async run() {
+    await this.config.runCommand("help", ["workspaces"]);
+  }
+}