overlord-cli 4.15.0 → 4.17.0

package/bin/_cli/protocol.mjs

@@ -69,7 +69,7 @@ function resolveProtocolMetadata(flags = {}, base = {}) {
   const metadata = { ...base };
 
   if (flags['metadata-json']) {
-    const parsed = JSON.parse(String(flags['metadata-json']));
+    const parsed = parseJsonFlag('--metadata-json', flags['metadata-json']);
     if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
       throw new Error('--metadata-json must be a JSON object');
     }
@@ -215,6 +215,15 @@ function requireFlag(flags, name, envAlias) {
   return String(value);
 }
 
+function parseJsonFlag(flagName, rawValue) {
+  try {
+    return JSON.parse(String(rawValue));
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new Error(`${flagName} must be valid JSON: ${detail}`);
+  }
+}
+
 function readTextFile(filePath, label) {
   try {
     return fs.readFileSync(filePath, 'utf8');
@@ -286,11 +295,7 @@ async function resolveChangeRationales(flags) {
     );
   }
   if (flags['change-rationales-json']) {
-    try {
-      return JSON.parse(String(flags['change-rationales-json']));
-    } catch {
-      throw new Error('--change-rationales-json must be valid JSON');
-    }
+    return parseJsonFlag('--change-rationales-json', flags['change-rationales-json']);
   }
   return [];
 }
@@ -534,7 +539,7 @@ async function protocolUpdate(args) {
       : {}),
     ...(flags.phase ? { phase: String(flags.phase) } : {}),
     ...(flags['event-type'] ? { eventType: String(flags['event-type']) } : {}),
-    ...(flags['payload-json'] ? { payload: JSON.parse(String(flags['payload-json'])) } : {}),
+    ...(flags['payload-json'] ? { payload: parseJsonFlag('--payload-json', flags['payload-json']) } : {}),
     ...(changeRationales.length > 0 ? { changeRationales } : {})
   };
 
@@ -613,7 +618,7 @@ async function protocolAsk(args) {
     ticketId,
     question,
     ...(flags.phase ? { phase: String(flags.phase) } : {}),
-    ...(flags['payload-json'] ? { payload: JSON.parse(String(flags['payload-json'])) } : {})
+    ...(flags['payload-json'] ? { payload: parseJsonFlag('--payload-json', flags['payload-json']) } : {})
   };
 
   const data = await apiPost(platformUrl, agentToken, localSecret, '/api/protocol/ask', body, timeoutMs);
