@profoundlogic/coderflow-cli 0.13.10 → 0.13.11-dev.20260809021314.g778dadcc

package/README.md

@@ -90,6 +90,52 @@ visibility.
 When supplying a container ID directly, use the full ID or an unambiguous
 prefix of at least 12 hexadecimal characters.
 
+## Exporting and Importing Tasks
+
+Export a task as a portable ZIP package:
+
+```bash
+coder export <task-id>
+coder export <task-id> --output ./task-backup.zip
+```
+
+The package contains persisted task output and activity history, task metadata,
+container logs, and a `/workspace` snapshot when the retained container is
+available. Runtime-only server credential configuration is not included.
+
+Import an export package or a plain local workspace directory:
+
+```bash
+# 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
+coder import ./my-workspace --environment=myproject
+
+# Store the package as a reusable objective, or launch immediately
+coder import ./task-backup.zip --mode=objective
+coder import ./task-backup.zip --mode=running
+```
+
+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
 
 Manage connection settings:

package/coder.js

@@ -20,6 +20,8 @@ import { attachToContainer } from './lib/commands/attach.js';
 import { handleConfig } from './lib/commands/config.js';
 import { handleProfile } from './lib/commands/profile.js';
 import { runTest } from './lib/commands/test.js';
+import { exportTask } from './lib/commands/export.js';
+import { importTask } from './lib/commands/import.js';
 import { setCliProfileOverride } from './lib/config.js';
 import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
