@vectorplane/ctrl-cli 0.1.9 → 0.1.11

package/README.md

@@ -13,15 +13,28 @@ npm install -g @vectorplane/ctrl-cli
 ## Uso
 
 ```bash
+vp init
 vp login
 vp logout
 vp status
 vp sync
+vp context --workspace <workspace> --delivery
+vp session check-in --workspace <workspace> --agent codex --type codex --client openai-codex --feature feature-key --task task-key --owning-path "src/core,src/ui" --need "api-contract" --provide "implementation" --status "starting implementation"
 vp draft create --type progress --title "Entrega concluída" --content "Resumo da mudança"
 ```
 
 ## Comandos
 
+### `vp init`
+
+- autentica localmente se ainda não houver sessão
+- resolve e associa o workspace atual a partir do `git remote`, somente quando houver correspondência com um workspace que o usuário pode acessar
+- detecta o agente local automaticamente, pede confirmação se houver ambiguidade e aceita `--agent`
+- baixa o template oficial do backend
+- grava o arquivo local e adiciona a entrada no `.gitignore`
+- aceita `--force` para sobrescrever template existente
+- durante execução, se outro agente passar a operar no workspace e a detecção for confiável, o setup local é reconciliado automaticamente
+
 ### `vp login`
 
 - abre o navegador para autenticação
@@ -53,6 +66,12 @@ vp draft create --type progress --title "Entrega concluída" --content "Resumo d
 - suporta `ui`, `ux`, `project_skeleton`, `template_engineering`, `patterns`, `progress`, `decisions` e `architecture`
 - aceita `--no-impact` para registrar explicitamente quando uma lane não foi afetada
 
+### `vp session`
+
+- suporta `check-in`, `heartbeat` e `check-out`
+- permite declarar `feature`, `task`, `component`, `role`, `owning-path`, `need`, `provide` e `status`
+- deve ser usado em conjunto com `vp context --delivery` para reduzir conflito entre agentes ativos
+
 ### Comandos adicionais já implementados
 
 - `vp whoami`

package/dist/commands/context.js

@@ -7,6 +7,7 @@ import { ensureFreshSession, resolveWorkspaceSlug } from "../core/session.js";
 import { VectorPlaneApiClient } from "../core/api.js";
 import { getBoundWorkspace, resolveWorkspaceRoot } from "../core/workspace-binding.js";
 import { ValidationError } from "../core/errors.js";