@@ -750,11 +755,7 @@ async function protocolDeliver(args) {
   if (flags['artifacts-file']) {
     artifacts = await readJsonFileOrStdin(String(flags['artifacts-file']), '--artifacts-file');
   } else if (flags['artifacts-json']) {
-    try {
-      artifacts = JSON.parse(String(flags['artifacts-json']));
-    } catch {
-      throw new Error('--artifacts-json must be valid JSON');
-    }
+    artifacts = parseJsonFlag('--artifacts-json', flags['artifacts-json']);
   }
 
   if (deliverPayload && (flags['change-rationales-file'] || flags['change-rationales-json'])) {
@@ -805,7 +806,7 @@ async function protocolArtifactPrepareUpload(args) {
     ...(flags['artifact-type'] ? { artifactType: String(flags['artifact-type']) } : {}),
     ...(flags['content-type'] ? { contentType: String(flags['content-type']) } : {}),
     ...(flags['file-size'] ? { fileSize: parseInt(String(flags['file-size']), 10) } : {}),
-    ...(flags['metadata-json'] ? { metadata: JSON.parse(String(flags['metadata-json'])) } : {})
+    ...(flags['metadata-json'] ? { metadata: parseJsonFlag('--metadata-json', flags['metadata-json']) } : {})
   };
 
   const data = await apiPost(
@@ -838,7 +839,7 @@ async function protocolArtifactFinalizeUpload(args) {
     ...(flags['artifact-type'] ? { artifactType: String(flags['artifact-type']) } : {}),
     ...(flags['content-type'] ? { contentType: String(flags['content-type']) } : {}),
     ...(flags['file-size'] ? { fileSize: parseInt(String(flags['file-size']), 10) } : {}),
-    ...(flags['metadata-json'] ? { metadata: JSON.parse(String(flags['metadata-json'])) } : {})
+    ...(flags['metadata-json'] ? { metadata: parseJsonFlag('--metadata-json', flags['metadata-json']) } : {})
   };
 
   const data = await apiPost(
@@ -915,7 +916,7 @@ async function protocolArtifactUploadFile(args) {
       artifactType: String(flags['artifact-type'] ?? 'document'),
       contentType,
       fileSize: fileStats.size,
-      ...(flags['metadata-json'] ? { metadata: JSON.parse(String(flags['metadata-json'])) } : {})
+      ...(flags['metadata-json'] ? { metadata: parseJsonFlag('--metadata-json', flags['metadata-json']) } : {})
     },
     timeoutMs
   );
@@ -941,7 +942,7 @@ async function protocolArtifactUploadFile(args) {
       artifactType: String(flags['artifact-type'] ?? 'document'),
       contentType,
       fileSize: fileStats.size,
-      ...(flags['metadata-json'] ? { metadata: JSON.parse(String(flags['metadata-json'])) } : {})
+      ...(flags['metadata-json'] ? { metadata: parseJsonFlag('--metadata-json', flags['metadata-json']) } : {})
     },
     timeoutMs
   );
@@ -1047,7 +1048,9 @@ async function protocolSpawn(args) {
   // When --project-id is not provided, auto-send cwd as workingDirectory so
   // the server can resolve the project from the caller's project_user
   // local_working_directory setting.
-  const workingDirectory = flags['working-directory'] ?? (!flags['project-id'] ? process.cwd() : undefined);
+  const personal = Boolean(flags.personal);
+  const workingDirectory =
+    flags['working-directory'] ?? (!flags['project-id'] && !personal ? process.cwd() : undefined);
 
   const body = {
     objective,
@@ -1057,6 +1060,7 @@ async function protocolSpawn(args) {
     ...(flags.title ? { title: String(flags.title) } : {}),
     ...(flags.priority ? { priority: String(flags.priority) } : {}),
     ...(flags['project-id'] ? { projectId: String(flags['project-id']) } : {}),
+    ...(personal ? { personal: true } : {}),
     ...(workingDirectory ? { workingDirectory: String(workingDirectory) } : {}),
     ...(flags['acceptance-criteria'] ? { acceptanceCriteria: String(flags['acceptance-criteria']) } : {}),
     ...(flags['available-tools'] ? { availableTools: String(flags['available-tools']) } : {}),
@@ -1135,26 +1139,16 @@ async function protocolCreateTicket(args) {
     );
   }
 
-  const workingDirectory = String(flags['working-directory'] ?? process.cwd());
-  const discovered = await apiPost(
-    platformUrl,
-    agentToken,
-    localSecret,
-    '/api/protocol/discover-project',
-    { workingDirectory },
-    timeoutMs
-  );
-
-  const projectId = discovered?.project?.id;
-  if (!projectId) {
-    throw new Error(
-      "Could not resolve project from working directory. Set your local working directory for this project in Overlord or pass --working-directory."
-    );
-  }
+  const standaloneWorkingDirectory =
+    !flags.personal && !flags['project-id']
+      ? String(flags['working-directory'] ?? process.cwd())
+      : undefined;
 
   const standaloneBody = {
     objective,
-    projectId,
+    ...(flags.personal ? { personal: true } : {}),
+    ...(!flags.personal && flags['project-id'] ? { projectId: String(flags['project-id']) } : {}),
+    ...(standaloneWorkingDirectory ? { workingDirectory: standaloneWorkingDirectory } : {}),
     ...(flags.title ? { title: String(flags.title) } : {}),
     ...(flags.priority ? { priority: String(flags.priority) } : {}),
     ...(flags['acceptance-criteria'] ? { acceptanceCriteria: String(flags['acceptance-criteria']) } : {}),
@@ -1224,6 +1218,7 @@ Project discovery:
     ovld protocol discover-project --working-directory /path/to/repo
 
   Use --project-id to override automatic resolution on spawn or ticket creation.
+  Use --personal to create a private ticket without assigning any project.
 
 Subcommands:
   auth-status               Return machine-readable auth status for agent runtimes
@@ -1414,6 +1409,7 @@ spawn:
     --title <text>
     --priority <level>        low | medium | high | urgent
     --project-id <id>         Explicit project; skips working-directory resolution
+    --personal                Create the ticket without assigning a project
     --working-directory <path> Override cwd for project resolution (default: cwd)
     --acceptance-criteria <text>
     --available-tools <text>
@@ -1439,6 +1435,8 @@ create:
     --session-key <key>
     --ticket-id <id>
     --working-directory <path>  Resolve project by your configured local working directory (default: cwd)
+    --project-id <id>           Explicit project for standalone draft creation
+    --personal                  Create a private standalone draft without a project
     --title <text>
     --priority <level>        low | medium | high | urgent
     --acceptance-criteria <text>
@@ -1450,7 +1448,7 @@ create:
   Returns:
     New draft ticket JSON (follow-up draft when session flags are provided)
   Notes:
-    Standalone create auto-discovers the project from the current working directory.
+    Standalone create auto-discovers the project from the current working directory unless --personal is set.
     Follow-up create requires both --session-key and --ticket-id.
 
 artifact-prepare-upload:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overlord-cli",
-  "version": "4.15.0",
+  "version": "4.17.0",
   "description": "Overlord CLI — launch AI agents on tickets from anywhere",
   "type": "module",
   "bin": {