pi-dev-workflow

Workflow de Desenvolvimento Pi

Desenvolver extensões, skills ou temas para o pi exige alternar entre código local (para iterar rápido) e pacotes publicados (para validar a experiência do usuário final). Esta skill documenta os padrões que funcionam.

Paridade guide-skill

Guide canônico: docs/guides/testing-isolation.md Guide complementar: docs/guides/control-plane-operating-doctrine.md Paridade mínima: PI_CODING_AGENT_DIR isolado; settings canônico vs derivado; paths portáveis; reload obrigatório; não mutar pacote upstream do pi Última revisão de paridade: 2026-04-30

O Problema

Quando você desenvolve um pacote pi dentro de um monorepo, surgem 3 conflitos comuns:

1. O pi carrega a versão publicada em vez do código local que você está editando
2. npm workspaces faz hoisting — deps vão para root/node_modules/ e paths relativos quebram
3. bundledDependencies não funciona com workspaces — o tarball sai vazio

Solução: Source Switching

O padrão adotado pelo oh-pi e pelo agents-lab:

1. Cada pacote é independente — publicado no npm com seu próprio package.json
2. Um script alterna entre paths locais e npm:@scope/name no settings.json do pi
3. Sem bundledDependencies — meta-pacotes são installers que rodam pi install para cada dependência

Configuração Mínima (pacote único)

Para um pacote simples, basta usar pi install com path local:

# Desenvolvimento — carrega do disco
pi install /caminho/absoluto/para/meu-pacote

# Produção — volta para npm
pi remove /caminho/absoluto/para/meu-pacote
pi install npm:@meu-scope/meu-pacote

Configuração Monorepo (múltiplos pacotes)

Crie um script que reescreve o settings.json do pi:

#!/usr/bin/env node
// scripts/pi-source-switch.mjs
import { existsSync, readFileSync, readdirSync, writeFileSync, mkdirSync } from "node:fs";
import { homedir } from "node:os";
import path from "node:path";
import { fileURLToPath } from "node:url";

const __dirname = path.dirname(fileURLToPath(import.meta.url));
const REPO_ROOT = path.resolve(__dirname, "..");

// Descobrir pacotes pi no workspace
const PACKAGES = new Map();
for (const entry of readdirSync(path.join(REPO_ROOT, "packages"), { withFileTypes: true })) {
  if (!entry.isDirectory()) continue;
  const pkgPath = path.join(REPO_ROOT, "packages", entry.name, "package.json");
  if (!existsSync(pkgPath)) continue;
  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
  if (pkg.keywords?.includes("pi-package")) {
    PACKAGES.set(pkg.name, path.join(REPO_ROOT, "packages", entry.name));
  }
}

const mode = process.argv[2]; // "local" ou "published"
const settingsPath = path.join(homedir(), ".pi", "agent", "settings.json");
const settings = existsSync(settingsPath)
  ? JSON.parse(readFileSync(settingsPath, "utf8")) : {};

const newPackages = [];
for (const [name, dir] of PACKAGES) {
  newPackages.push(mode === "local" ? path.resolve(dir) : `npm:${name}`);
}
settings.packages = newPackages;

mkdirSync(path.dirname(settingsPath), { recursive: true });
writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
console.log(`✅ Switched to ${mode} mode. Restart pi to reload.`);