@profoundlogic/coderflow-cli 0.13.11-dev.20260807233136.g074f26b1 → 0.13.11

package/README.md

@@ -106,7 +106,7 @@ available. Runtime-only server credential configuration is not included.
 Import an export package or a plain local workspace directory:
 
 ```bash
-# Restore a ready-to-use staged container (default)
+# Restore the task in the state it was exported in (default)
 coder import ./task-backup.zip
 
 # Package a directory and restore it into an environment
@@ -117,10 +117,24 @@ coder import ./task-backup.zip --mode=objective
 coder import ./task-backup.zip --mode=running
 ```
 
-Import modes are `objective`, `staged` (the default), and `running`. Use
-`--environment`, `--name`, `--agent`, or `--instructions` to override package
-metadata. In the Web UI, **Import** creates an objective from the Objectives
-view and a staged task from the Tasks or Board view.
+Import modes are `preserve` (the default), `objective`, `staged`, `running`,
+and `completed`. `preserve` reproduces the exported state: a finished task
+imports as a finished task, an objective as an objective, and anything else —
+including a plain workspace directory, which carries no state — as a staged
+task. Use `--environment`, `--name`, `--agent`, or `--instructions` to override
+package metadata. In the Web UI, **Import** creates an objective from the
+Objectives view and preserves the exported state everywhere else.
+
+A restored task keeps its transcript, its follow-up history, and its changed
+files: the changed-files list is recomputed against the destination's own
+repositories once the workspace is restored, so the Changed Files tab and the
+approve dialog are populated as soon as the import finishes.
+
+Continuing an imported conversation replays it rather than resuming it. An
+agent session belongs to the container that created it, and the destination
+container has never run the agent, so the first message after an import hands
+the agent the imported transcript as context — the same mechanism a forked task
+uses.
 
 ## Configuration and Profiles
 

package/lib/commands/export.js

@@ -10,9 +10,14 @@ import { pipeline } from 'node:stream/promises';
 import { getApiKey, getServerUrl } from '../config.js';
 import { buildHttpError } from '../http-client.js';
 