@@ -167,6 +169,14 @@ async function main() {
         await runTest(args.slice(1));
         break;
 
+      case 'export':
+        await exportTask(args.slice(1));
+        break;
+
+      case 'import':
+        await importTask(args.slice(1));
+        break;
+
       case 'start':
         await startInteractive(args.slice(1));
         break;

package/lib/commands/export.js

@@ -0,0 +1,126 @@
+/**
+ * Command: coder export - Download a portable task package.
+ */
+
+import { createWriteStream, promises as fs } from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { getApiKey, getServerUrl } from '../config.js';
+import { buildHttpError } from '../http-client.js';
+
+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];
+    if (arg === '--output' || arg === '-o') {
+      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 {
+      throw new Error(`Unexpected export argument: ${arg}`);
+    }
+  }
+
+  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) {
+  const disposition = response.headers.get('content-disposition') || '';
+  const match = disposition.match(/filename="([^"]+)"/i);
+  return match?.[1] || `coderflow-task-${taskId}.zip`;
+}
+
+export async function writeExportStream(source, destination) {
+  const directory = path.dirname(destination);
+  const temporaryPath = path.join(
+    directory,
+    `.coderflow-export-${process.pid}-${randomUUID()}.tmp`
+  );
+
+  try {
+    await pipeline(source, createWriteStream(temporaryPath, { flags: 'wx' }));
+    // Publishing with a hard link is atomic and fails with EEXIST instead of
+    // replacing a destination another process (or the user) already owns.
+    await fs.link(temporaryPath, destination);
+  } finally {
+    await fs.rm(temporaryPath, { force: true }).catch(() => {});
+  }
+}
+
+export async function exportTask(args = []) {
+  const { taskId, output, workspace } = parseExportArgs(args);
+  const serverUrl = await getServerUrl();
+  const apiKey = await getApiKey();
+  const query = workspace ? `?workspace=${encodeURIComponent(workspace)}` : '';
+  const response = await fetch(`${serverUrl}/tasks/${encodeURIComponent(taskId)}/export${query}`, {
+    headers: apiKey ? { Authorization: `Bearer ${apiKey}` } : {}
+  });
+
+  if (!response.ok) {
+    const contentType = response.headers.get('content-type') || '';
+    const body = contentType.includes('application/json')
+      ? await response.json()
+      : await response.text();
+    throw buildHttpError(response.status, body);
+  }
+
+  const destination = path.resolve(output || getResponseFilename(response, taskId));
+  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

@@ -0,0 +1,200 @@
+/**
+ * Command: coder import - Import a task export or local workspace directory.
+ */
+
+import { createWriteStream, openAsBlob, promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { ZipArchive } from 'archiver';
+import { getApiKey, getServerUrl } from '../config.js';
+import { buildHttpError } from '../http-client.js';
+
+function takeOption(args, index, name) {
+  const arg = args[index];
+  if (arg === `--${name}`) {
+    if (!args[index + 1]) throw new Error(`--${name} requires a value`);
+    return { value: args[index + 1], consumed: 2 };
+  }
+  if (arg.startsWith(`--${name}=`)) {
+    return { value: arg.slice(name.length + 3), consumed: 1 };
+  }
+  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: '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);
+      if (!parsed) continue;
+      options[name] = parsed.value;
+      index += parsed.consumed;
+      matched = true;
+      break;
+    }
+    if (matched) continue;
+    if (!arg.startsWith('-') && !source) {
+      source = arg;
+      index += 1;
+      continue;
+    }
+    throw new Error(`Unexpected import argument: ${arg}`);
+  }
+
+  if (!source) throw new Error('Path required. Usage: coder import <directory-or-zip> [options]');
+  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');
+  await new Promise((resolve, reject) => {
+    const output = createWriteStream(zipPath, { flags: 'wx' });
+    const archive = new ZipArchive({ zlib: { level: 6 } });
+    output.on('close', resolve);
+    output.on('error', reject);
+    archive.on('error', reject);
+    archive.pipe(output);
+    archive.directory(sourceDir, false);
+    archive.finalize().catch(reject);
+  });
+  return { zipPath, tempDir };
+}
+
+export async function importTask(args = []) {
+  const { source, options } = parseImportArgs(args);
+  const sourcePath = path.resolve(source);
+  const sourceStats = await fs.stat(sourcePath).catch(() => null);
+  if (!sourceStats) throw new Error(`Import path does not exist: ${sourcePath}`);
+
+  let archivePath = sourcePath;
+  let tempDir = null;
+  if (sourceStats.isDirectory()) {
+    console.log(`Packaging workspace directory ${sourcePath}...`);
+    ({ zipPath: archivePath, tempDir } = await zipDirectory(sourcePath));
+  } else if (path.extname(sourcePath).toLowerCase() !== '.zip') {
+    throw new Error('Import path must be a directory or .zip file');
+  }
+
+  try {
+    const form = new FormData();
+    form.append('archive', await openAsBlob(archivePath, { type: 'application/zip' }), path.basename(archivePath));
+    for (const [key, value] of Object.entries(options)) {
+      if (value != null && value !== '') form.append(key, value);
+    }
+
+    const serverUrl = await getServerUrl();
+    const apiKey = await getApiKey();
+    const response = await fetch(`${serverUrl}/tasks/import`, {
+      method: 'POST',
+      headers: apiKey ? { Authorization: `Bearer ${apiKey}` } : {},
+      body: form
+    });
+    const contentType = response.headers.get('content-type') || '';
+    const data = contentType.includes('application/json')
+      ? await response.json()
+      : await response.text();
+    if (!response.ok) throw buildHttpError(response.status, data);
+
+    console.log(`Task import created ${data.status} ${data.taskId}`);
+    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

@@ -182,6 +182,73 @@ Examples:
   coder logs 1759542727986-3uoyf48lr --tail=100
 `,
 
+  export: `
+Usage: coder export <task-id> [options]
+
+Download a portable task package containing task output, logs, metadata, and
+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]
+
+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>         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
+`,
+
   list: `
 Usage: coder list [options]
 
@@ -327,6 +394,8 @@ 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> [--workspace=delta|full]    Export task contents and logs
+  coder import <directory-or-zip> [options]          Import an objective or task container
 
 Setup:
   coder login [--sso]                                Authenticate with server
@@ -389,6 +458,8 @@ 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> [--workspace=delta|full]    Export task contents and logs
+  coder import <directory-or-zip> [options]          Restore an objective or task
 
 Interactive Sessions:
   coder start <environment> [options]                Start interactive session with AI agent
@@ -445,6 +516,8 @@ Task Management (Web UI alternative):
   coder status 1759542727986-3uoyf48lr               # Check task status
   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                     # 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.10",
+  "version": "0.13.11-dev.20260809021314.g778dadcc",
   "description": "AI Coder CLI - Command-line interface for managing AI coding tasks",
   "main": "coder.js",
   "type": "module",
@@ -28,8 +28,9 @@
   "license": "SEE LICENSE IN LICENSE.txt",
   "homepage": "https://coderflow.ai",
   "dependencies": {
-    "ws": "^8.21.1",
     "@inquirer/prompts": "^8.5.2",
-    "open": "^11.0.0"
+    "archiver": "^8.0.0",
+    "open": "^11.0.0",
+    "ws": "^8.21.1"
   }
 }