@vectorplane/ctrl-cli 0.1.8 → 0.1.10

package/README.md

@@ -17,6 +17,9 @@ 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
@@ -45,6 +48,19 @@ vp sync
 - mostra o estado da sessão local
 - exibe workspace ativo, diretório atual e última sincronização
 
+### `vp draft`
+
+- cria drafts editoriais ligados ao workspace atual
+- lista drafts existentes para conferência rápida
+- 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`
@@ -64,6 +80,8 @@ vp sync
   - obtém instruções de setup do workspace
 - `vp event send`
   - envia eventos operacionais
+- `vp draft`
+  - envia e consulta drafts editoriais do workspace
 
 ## Persistência local
 

package/dist/commands/draft.d.ts

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

package/dist/commands/draft.js

@@ -0,0 +1,166 @@
+import { getBooleanOption, getStringOption, parseArgs, requirePositional } from "../core/cli.js";
+import { ensureSessionAvailable, getProfileState } from "../core/config.js";
+import { collectGitContext } from "../core/git.js";
+import { collectMachineContext, collectRuntimeContext } from "../core/machine.js";
+import { loadRuntimeStatus } from "../core/runtime.js";
+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";
+const VALID_DRAFT_TYPES = new Set([
+    "architecture",
+    "decisions",
+    "progress",
+    "patterns",
+    "ui",
+    "ux",
+    "template_engineering",
+    "project_skeleton",
+]);
+const VALID_STATUSES = new Set([
+    "draft",
+    "in_review",
+    "approved",
+    "merged",
+    "rejected",
+    "archived",
+]);
+function slugify(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .normalize("NFD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 120);
+}
+function inferMemoryKey(type, title) {
+    const slug = slugify(title);
+    if (!slug)
+        return undefined;
+    const prefix = type === "decisions"
+        ? "decision"
+        : type === "patterns"
+            ? "pattern"
+            : type === "template_engineering"
+                ? "template"
+                : type === "project_skeleton"
+                    ? "skeleton"
+                    : type;
+    return `${prefix}:${slug}`;
+}
+function validateDraftType(value) {
+    if (!value || !VALID_DRAFT_TYPES.has(value)) {
+        throw new ValidationError("Informe um tipo válido em `--type`.");
+    }
+    return value;
+}
+function validateStatus(value) {
+    if (!value)
+        return undefined;
+    if (!VALID_STATUSES.has(value)) {
+        throw new ValidationError("Informe um status válido em `--status`.");
+    }
+    return value;
+}
+function buildNoImpactDraft(type, reason) {
+    const laneLabel = type.replaceAll("_", " ");
+    const explanation = reason?.trim() || "sem impacto identificado nesta tarefa";
+    return {
+        title: `Sem impacto em ${laneLabel}`,
+        content: `Esta tarefa não alterou diretamente a lane ${laneLabel}. Escopo efetivo: ${explanation}.`,
+    };
+}
+function printDraftList(drafts) {
+    if (drafts.length === 0) {
+        process.stdout.write("VectorPlane: nenhum draft encontrado.\n");
+        return;
+    }
+    for (const draft of drafts) {
+        process.stdout.write(`${draft.id} | ${draft.docType} | ${draft.status} | ${draft.title}\n`);
+    }
+}
+async function resolveAuthenticatedWorkspace(cliVersion, rawArgs) {
+    const runtime = await loadRuntimeStatus();
+    const session = await ensureSessionAvailable(runtime.profile.name);
+    const parsed = parseArgs(rawArgs);
+    const [git, machine, runtimeContext] = await Promise.all([
+        collectGitContext(process.cwd()),
+        collectMachineContext(runtime.device, runtime.config),
+        collectRuntimeContext(cliVersion, "draft", 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 boundWorkspace = await getBoundWorkspace(rootPath);
+    const profileState = getProfileState(runtime.state, runtime.profile.name);
+    const workspace = resolveWorkspaceSlug(runtime.profile, freshSession, getStringOption(parsed, "workspace"), boundWorkspace, profileState.lastWorkspace);
+    if (!workspace) {
+        throw new ValidationError("Nenhum workspace resolvido para operar drafts.");
+    }
+    return { parsed, runtime, apiClient, freshSession, git, workspace };
+}
+async function runDraftCreate(cliVersion, args) {
+    const { parsed, runtime, apiClient, freshSession, git, workspace } = await resolveAuthenticatedWorkspace(cliVersion, args);
+    const type = validateDraftType(getStringOption(parsed, "type"));
+    const noImpact = getBooleanOption(parsed, "no-impact");
+    const explicitTitle = getStringOption(parsed, "title")?.trim();
+    const explicitContent = getStringOption(parsed, "content")?.trim();
+    const reason = getStringOption(parsed, "reason");
+    const derived = noImpact ? buildNoImpactDraft(type, reason) : null;
+    const title = explicitTitle || derived?.title;
+    const content = explicitContent || derived?.content;
+    if (!title) {
+        throw new ValidationError("Informe `--title` para criar o draft.");
+    }
+    if (!content) {
+        throw new ValidationError("Informe `--content` para criar o draft.");
+    }
+    const payload = {
+        docType: type,
+        title,
+        content,
+        memoryKey: getStringOption(parsed, "memory-key")?.trim() || inferMemoryKey(type, title),
+        featureKey: getStringOption(parsed, "feature")?.trim() || undefined,
+        branch: getStringOption(parsed, "branch")?.trim() || git.branch || undefined,
+        taskKey: getStringOption(parsed, "task")?.trim() || undefined,
+    };
+    const draft = await apiClient.createMemoryDraft(freshSession.accessToken, workspace, payload);
+    runtime.logger.success(`draft enviado para ${type}.`);
+    process.stdout.write(`ID: ${draft.id}\n`);
+    process.stdout.write(`Workspace: ${workspace}\n`);
+    process.stdout.write(`Status: ${draft.status}\n`);
+    return 0;
+}
+async function runDraftList(cliVersion, args) {
+    const { parsed, apiClient, freshSession, workspace } = await resolveAuthenticatedWorkspace(cliVersion, args);
+    const status = validateStatus(getStringOption(parsed, "status"));
+    const drafts = await apiClient.listMemoryDrafts(freshSession.accessToken, workspace, status);
+    if (getBooleanOption(parsed, "json")) {
+        process.stdout.write(`${JSON.stringify(drafts, null, 2)}\n`);
+        return 0;
+    }
+    printDraftList(drafts);
+    return 0;
+}
+export async function runDraftCommand(cliVersion, args) {
+    const parsed = parseArgs(args);
+    const subcommand = requirePositional(parsed, 0, "Uso: vp draft <create|list> [...]");
+    if (subcommand === "create") {
+        return runDraftCreate(cliVersion, args.slice(1));
+    }
+    if (subcommand === "list") {
+        return runDraftList(cliVersion, args.slice(1));
+    }
+    throw new ValidationError("Uso: vp draft <create|list> [...]");
+}
+//# sourceMappingURL=draft.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,25 @@ 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";
+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;
@@ -38,6 +57,7 @@ export async function runSessionCommand(cliVersion, args) {
         throw new ValidationError("Nenhum workspace resolvido para a sessão.");
     }
     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 +68,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 +79,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 +97,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 +118,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/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, ResolveWorkspaceRequest, ResolveWorkspaceResponse, SyncRequest, SyncResponse } from "../types/api.js";
+import type { AgentCheckoutRequest, AgentHeartbeatRequest, AgentSessionRequest, AgentSessionResponse, EventRequest, MemoryDraftCreateRequest, MemoryDraftRecord, MemoryDraftStatus, ResolveWorkspaceRequest, ResolveWorkspaceResponse, SyncRequest, SyncResponse } from "../types/api.js";
 export declare class VectorPlaneApiClient {
     private readonly apiBaseUrl;
     private readonly timeoutMs;
@@ -22,6 +22,8 @@ export declare class VectorPlaneApiClient {
     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>>;
+    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>;
     heartbeatAgent(accessToken: string, payload: AgentHeartbeatRequest): Promise<AgentSessionResponse>;
     checkOutAgent(accessToken: string, payload: AgentCheckoutRequest): Promise<AgentSessionResponse>;

package/dist/core/api.js

@@ -160,6 +160,25 @@ export class VectorPlaneApiClient {
             },
         }, this.timeoutMs, this.logger);
     }
+    async listMemoryDrafts(accessToken, workspaceRef, status) {
+        const url = new URL(`${this.apiBaseUrl}/cli/workspace/${workspaceRef}/memory-drafts`);
+        if (status) {
+            url.searchParams.set("status", status);
+        }
+        return requestJson(url.toString(), {
+            method: "GET",
+            headers: {
+                "Authorization": `Bearer ${accessToken}`,
+            },
+        }, this.timeoutMs, this.logger);
+    }
+    async createMemoryDraft(accessToken, workspaceRef, payload) {
+        return requestJson(`${this.apiBaseUrl}/cli/workspace/${workspaceRef}/memory-drafts`, {
+            method: "POST",
+            headers: authHeaders(accessToken),
+            body: JSON.stringify(payload),
+        }, this.timeoutMs, this.logger);
+    }
     async checkInAgent(accessToken, payload) {
         return requestJson(`${this.apiBaseUrl}/cli/workspace/${payload.workspaceId}/agents/check-in`, {
             method: "POST",

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/index.js

@@ -5,6 +5,7 @@ import { runBootstrapCommand } from "./commands/bootstrap.js";
 import { runConfigCommand } from "./commands/config.js";
 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 { runLoginCommand } from "./commands/login.js";
 import { runLogoutCommand } from "./commands/logout.js";
@@ -32,6 +33,7 @@ function printHelp() {
     process.stdout.write("  status\n");
     process.stdout.write("  whoami\n");
     process.stdout.write("  doctor\n");
+    process.stdout.write("  draft <create|list>\n");
     process.stdout.write("  config <profile|get|set>\n");
     process.stdout.write("  workspace <current|use|resolve|clear>\n");
     process.stdout.write("  session <check-in|heartbeat|check-out>\n");
@@ -60,6 +62,8 @@ export async function runCli(args) {
                 return runWhoAmICommand(cliVersion);
             case "doctor":
                 return runDoctorCommand(cliVersion);
+            case "draft":
+                return runDraftCommand(cliVersion, rest);
             case "config":
                 return runConfigCommand(rest);
             case "workspace":

package/dist/types/api.d.ts

@@ -59,3 +59,30 @@ export interface AgentSessionResponse {
     workspaceId?: string;
     [key: string]: unknown;
 }
+export type MemoryDraftType = "architecture" | "decisions" | "progress" | "patterns" | "ui" | "ux" | "template_engineering" | "project_skeleton";
+export type MemoryDraftStatus = "draft" | "in_review" | "approved" | "merged" | "rejected" | "archived";
+export interface MemoryDraftCreateRequest {
+    docType: MemoryDraftType;
+    title: string;
+    content: string;
+    memoryKey?: string;
+    featureKey?: string;
+    branch?: string;
+    taskKey?: string;
+}
+export interface MemoryDraftRecord {
+    id: string;
+    workspaceId: string;
+    docType: MemoryDraftType;
+    title: string;
+    content: string;
+    memoryKey: string | null;
+    featureKey: string | null;
+    branch: string | null;
+    taskKey: string | null;
+    status: MemoryDraftStatus;
+    suggestedMergeStrategy?: string | null;
+    createdAt: string;
+    updatedAt?: string;
+    [key: string]: unknown;
+}

package/package.json

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