-function parseExportArgs(args) {
+const WORKSPACE_MODES = ['delta', 'full', 'none'];
+
+const USAGE = 'Usage: coder export <task-id> [--output <file.zip>] [--workspace delta|full|none]';
+
+export function parseExportArgs(args) {
   let taskId = null;
   let output = null;
+  let workspace = null;
 
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
@@ -20,6 +25,10 @@ function parseExportArgs(args) {
       output = args[++index];
     } else if (arg.startsWith('--output=')) {
       output = arg.slice('--output='.length);
+    } else if (arg === '--workspace') {
+      workspace = args[++index];
+    } else if (arg.startsWith('--workspace=')) {
+      workspace = arg.slice('--workspace='.length);
     } else if (!arg.startsWith('-') && !taskId) {
       taskId = arg;
     } else {
@@ -27,8 +36,45 @@ function parseExportArgs(args) {
     }
   }
 
-  if (!taskId) throw new Error('Task ID required. Usage: coder export <task-id> [--output <file.zip>]');
-  return { taskId, output };
+  if (!taskId) throw new Error(`Task ID required. ${USAGE}`);
+  if (workspace != null && !WORKSPACE_MODES.includes(workspace)) {
+    throw new Error(`--workspace must be ${WORKSPACE_MODES.join(', ')}`);
+  }
+  return { taskId, output, workspace };
+}
+
+/**
+ * Describe what the server's capture actually carried.
+ *
+ * The archive body is a zip, so the capture summary travels in headers. An
+ * export that came back without a workspace says why, because "the delta was
+ * over the size cap" and "the task changed nothing" are not the same news.
+ */
+export function describeExportWorkspace(headers) {
+  const mode = headers.get('x-coderflow-workspace-mode') || 'none';
+  const reasonHeader = headers.get('x-coderflow-workspace-reason');
+  let reason = null;
+  if (reasonHeader) {
+    try {
+      reason = decodeURIComponent(reasonHeader);
+    } catch {
+      reason = reasonHeader;
+    }
+  }
+
+  if (mode === 'none') {
+    return reason ? `Workspace: not included (${reason})` : 'Workspace: not included';
+  }
+  if (mode !== 'delta') {
+    return 'Workspace: full capture';
+  }
+
+  const files = Number(headers.get('x-coderflow-workspace-files')) || 0;
+  const bytes = Number(headers.get('x-coderflow-workspace-bytes')) || 0;
+  const deleted = Number(headers.get('x-coderflow-workspace-deleted')) || 0;
+  const parts = [`${files} changed file${files === 1 ? '' : 's'} (${bytes} bytes)`];
+  if (deleted > 0) parts.push(`${deleted} deleted path${deleted === 1 ? '' : 's'}`);
+  return `Workspace: delta - ${parts.join(', ')}`;
 }
 
 function getResponseFilename(response, taskId) {
@@ -55,10 +101,11 @@ export async function writeExportStream(source, destination) {
 }
 
 export async function exportTask(args = []) {
-  const { taskId, output } = parseExportArgs(args);
+  const { taskId, output, workspace } = parseExportArgs(args);
   const serverUrl = await getServerUrl();
   const apiKey = await getApiKey();
-  const response = await fetch(`${serverUrl}/tasks/${encodeURIComponent(taskId)}/export`, {
+  const query = workspace ? `?workspace=${encodeURIComponent(workspace)}` : '';
+  const response = await fetch(`${serverUrl}/tasks/${encodeURIComponent(taskId)}/export${query}`, {
     headers: apiKey ? { Authorization: `Bearer ${apiKey}` } : {}
   });
 
@@ -74,5 +121,6 @@ export async function exportTask(args = []) {
   await fs.mkdir(path.dirname(destination), { recursive: true });
   await writeExportStream(Readable.fromWeb(response.body), destination);
   console.log(`Task ${taskId} exported to ${destination}`);
+  console.log(describeExportWorkspace(response.headers));
   return destination;
 }

package/lib/commands/import.js

@@ -21,13 +21,26 @@ function takeOption(args, index, name) {
   return null;
 }
 
+// `preserve` is not a state of its own: it asks the server to land the task in
+// whatever state it was exported from, which is what makes a round trip a round
+// trip. The explicit modes force a state instead.
+export const IMPORT_MODES = ['preserve', 'objective', 'staged', 'running', 'completed'];
+
 export function parseImportArgs(args) {
   let source = null;
-  const options = { mode: 'staged' };
+  const options = { mode: 'preserve' };
   const names = ['mode', 'environment', 'name', 'agent', 'instructions'];
 
   for (let index = 0; index < args.length;) {
     const arg = args[index];
+    // A delta records the base each repository came from. By default a
+    // differing base is reported and the import proceeds; this asks the server
+    // to refuse instead.
+    if (arg === '--require-matching-base') {
+      options.requireMatchingBase = 'true';
+      index += 1;
+      continue;
+    }
     let matched = false;
     for (const name of names) {
       const parsed = takeOption(args, index, name);
@@ -47,12 +60,78 @@ export function parseImportArgs(args) {
   }
 
   if (!source) throw new Error('Path required. Usage: coder import <directory-or-zip> [options]');
-  if (!['objective', 'staged', 'running'].includes(options.mode)) {
-    throw new Error('--mode must be objective, staged, or running');
+  if (!IMPORT_MODES.includes(options.mode)) {
+    throw new Error(`--mode must be one of ${IMPORT_MODES.join(', ')}`);
   }
   return { source, options };
 }
 
+/**
+ * Say which state the import landed in, and — for a preserved import — that it
+ * was the package that decided.
+ */
+export function describeImportState(data = {}) {
+  const state = data.mode === 'objective' ? 'objective' : `${data.status} task`;
+  const preserved = data.requestedMode === 'preserve' && data.importedStatus
+    ? ` (preserved from the exported ${data.importedStatus} task)`
+    : '';
+  return `Imported as ${state}${preserved}`;
+}
+
+/**
+ * An imported conversation is replayed, not resumed: the destination container
+ * has never run this agent, so there is no session to attach to. Say so, or a
+ * user reading "completed" will expect `--continue` semantics they will not get.
+ */
+export function describeImportConversation(data = {}) {
+  if (data.conversationMode === 'history_replay') {
+    return 'Conversation: the imported transcript replays into a fresh agent session on your next message.';
+  }
+  if (data.conversationMode === 'instructions_replay') {
+    return 'Conversation: no transcript travelled with this package, so the next message replays the '
+      + 'imported instructions and follow-up history into a fresh agent session.';
+  }
+  return null;
+}
+
+/**
+ * Say what the import will do to the destination workspace: merge a delta into
+ * it, or replace it outright.
+ */
+export function describeImportWorkspace(data = {}) {
+  if (!data.workspaceIncluded) {
+    // "not included" alone reads as a task that changed nothing. If the export
+    // said why it carried no workspace, say it here too.
+    return data.workspaceUnavailableReason
+      ? `Workspace: not included (${data.workspaceUnavailableReason})`
+      : 'Workspace: not included';
+  }
+  if (data.workspaceMode !== 'delta' || !data.workspaceDelta) {
+    return 'Workspace: full archive (replaces the initialized workspace)';
+  }
+
+  const { fileCount = 0, byteCount = 0, deletedPathCount = 0, repositories = [] } = data.workspaceDelta;
+  const parts = [`${fileCount} changed file${fileCount === 1 ? '' : 's'} (${byteCount} bytes)`];
+  if (deletedPathCount > 0) parts.push(`${deletedPathCount} deleted path${deletedPathCount === 1 ? '' : 's'}`);
+  if (repositories.length > 0) parts.push(`repos: ${repositories.join(', ')}`);
+  return `Workspace: delta merged into the initialized workspace - ${parts.join(', ')}`;
+}
+
+/**
+ * The base check cannot run before the server answers: it compares against
+ * repositories that only exist once the destination container has finished
+ * cloning them, which happens after the import is accepted. Say so, rather than
+ * letting a printed success imply the check already passed.
+ */
+export function describeBaseCheck(data = {}) {
+  if (!data.requireMatchingBase) return null;
+  if (!data.workspaceIncluded || data.workspaceMode !== 'delta') {
+    return 'Base match: requested, but this package carries no delta to check.';
+  }
+  return 'Base match: required. The check runs once the destination repositories are cloned; '
+    + `if the base differs the import stops and task ${data.taskId} is marked failed.`;
+}
+
 async function zipDirectory(sourceDir) {
   const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'coderflow-cli-import-'));
   const zipPath = path.join(tempDir, 'workspace.zip');
@@ -108,6 +187,12 @@ export async function importTask(args = []) {
     if (data.containerId) console.log(`Container: ${data.containerId}`);
     if (data.queuePosition) console.log(`Queue position: ${data.queuePosition}`);
     console.log(`Environment: ${data.environment}`);
+    console.log(describeImportState(data));
+    console.log(describeImportWorkspace(data));
+    const conversation = describeImportConversation(data);
+    if (conversation) console.log(conversation);
+    const baseCheck = describeBaseCheck(data);
+    if (baseCheck) console.log(baseCheck);
     return data;
   } finally {
     if (tempDir) await fs.rm(tempDir, { recursive: true, force: true });

package/lib/help.js

@@ -186,39 +186,66 @@ Examples:
 Usage: coder export <task-id> [options]
 
 Download a portable task package containing task output, logs, metadata, and
-the retained container workspace when it is available.
+the workspace changes the task made.
+
+By default the package carries a workspace *delta*: only the files the task
+added or modified, plus the list of paths it deleted. Importing it merges that
+into the destination environment's own initialized workspace, so dependencies
+and untouched sources are neither shipped nor overwritten.
 
 Arguments:
   task-id               Task ID to export (required)
 
 Options:
   --output, -o <file>   Destination zip path (defaults to the server filename)
+  --workspace=<mode>    delta (default), full, or none.
+                        full archives the entire /workspace and replaces the
+                        destination workspace on import; none omits it.
 
 Examples:
   coder export 1759542727986-3uoyf48lr
   coder export 1759542727986-3uoyf48lr --output ./task-backup.zip
+  coder export 1759542727986-3uoyf48lr --workspace=full
 `,
 
   import: `
 Usage: coder import <directory-or-zip> [options]
 
-Create a new objective or task from a CoderFlow export package or a plain
+Recreate a task from a CoderFlow export package, or create one from a plain
 workspace directory. Plain directories are packaged before upload.
 
+By default the import reproduces the state the task was exported from: a
+finished task comes back finished, with its transcript and its changed files,
+ready to be continued. Its container has never run the agent, so the first
+message replays the imported conversation into a fresh session rather than
+resuming one.
+
 Arguments:
   directory-or-zip      Export zip or local workspace directory (required)
 
 Options:
-  --mode=<mode>         objective, staged, or running (default: staged)
+  --mode=<mode>         preserve (default), objective, staged, running, or
+                        completed. preserve reproduces the exported state;
+                        the others force one. A plain workspace directory has
+                        no exported state, so preserve stages it.
   --environment=<name>  Override/select the destination environment
   --name=<name>         Override the imported task name
   --agent=<agent>       Override the imported/default agent
   --instructions=<text> Override instructions used when the task runs
+  --require-matching-base
+                        Refuse a workspace delta whose repositories were
+                        exported from a different base commit, remote, or
+                        branch. Without it the mismatch is reported and the
+                        delta is applied anyway. The check needs the
+                        destination's repositories, so it runs after the
+                        import is accepted: a refusal shows up as a failed
+                        task, not as a failed command.
 
 Examples:
   coder import ./task-backup.zip
   coder import ./workspace --environment=hello --mode=staged
   coder import ./task-backup.zip --mode=objective
+  coder import ./task-backup.zip --mode=completed
   coder import ./task-backup.zip --mode=running --agent=codex
 `,
 
@@ -367,7 +394,7 @@ Commands:
   coder apply [task-id]                              Apply patches from completed task to local repos
   coder discard [--env=<environment>] [--yes]        Discard applied changes from repos
   coder attach [container-or-task-id] [options]      Connect to a running container
-  coder export <task-id> [--output=<file.zip>]       Export task contents and logs
+  coder export <task-id> [--workspace=delta|full]    Export task contents and logs
   coder import <directory-or-zip> [options]          Import an objective or task container
 
 Setup:
@@ -431,7 +458,7 @@ Task Management:
   coder logs <task-id> [--tail=N]                    Show task logs
   coder list [--status=...] [--environment=...]      List tasks with optional filters
   coder reject <task-id> [--cleanup]                 Reject task results
-  coder export <task-id> [--output=file.zip]         Export task contents and logs
+  coder export <task-id> [--workspace=delta|full]    Export task contents and logs
   coder import <directory-or-zip> [options]          Restore an objective or task
 
 Interactive Sessions:
@@ -490,7 +517,7 @@ Task Management (Web UI alternative):
   coder results 1759542727986-3uoyf48lr              # Get task results
   coder list --status=completed                      # List completed tasks
   coder export 1759542727986-3uoyf48lr               # Download a portable task package
-  coder import ./task-export.zip --mode=staged       # Restore into a staged container
+  coder import ./task-export.zip                     # Restore it in the state it was exported in
 
 Interactive Sessions (Web UI alternative):
   coder start hello                                  # Start AI agent in environment

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profoundlogic/coderflow-cli",
-  "version": "0.13.11-dev.20260807233136.g074f26b1",
+  "version": "0.13.11",
   "description": "AI Coder CLI - Command-line interface for managing AI coding tasks",
   "main": "coder.js",
   "type": "module",