+import { ensureAgentSetupCurrent } from "../core/agent-setup.js";
 export async function runContextCommand(cliVersion, args) {
     const parsed = parseArgs(args);
     const delivery = getBooleanOption(parsed, "delivery");
@@ -35,6 +36,15 @@ export async function runContextCommand(cliVersion, args) {
     if (!workspace) {
         throw new ValidationError("Nenhum workspace resolvido para carregar contexto.");
     }
+    await ensureAgentSetupCurrent({
+        rootPath,
+        workspace,
+        repoUrl: git.remoteOrigin,
+        source: git.remoteOrigin ? "api-resolve" : "manual",
+        accessToken: freshSession.accessToken,
+        apiClient,
+        logger: runtime.logger,
+    });
     const payload = delivery
         ? await apiClient.getWorkspaceDeliveryContext(freshSession.accessToken, workspace)
         : snapshot

package/dist/commands/init.d.ts

@@ -0,0 +1 @@
+export declare function runInitCommand(cliVersion: string, args: string[]): Promise<number>;

package/dist/commands/init.js

@@ -0,0 +1,79 @@
+import { getBooleanOption, getStringOption, parseArgs } from "../core/cli.js";
+import { ensureSessionAvailable, loadSession, upsertProfile } from "../core/config.js";
+import { collectGitContext } from "../core/git.js";
+import { runLoginCommand } from "./login.js";
+import { collectMachineContext, collectRuntimeContext } from "../core/machine.js";
+import { loadRuntimeStatus } from "../core/runtime.js";
+import { ensureFreshSession } from "../core/session.js";
+import { VectorPlaneApiClient } from "../core/api.js";
+import { ensureAgentSetupCurrent } from "../core/agent-setup.js";
+import { resolveWorkspaceRoot } from "../core/workspace-binding.js";
+import { resolveAuthorizedWorkspace } from "../core/workspace-resolution.js";
+export async function runInitCommand(cliVersion, args) {
+    const parsed = parseArgs(args);
+    const force = getBooleanOption(parsed, "force");
+    const requestedAgent = getStringOption(parsed, "agent");
+    const explicitWorkspace = getStringOption(parsed, "workspace");
+    const loginArgs = [];
+    if (getBooleanOption(parsed, "manual")) {
+        loginArgs.push("--manual");
+    }
+    if (getBooleanOption(parsed, "no-browser")) {
+        loginArgs.push("--no-browser");
+    }
+    const requestedProfile = getStringOption(parsed, "profile");
+    if (requestedProfile) {
+        loginArgs.push("--profile", requestedProfile);
+    }
+    let runtime = await loadRuntimeStatus();
+    let session = await loadSession(runtime.profile.name);
+    if (!session) {
+        runtime.logger.info("sessão local ausente, iniciando login...");
+        await runLoginCommand(cliVersion, loginArgs);
+        runtime = await loadRuntimeStatus();
+        session = await ensureSessionAvailable(runtime.profile.name);
+    }
+    const [git, machine, runtimeContext] = await Promise.all([
+        collectGitContext(process.cwd()),
+        collectMachineContext(runtime.device, runtime.config),
+        collectRuntimeContext(cliVersion, "init", process.argv.slice(2)),
+    ]);
+    const apiClient = new VectorPlaneApiClient(runtime.profile.apiBaseUrl, runtime.config.requestTimeoutMs, runtime.logger);
+    const freshSession = await ensureFreshSession({
+        profileName: runtime.profile.name,
+        session,
+        machine,
+        runtime: runtimeContext,
+        device: runtime.device,
+        apiClient,
+        logger: runtime.logger,
+    });
+    const rootPath = resolveWorkspaceRoot(process.cwd(), git);
+    const workspace = await resolveAuthorizedWorkspace({
+        apiClient,
+        accessToken: freshSession.accessToken,
+        git,
+        explicitWorkspace: explicitWorkspace ?? undefined,
+        profile: runtime.profile,
+        session: freshSession,
+    });
+    const result = await ensureAgentSetupCurrent({
+        rootPath,
+        workspace,
+        repoUrl: git.remoteOrigin,
+        source: git.remoteOrigin ? "api-resolve" : "manual",
+        accessToken: freshSession.accessToken,
+        apiClient,
+        logger: runtime.logger,
+        explicitAgent: requestedAgent,
+        force,
+    });
+    await upsertProfile(runtime.profile.name, { workspace });
+    runtime.logger.success("workspace inicializado.");
+    process.stdout.write(`Workspace: ${workspace}\n`);
+    process.stdout.write(`Agente configurado: ${result.agent}\n`);
+    process.stdout.write(`Confiança da detecção: ${result.confidence}\n`);
+    process.stdout.write(`Template: ${result.templatePath} (${result.fileStatus})\n`);
+    return 0;
+}
+//# sourceMappingURL=init.js.map

package/dist/commands/session.js

@@ -1,4 +1,4 @@
-import { getStringOption, parseArgs } from "../core/cli.js";
+import { getStringListOption, getStringOption, parseArgs } from "../core/cli.js";
 import { ensureSessionAvailable, getProfileState, updateProfileState } from "../core/config.js";
 import { collectGitContext } from "../core/git.js";
 import { collectMachineContext, collectRuntimeContext } from "../core/machine.js";
@@ -7,6 +7,26 @@ import { ensureFreshSession, resolveWorkspaceSlug } from "../core/session.js";
 import { VectorPlaneApiClient } from "../core/api.js";
 import { deriveClientInstanceId, getBoundWorkspace, resolveWorkspaceRoot } from "../core/workspace-binding.js";
 import { ValidationError } from "../core/errors.js";
+import { ensureAgentSetupCurrent } from "../core/agent-setup.js";
+function readCollaborationMetadata(parsed, rootPath) {
+    const owningPaths = getStringListOption(parsed, "owning-path");
+    const needs = getStringListOption(parsed, "need");
+    const provides = getStringListOption(parsed, "provide");
+    const relatedWorkspaceIds = getStringListOption(parsed, "related-workspace");
+    return {
+        source: "vp-cli",
+        rootPath,
+        featureKey: getStringOption(parsed, "feature"),
+        taskKey: getStringOption(parsed, "task"),
+        component: getStringOption(parsed, "component"),
+        role: getStringOption(parsed, "role"),
+        statusSummary: getStringOption(parsed, "status"),
+        owningPaths: owningPaths.length > 0 ? owningPaths : undefined,
+        needs: needs.length > 0 ? needs : undefined,
+        provides: provides.length > 0 ? provides : undefined,
+        relatedWorkspaceIds: relatedWorkspaceIds.length > 0 ? relatedWorkspaceIds : undefined,
+    };
+}
 export async function runSessionCommand(cliVersion, args) {
     const parsed = parseArgs(args);
     const [subcommand] = parsed.positionals;
@@ -37,7 +57,17 @@ export async function runSessionCommand(cliVersion, args) {
     if (!workspace) {
         throw new ValidationError("Nenhum workspace resolvido para a sessão.");
     }
+    await ensureAgentSetupCurrent({
+        rootPath,
+        workspace,
+        repoUrl: git.remoteOrigin,
+        source: git.remoteOrigin ? "api-resolve" : "manual",
+        accessToken: freshSession.accessToken,
+        apiClient,
+        logger: runtime.logger,
+    });
     const clientInstanceId = getStringOption(parsed, "client-instance-id") ?? deriveClientInstanceId(runtime.device.machineId, rootPath, git);
+    const metadata = readCollaborationMetadata(parsed, rootPath);
     if (subcommand === "check-in") {
         const response = await apiClient.checkInAgent(freshSession.accessToken, {
             workspaceId: workspace,
@@ -48,10 +78,7 @@ export async function runSessionCommand(cliVersion, args) {
             repoUrl: git.remoteOrigin ?? undefined,
             branch: git.branch,
             commitSha: git.commitHash,
-            metadata: {
-                source: "vp-cli",
-                rootPath,
-            },
+            metadata,
         });
         const sessionId = String(response.id ?? response.sessionId ?? "");
         await updateProfileState(runtime.profile.name, {
@@ -62,6 +89,12 @@ export async function runSessionCommand(cliVersion, args) {
         });
         process.stdout.write(`Session ID: ${sessionId || "não retornado"}\n`);
         process.stdout.write(`Client Instance ID: ${clientInstanceId}\n`);
+        if (metadata.featureKey) {
+            process.stdout.write(`Feature: ${metadata.featureKey}\n`);
+        }
+        if (metadata.taskKey) {
+            process.stdout.write(`Task: ${metadata.taskKey}\n`);
+        }
         return 0;
     }
     if (subcommand === "heartbeat") {
@@ -74,16 +107,16 @@ export async function runSessionCommand(cliVersion, args) {
             clientInstanceId,
             branch: git.branch,
             commitSha: git.commitHash,
-            metadata: {
-                source: "vp-cli",
-                rootPath,
-            },
+            metadata,
         });
         await updateProfileState(runtime.profile.name, {
             lastCommand: "session:heartbeat",
             lastError: null,
         });
         process.stdout.write(`Heartbeat enviado para ${sessionId}\n`);
+        if (metadata.statusSummary) {
+            process.stdout.write(`Status: ${metadata.statusSummary}\n`);
+        }
         return 0;
     }
     if (subcommand === "check-out") {
@@ -95,6 +128,9 @@ export async function runSessionCommand(cliVersion, args) {
             sessionId,
             metadata: {
                 source: "vp-cli",
+                featureKey: metadata.featureKey,
+                taskKey: metadata.taskKey,
+                statusSummary: metadata.statusSummary,
             },
         });
         await updateProfileState(runtime.profile.name, {

package/dist/commands/sync.js

@@ -10,6 +10,7 @@ import { VectorPlaneApiClient } from "../core/api.js";
 import { collectWorkspaceContext } from "../core/workspace.js";
 import { getBoundWorkspace } from "../core/workspace-binding.js";
 import { ValidationError } from "../core/errors.js";
+import { ensureAgentSetupCurrent } from "../core/agent-setup.js";
 export async function runSyncCommand(cliVersion, args) {
     const parsed = parseArgs(args);
     const force = getBooleanOption(parsed, "force");
@@ -39,6 +40,15 @@ export async function runSyncCommand(cliVersion, args) {
     if (!workspaceSlug) {
         throw new ValidationError("Nenhum workspace ativo foi resolvido. Use `vp workspace use <workspace>` ou `vp login`.");
     }
+    await ensureAgentSetupCurrent({
+        rootPath: workspaceRoot,
+        workspace: workspaceSlug,
+        repoUrl: git.remoteOrigin,
+        source: git.remoteOrigin ? "api-resolve" : "manual",
+        accessToken: freshSession.accessToken,
+        apiClient,
+        logger: runtime.logger,
+    });
     const workspace = await collectWorkspaceContext(process.cwd(), git);
     runtime.logger.info("consolidando contexto...");
     const timestamp = new Date().toISOString();

package/dist/core/agent-setup.d.ts

@@ -0,0 +1,32 @@
+import type { VectorPlaneApiClient } from "./api.js";
+import type { Logger } from "./logger.js";
+export type SupportedAgent = "claude" | "cursor" | "windsurf" | "copilot" | "codex" | "generic";
+export type DetectionConfidence = "high" | "medium" | "low";
+export interface AgentDetectionResult {
+    selected: SupportedAgent | null;
+    confidence: DetectionConfidence;
+    reasons: string[];
+    candidates: SupportedAgent[];
+}
+export declare function detectAgentRuntime(rootPath: string): Promise<AgentDetectionResult>;
+export declare function resolveAgentSelection(rootPath: string, explicitAgent?: SupportedAgent): Promise<{
+    agent: SupportedAgent;
+    detection: AgentDetectionResult;
+}>;
+export declare function ensureAgentSetupCurrent(params: {
+    rootPath: string;
+    workspace: string;
+    repoUrl: string | null;
+    source: "manual" | "api-resolve" | "session";
+    accessToken: string;
+    apiClient: VectorPlaneApiClient;
+    logger: Logger;
+    explicitAgent?: SupportedAgent;
+    force?: boolean;
+}): Promise<{
+    agent: SupportedAgent;
+    templatePath: string;
+    fileStatus: "created" | "updated" | "unchanged";
+    changed: boolean;
+    confidence: DetectionConfidence;
+}>;

package/dist/core/agent-setup.js

@@ -0,0 +1,226 @@
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import path from "node:path";
+import readline from "node:readline/promises";
+import { ValidationError } from "./errors.js";
+import { bindWorkspaceToRoot, getWorkspaceBinding } from "./workspace-binding.js";
+const AGENT_TEMPLATE_PATHS = {
+    claude: "CLAUDE.md",
+    cursor: ".cursor/rules/traceplane.mdc",
+    windsurf: ".windsurfrules",
+    copilot: ".github/copilot-instructions.md",
+    codex: "AGENTS.md",
+    generic: "AGENTS.md",
+};
+async function pathExists(filePath) {
+    try {
+        await access(filePath, fsConstants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function uniqueAgents(values) {
+    return [...new Set(values)];
+}
+export async function detectAgentRuntime(rootPath) {
+    const scores = new Map();
+    const reasons = new Map();
+    const addScore = (agent, amount, reason) => {
+        scores.set(agent, (scores.get(agent) ?? 0) + amount);
+        reasons.set(agent, [...(reasons.get(agent) ?? []), reason]);
+    };
+    const fileCandidates = [
+        { agent: "claude", file: path.join(rootPath, "CLAUDE.md") },
+        { agent: "cursor", file: path.join(rootPath, ".cursor") },
+        { agent: "windsurf", file: path.join(rootPath, ".windsurfrules") },
+        { agent: "copilot", file: path.join(rootPath, ".github", "copilot-instructions.md") },
+        { agent: "codex", file: path.join(rootPath, "AGENTS.md") },
+    ];
+    for (const candidate of fileCandidates) {
+        if (await pathExists(candidate.file)) {
+            addScore(candidate.agent, 25, `file:${path.relative(rootPath, candidate.file) || candidate.file}`);
+        }
+    }
+    const envSignals = [
+        { agent: "cursor", value: process.env.CURSOR_TRACE_ID, reason: "env:CURSOR_TRACE_ID" },
+        { agent: "windsurf", value: process.env.WINDSURF_SESSION_ID, reason: "env:WINDSURF_SESSION_ID" },
+        { agent: "codex", value: process.env.CODEX_ENV, reason: "env:CODEX_ENV" },
+        { agent: "claude", value: process.env.CLAUDECODE, reason: "env:CLAUDECODE" },
+        { agent: "copilot", value: process.env.GITHUB_COPILOT, reason: "env:GITHUB_COPILOT" },
+    ];
+    for (const signal of envSignals) {
+        if (signal.value) {
+            addScore(signal.agent, 100, signal.reason);
+        }
+    }
+    const ranked = [...scores.entries()].sort((left, right) => right[1] - left[1]);
+    if (ranked.length === 0) {
+        return {
+            selected: null,
+            confidence: "low",
+            reasons: [],
+            candidates: [],
+        };
+    }
+    const topScore = ranked[0][1];
+    const candidates = uniqueAgents(ranked.filter((entry) => entry[1] === topScore).map(([agent]) => agent));
+    const selected = candidates.length === 1 ? candidates[0] : null;
+    return {
+        selected,
+        confidence: topScore >= 100 ? "high" : candidates.length === 1 ? "medium" : "low",
+        reasons: selected ? (reasons.get(selected) ?? []) : candidates.flatMap((agent) => reasons.get(agent) ?? []),
+        candidates,
+    };
+}
+async function promptForAgent(detection) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        throw new ValidationError("Não foi possível detectar o agente local com segurança. Use --agent claude|cursor|windsurf|copilot|codex|generic.");
+    }
+    const ordered = uniqueAgents([
+        ...detection.candidates,
+        "claude",
+        "cursor",
+        "windsurf",
+        "copilot",
+        "codex",
+        "generic",
+    ]);
+    process.stdout.write("VectorPlane: não foi possível identificar o agente local com segurança.\n");
+    ordered.forEach((agent, index) => {
+        process.stdout.write(`  ${index + 1}. ${agent}\n`);
+    });
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = (await rl.question("Selecione o agente local: ")).trim();
+        const index = Number(answer);
+        if (Number.isInteger(index) && index >= 1 && index <= ordered.length) {
+            return ordered[index - 1];
+        }
+        if (ordered.includes(answer)) {
+            return answer;
+        }
+    }
+    finally {
+        rl.close();
+    }
+    throw new ValidationError("Seleção de agente inválida.");
+}
+async function appendGitIgnoreEntry(rootPath, relativeTarget) {
+    const gitIgnorePath = path.join(rootPath, ".gitignore");
+    const normalizedEntry = relativeTarget.replace(/\\/g, "/");
+    const current = await readFile(gitIgnorePath, "utf8").catch(() => "");
+    const lines = current.split(/\r?\n/).map((line) => line.trim());
+    if (lines.includes(normalizedEntry)) {
+        return;
+    }
+    const next = current.trimEnd();
+    const updated = `${next}${next ? "\n" : ""}${normalizedEntry}\n`;
+    await writeFile(gitIgnorePath, updated, "utf8");
+}
+async function writeTemplateFile(rootPath, relativeTarget, content, force) {
+    const absoluteTarget = path.join(rootPath, relativeTarget);
+    await mkdir(path.dirname(absoluteTarget), { recursive: true });
+    if (await pathExists(absoluteTarget)) {
+        const current = await readFile(absoluteTarget, "utf8");
+        if (current === content) {
+            return "unchanged";
+        }
+        if (!force) {
+            throw new ValidationError(`O arquivo ${relativeTarget} já existe. Use --force para sobrescrever.`);
+        }
+        await writeFile(absoluteTarget, content, "utf8");
+        return "updated";
+    }
+    await writeFile(absoluteTarget, content, "utf8");
+    return "created";
+}
+function getAgentTemplate(setup, agent) {
+    const template = setup.agents[agent];
+    if (!template) {
+        throw new ValidationError(`O backend não retornou template para o agente ${agent}.`);
+    }
+    return template;
+}
+export async function resolveAgentSelection(rootPath, explicitAgent) {
+    if (explicitAgent) {
+        return {
+            agent: explicitAgent,
+            detection: {
+                selected: explicitAgent,
+                confidence: "high",
+                reasons: ["explicit-flag"],
+                candidates: [explicitAgent],
+            },
+        };
+    }
+    const detection = await detectAgentRuntime(rootPath);
+    if (detection.selected && detection.confidence !== "low") {
+        return { agent: detection.selected, detection };
+    }
+    return {
+        agent: await promptForAgent(detection),
+        detection,
+    };
+}
+export async function ensureAgentSetupCurrent(params) {
+    const binding = await getWorkspaceBinding(params.rootPath);
+    let selection;
+    if (!params.explicitAgent && binding?.configuredAgent) {
+        const detection = await detectAgentRuntime(params.rootPath);
+        if (!detection.selected && detection.confidence === "low") {
+            selection = {
+                agent: binding.configuredAgent,
+                detection: {
+                    selected: binding.configuredAgent,
+                    confidence: "low",
+                    reasons: ["binding-fallback"],
+                    candidates: [binding.configuredAgent],
+                },
+            };
+        }
+        else {
+            selection = await resolveAgentSelection(params.rootPath, params.explicitAgent);
+        }
+    }
+    else {
+        selection = await resolveAgentSelection(params.rootPath, params.explicitAgent);
+    }
+    const { agent, detection } = selection;
+    const expectedPath = AGENT_TEMPLATE_PATHS[agent];
+    if (binding?.workspace === params.workspace && binding.configuredAgent === agent && binding.templatePath === expectedPath && await pathExists(path.join(params.rootPath, expectedPath))) {
+        return {
+            agent,
+            templatePath: expectedPath,
+            fileStatus: "unchanged",
+            changed: false,
+            confidence: detection.confidence,
+        };
+    }
+    const setup = await params.apiClient.getAgentSetup(params.accessToken, params.workspace);
+    const template = getAgentTemplate(setup, agent);
+    const fileStatus = await writeTemplateFile(params.rootPath, template.filename, template.content, params.force ?? false);
+    await appendGitIgnoreEntry(params.rootPath, template.filename);
+    await bindWorkspaceToRoot({
+        rootPath: params.rootPath,
+        workspace: params.workspace,
+        repoUrl: params.repoUrl,
+        source: params.source,
+        configuredAgent: agent,
+        agentConfidence: detection.confidence,
+        templatePath: template.filename,
+        agentConfiguredAt: new Date().toISOString(),
+    });
+    if (binding?.configuredAgent && binding.configuredAgent !== agent) {
+        params.logger.info(`agente ativo detectado mudou de ${binding.configuredAgent} para ${agent}; setup local atualizado.`);
+    }
+    return {
+        agent,
+        templatePath: template.filename,
+        fileStatus,
+        changed: true,
+        confidence: detection.confidence,
+    };
+}
+//# sourceMappingURL=agent-setup.js.map

package/dist/core/api.d.ts

@@ -1,6 +1,6 @@
 import type { Logger } from "./logger.js";
 import type { CurrentUserResponse, AuthCodeExchangeRequest, AuthTokenExchangeResponse, CreateLoginAttemptRequest, CreateLoginAttemptResponse, LoginAttemptStatusResponse, RefreshTokenRequest } from "../types/auth.js";
-import type { AgentCheckoutRequest, AgentHeartbeatRequest, AgentSessionRequest, AgentSessionResponse, EventRequest, MemoryDraftCreateRequest, MemoryDraftRecord, MemoryDraftStatus, ResolveWorkspaceRequest, ResolveWorkspaceResponse, SyncRequest, SyncResponse } from "../types/api.js";
+import type { AgentCheckoutRequest, AgentHeartbeatRequest, AgentSessionRequest, AgentSessionResponse, EventRequest, MemoryDraftCreateRequest, MemoryDraftRecord, MemoryDraftStatus, ResolveWorkspaceRequest, ResolveWorkspaceResponse, SyncRequest, SyncResponse, WorkspaceAgentSetup } from "../types/api.js";
 export declare class VectorPlaneApiClient {
     private readonly apiBaseUrl;
     private readonly timeoutMs;
@@ -21,7 +21,7 @@ export declare class VectorPlaneApiClient {
     getWorkspaceContext(accessToken: string, workspaceId: string): Promise<Record<string, unknown>>;
     getWorkspaceSnapshot(accessToken: string, workspaceId: string): Promise<Record<string, unknown>>;
     getWorkspaceDeliveryContext(accessToken: string, workspaceId: string): Promise<Record<string, unknown>>;
-    getAgentSetup(accessToken: string, workspaceId: string): Promise<Record<string, unknown>>;
+    getAgentSetup(accessToken: string, workspaceId: string): Promise<WorkspaceAgentSetup>;
     listMemoryDrafts(accessToken: string, workspaceRef: string, status?: MemoryDraftStatus): Promise<MemoryDraftRecord[]>;
     createMemoryDraft(accessToken: string, workspaceRef: string, payload: MemoryDraftCreateRequest): Promise<MemoryDraftRecord>;
     checkInAgent(accessToken: string, payload: AgentSessionRequest): Promise<AgentSessionResponse>;

package/dist/core/cli.d.ts

@@ -5,5 +5,6 @@ export interface ParsedArgs {
 export declare function parseArgs(args: string[]): ParsedArgs;
 export declare function getStringOption(parsed: ParsedArgs, key: string): string | undefined;
 export declare function getBooleanOption(parsed: ParsedArgs, key: string): boolean;
+export declare function getStringListOption(parsed: ParsedArgs, key: string): string[];
 export declare function requirePositional(parsed: ParsedArgs, index: number, message: string): string;
 export declare function parseJsonOption(value: string | undefined, fallback?: Record<string, unknown>): Record<string, unknown>;

package/dist/core/cli.js

@@ -38,6 +38,16 @@ export function getBooleanOption(parsed, key) {
     }
     return false;
 }
+export function getStringListOption(parsed, key) {
+    const value = getStringOption(parsed, key);
+    if (!value) {
+        return [];
+    }
+    return [...new Set(value
+            .split(",")
+            .map((item) => item.trim())
+            .filter(Boolean))];
+}
 export function requirePositional(parsed, index, message) {
     const value = parsed.positionals[index];
     if (!value) {

package/dist/core/workspace-binding.d.ts

@@ -3,12 +3,17 @@ import type { GitContext } from "../types/workspace.js";
 export declare function resolveWorkspaceRoot(cwd: string, git: GitContext): string;
 export declare function deriveClientInstanceId(machineId: string, workspaceRoot: string, git: GitContext): string;
 export declare function getBoundWorkspace(rootPath: string): Promise<string | null>;
+export declare function getWorkspaceBinding(rootPath: string): Promise<import("../types/config.js").WorkspaceBinding>;
 export declare function getBindingStore(): Promise<WorkspaceBindingStore>;
 export declare function bindWorkspaceToRoot(params: {
     rootPath: string;
     workspace: string;
     repoUrl: string | null;
     source: "manual" | "api-resolve" | "session";
+    configuredAgent?: "claude" | "cursor" | "windsurf" | "copilot" | "codex" | "generic" | null;
+    agentConfidence?: "high" | "medium" | "low" | null;
+    templatePath?: string | null;
+    agentConfiguredAt?: string | null;
 }): Promise<void>;
 export declare function clearBoundWorkspace(rootPath: string): Promise<void>;
 export declare function resolveWorkspacePreference(profile: CliProfileConfig, boundWorkspace: string | null): string | null;

package/dist/core/workspace-binding.js

@@ -17,6 +17,10 @@ export async function getBoundWorkspace(rootPath) {
     const store = await loadWorkspaceBindings();
     return store.bindings[rootPath]?.workspace ?? null;
 }
+export async function getWorkspaceBinding(rootPath) {
+    const store = await loadWorkspaceBindings();
+    return store.bindings[rootPath] ?? null;
+}
 export async function getBindingStore() {
     return loadWorkspaceBindings();
 }
@@ -27,6 +31,10 @@ export async function bindWorkspaceToRoot(params) {
         repoUrl: params.repoUrl,
         resolvedAt: new Date().toISOString(),
         source: params.source,
+        configuredAgent: params.configuredAgent ?? null,
+        agentConfidence: params.agentConfidence ?? null,
+        templatePath: params.templatePath ?? null,
+        agentConfiguredAt: params.agentConfiguredAt ?? null,
     });
 }
 export async function clearBoundWorkspace(rootPath) {

package/dist/core/workspace-resolution.d.ts

@@ -0,0 +1,12 @@
+import type { VectorPlaneApiClient } from "./api.js";
+import type { AuthSession } from "../types/auth.js";
+import type { CliProfileConfig } from "../types/config.js";
+import type { GitContext } from "../types/workspace.js";
+export declare function resolveAuthorizedWorkspace(params: {
+    apiClient: VectorPlaneApiClient;
+    accessToken: string;
+    git: GitContext;
+    explicitWorkspace?: string;
+    profile: CliProfileConfig;
+    session: AuthSession;
+}): Promise<string>;

package/dist/core/workspace-resolution.js

@@ -0,0 +1,24 @@
+import { ValidationError } from "./errors.js";
+export async function resolveAuthorizedWorkspace(params) {
+    if (params.git.remoteOrigin) {
+        const resolved = await params.apiClient.resolveWorkspaceByRepo(params.accessToken, {
+            repoUrl: params.git.remoteOrigin,
+            orgId: params.profile.orgId ?? undefined,
+        });
+        const resolvedWorkspace = String(resolved.workspaceId ?? resolved.id ?? resolved.slug ?? "");
+        const resolvedSlug = typeof resolved.slug === "string" ? resolved.slug : null;
+        if (params.explicitWorkspace && params.explicitWorkspace !== resolvedWorkspace && params.explicitWorkspace !== resolvedSlug) {
+            throw new ValidationError("O workspace solicitado não corresponde ao repositório remoto atual ou você não tem permissão para manipulá-lo.");
+        }
+        const workspace = resolvedWorkspace || resolvedSlug;
+        if (!workspace) {
+            throw new ValidationError("A API não retornou um identificador de workspace utilizável para o repositório atual.");
+        }
+        return workspace;
+    }
+    if (params.explicitWorkspace) {
+        return params.explicitWorkspace;
+    }
+    throw new ValidationError("Nenhum workspace resolvido para init. Configure um remote git correspondente ao workspace ou use --workspace com permissão válida.");
+}
+//# sourceMappingURL=workspace-resolution.js.map

package/dist/index.js

@@ -7,6 +7,7 @@ import { runContextCommand } from "./commands/context.js";
 import { runDoctorCommand } from "./commands/doctor.js";
 import { runDraftCommand } from "./commands/draft.js";
 import { runEventCommand } from "./commands/event.js";
+import { runInitCommand } from "./commands/init.js";
 import { runLoginCommand } from "./commands/login.js";
 import { runLogoutCommand } from "./commands/logout.js";
 import { runSessionCommand } from "./commands/session.js";
@@ -27,6 +28,7 @@ function printHelp() {
     process.stdout.write("Uso: vp <comando>\n");
     process.stdout.write("\n");
     process.stdout.write("Comandos principais:\n");
+    process.stdout.write("  init [--agent <tipo>] [--workspace <workspace>] [--force]\n");
     process.stdout.write("  login [--no-browser|--manual]\n");
     process.stdout.write("  logout\n");
     process.stdout.write("  sync [--force]\n");
@@ -52,6 +54,8 @@ export async function runCli(args) {
         switch (command) {
             case "login":
                 return runLoginCommand(cliVersion, rest);
+            case "init":
+                return runInitCommand(cliVersion, rest);
             case "sync":
                 return runSyncCommand(cliVersion, rest);
             case "logout":

package/dist/types/api.d.ts

@@ -6,6 +6,42 @@ export interface SyncRequest {
     hash: string;
     sent_at: string;
 }
+export interface WorkspaceAgentSetupFile {
+    filename: string;
+    description?: string;
+    content: string;
+}
+export interface WorkspaceAgentSetupCli {
+    package: string;
+    command: string;
+    install: string;
+    login: string;
+    status: string;
+    sync: string;
+    workspaceUse: string;
+    bootstrap: string;
+    context: string;
+    deliveryContext: string;
+    draftCreate: string;
+    draftList: string;
+    sessionCheckIn: string;
+    sessionHeartbeat: string;
+    sessionCheckOut: string;
+    eventSend: string;
+}
+export interface WorkspaceAgentSetup {
+    workspaceId: string;
+    orgId: string;
+    mcpUrl: string;
+    apiUrl: string;
+    repoUrl: string | null;
+    cli: WorkspaceAgentSetupCli;
+    agents: Record<string, WorkspaceAgentSetupFile>;
+    hooks: Record<string, WorkspaceAgentSetupFile>;
+    githubActions: WorkspaceAgentSetupFile;
+    installScript: WorkspaceAgentSetupFile;
+    [key: string]: unknown;
+}
 export interface SyncResponse {
     ok?: boolean;
     workspace?: string;

package/dist/types/config.d.ts

@@ -60,6 +60,10 @@ export interface WorkspaceBinding {
     repoUrl: string | null;
     resolvedAt: string;
     source: "manual" | "api-resolve" | "session";
+    configuredAgent?: "claude" | "cursor" | "windsurf" | "copilot" | "codex" | "generic" | null;
+    agentConfidence?: "high" | "medium" | "low" | null;
+    templatePath?: string | null;
+    agentConfiguredAt?: string | null;
 }
 export interface WorkspaceBindingStore {
     bindings: Record<string, WorkspaceBinding>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectorplane/ctrl-cli",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Official VectorPlane CLI.",
   "type": "module",
   "main": "./dist/index.js",