@empirical-gauzza/cli 1.0.38 → 1.0.40

package/lib/attachmentCommands.js

@@ -1,388 +1,388 @@
-'use strict';
-
-// `empirical memory attachment <list|add|get|delete|restore>` over the four REST routes in
-// packages/server/src/routes/memories.ts (POST/GET/DELETE /:id/attachments[/:attachmentId] and
-// the restore POST). Attachments shipped REST-only; this is the first non-REST door.
-//
-// Two things here are not style choices:
-//  1. `get` writes BYTES. It never goes through httpJson, which decodes utf8 and would corrupt
-//     every non-text file, and it never prints the body to stdout unless asked (--out -), so a
-//     stray download cannot dump a binary into a terminal or a piped JSON stream.
-//  2. The per-file cap is checked locally BEFORE the upload. The server refuses an oversized
-//     body at ingress, but only after the client has pushed 25MB+ up the wire for nothing.
-
-const fs = require('fs');
-const path = require('path');
-const { log, warn } = require('./ui');
-const { httpJson, httpMultipart, httpDownload, printApiError } = require('./http');
-const { parseOption, parseFlag } = require('./env');
-const { requireAccessToken, resolveApiBaseUrl, buildApiAuthHeaders } = require('./auth');
-const { resolveMemoryByQuery, parseMatchFilters, printMemoryResolveError } = require('./memoryResolve');
-
-// Mirrors MAX_ATTACHMENT_BYTES / MAX_ATTACHMENTS_PER_MEMORY in packages/shared/src/
-// subscriptionPlans.ts. The CLI is published as its own npm package and cannot depend on the
-// workspace, so these are copied; they are used for a friendlier local error only, never to
-// decide anything the server does not re-check.
-const MAX_ATTACHMENT_BYTES = 25 * 1024 * 1024;
-
-// Enough to label the common cases. The server sniffs magic bytes and overrides anything
-// renderable or executable, so a wrong guess here is corrected, never trusted.
-const MIME_BY_EXTENSION = {
-  '.txt': 'text/plain',
-  '.md': 'text/markdown',
-  '.json': 'application/json',
-  '.csv': 'text/csv',
-  '.pdf': 'application/pdf',
-  '.png': 'image/png',
-  '.jpg': 'image/jpeg',
-  '.jpeg': 'image/jpeg',
-  '.gif': 'image/gif',
-  '.webp': 'image/webp',
-  '.svg': 'image/svg+xml',
-  '.zip': 'application/zip',
-  '.mp3': 'audio/mpeg',
-  '.m4a': 'audio/mp4',
-  '.wav': 'audio/wav',
-  '.mp4': 'video/mp4'
-};
-
-const ATTACHMENT_SUBCOMMAND_USAGE = {
-  list: 'Usage: empirical memory attachment list (--memory-id <id> | --match <query>) [--include-deleted] [--format table] [--pretty]',
-  add: 'Usage: empirical memory attachment add (--memory-id <id> | --match <query>) --file <path> [--author-type user|agent] [--min-score 0.35]',
-  get: 'Usage: empirical memory attachment get (--memory-id <id> | --match <query>) --attachment-id <id> [--out <path>] [--force]\n  --out - writes the bytes to stdout.',
-  delete: 'Usage: empirical memory attachment delete (--memory-id <id> | --match <query>) --attachment-id <id> [--confirm]\n  Soft delete: the file is restorable for 30 days, then purged.',
-  restore: 'Usage: empirical memory attachment restore (--memory-id <id> | --match <query>) --attachment-id <id>'
-};
-
-function printAttachmentHelp(sub) {
-  if (sub && ATTACHMENT_SUBCOMMAND_USAGE[sub]) {
-    log(ATTACHMENT_SUBCOMMAND_USAGE[sub]);
-    return;
-  }
-  log('Files attached to a memory. Up to 20 per memory, 25MB each; a delete is reversible for 30 days.');
-  log('');
-  for (const usage of Object.values(ATTACHMENT_SUBCOMMAND_USAGE)) log(usage);
-  log('');
-  log('Shorthands: `memory attach` = `memory attachment add`, `memory attachments` = `memory attachment list`.');
-}
-
-function guessContentType(filename) {
-  return MIME_BY_EXTENSION[path.extname(String(filename || '')).toLowerCase()] || 'application/octet-stream';
-}
-
-function fail(code, message, extra = {}) {
-  warn(JSON.stringify({ error: true, code, message, ...extra }));
-  process.exit(1);
-}
-
-// Every subcommand takes the same target: an explicit id, or a --match query resolved the same
-// way `memory note` and `memory delete` resolve theirs.
-async function resolveTargetMemoryId(args, accessToken, baseUrl, usage) {
-  const memoryId = parseOption(args, '--memory-id', '');
-  if (memoryId) return memoryId;
-
-  const match = parseOption(args, '--match', '');
-  if (!match) {
-    warn(usage);
-    process.exit(1);
-  }
-
-  const minScore = Number(parseOption(args, '--min-score', '0.35'));
-  const result = await resolveMemoryByQuery(match, minScore, accessToken, baseUrl, parseMatchFilters(args));
-  if (!result.found) {
-    printMemoryResolveError(result);
-    process.exit(1);
-  }
-  return result.memory.id;
-}
-
-function attachmentsUrl(baseUrl, memoryId, suffix = '') {
-  return new URL(`/api/v1/memories/${encodeURIComponent(memoryId)}/attachments${suffix}`, baseUrl).toString();
-}
-
-function renderAttachmentsTable(rows) {
-  const header = ['ID', 'FILENAME', 'BYTES', 'TYPE', 'STATE'];
-  const body = rows.map((row) => [
-    String(row.id || ''),
-    String(row.filename || ''),
-    String(row.bytes != null ? row.bytes : ''),
-    String(row.mimeType || ''),
-    row.deletedAt ? `deleted, purges ${String(row.purgeAfter || '').slice(0, 10)}` : 'live'
-  ]);
-  const widths = header.map((_h, i) => Math.max(header[i].length, ...body.map((r) => r[i].length), 1));
-  const line = (cells) => cells.map((c, i) => c.padEnd(widths[i])).join('  ').trimEnd();
-  log(line(header));
-  log(widths.map((w) => '-'.repeat(w)).join('  '));
-  for (const row of body) log(line(row));
-}
-
-async function runAttachmentList(args) {
-  const accessToken = requireAccessToken();
-  const baseUrl = resolveApiBaseUrl();
-  const memoryId = await resolveTargetMemoryId(args, accessToken, baseUrl, ATTACHMENT_SUBCOMMAND_USAGE.list);
-
-  const url = attachmentsUrl(baseUrl, memoryId) + (parseFlag(args, '--include-deleted') ? '?includeDeleted=true' : '');
-
-  let response;
-  try {
-    response = await httpJson(url, 'GET', undefined, buildApiAuthHeaders(accessToken));
-  } catch (error) {
-    printApiError(error);
-    process.exit(1);
-  }
-
-  // This route answers with `attachments` at the TOP level, not under `data` like most of the
-  // memory routes; reading response.data here would silently print nothing.
-  const attachments = Array.isArray(response && response.attachments) ? response.attachments : [];
-
-  if (parseOption(args, '--format', '') === 'table') {
-    if (!attachments.length) {
-      log('No attachments on this memory.');
-      return;
-    }
-    renderAttachmentsTable(attachments);
-    return;
-  }
-
-  const payload = {
-    memoryId: response.memoryId || memoryId,
-    attachmentsCount: response.attachmentsCount != null ? response.attachmentsCount : attachments.length,
-    attachments
-  };
-  log(parseFlag(args, '--pretty') ? JSON.stringify(payload, null, 2) : JSON.stringify(payload));
-}
-
-async function runAttachmentAdd(args) {
-  const filePath = parseOption(args, '--file', '');
-  if (!filePath) {
-    warn(ATTACHMENT_SUBCOMMAND_USAGE.add);
-    process.exit(1);
-  }
-
-  const resolved = path.resolve(filePath);
-  let stat;
-  try {
-    stat = fs.statSync(resolved);
-  } catch (_error) {
-    fail('file_not_found', `No such file: ${resolved}`);
-  }
-  if (!stat.isFile()) {
-    fail('not_a_file', `Not a file: ${resolved}`);
-  }
-  if (stat.size === 0) {
-    fail('empty_file', `File is empty: ${resolved}`);
-  }
-  // Local pre-check, see note 2 at the top of this file.
-  if (stat.size > MAX_ATTACHMENT_BYTES) {
-    fail('attachment_too_large', `File is ${stat.size} bytes; the per-file limit is ${MAX_ATTACHMENT_BYTES} bytes (25MB).`, {
-      bytes: stat.size,
-      maxBytes: MAX_ATTACHMENT_BYTES
-    });
-  }
-
-  const authorType = parseOption(args, '--author-type', '');
-  if (authorType && !['user', 'agent', 'system'].includes(authorType)) {
-    fail('invalid_author_type', `Invalid --author-type "${authorType}". Valid: user, agent, system`);
-  }
-
-  const accessToken = requireAccessToken();
-  const baseUrl = resolveApiBaseUrl();
-  const memoryId = await resolveTargetMemoryId(args, accessToken, baseUrl, ATTACHMENT_SUBCOMMAND_USAGE.add);
-
-  const filename = path.basename(resolved);
-  let response;
-  try {
-    response = await httpMultipart(
-      attachmentsUrl(baseUrl, memoryId),
-      'POST',
-      {
-        // Same authorship contract as `memory record`: `source` is observable truth, authorType
-        // is only declared when the caller says so, never guessed.
-        fields: { source: 'cli', ...(authorType ? { authorType } : {}) },
-        file: { field: 'file', filename, contentType: guessContentType(filename), buffer: fs.readFileSync(resolved) }
-      },
-      buildApiAuthHeaders(accessToken)
-    );
-  } catch (error) {
-    printApiError(error);
-    process.exit(1);
-  }
-
-  const data = (response && response.data) ? response.data : response;
-  log(JSON.stringify({ attached: true, ...data, ...(response.warnings ? { warnings: response.warnings } : {}) }));
-}
-
-// Content-Disposition from the download route is always the RFC 5987 form
-// (filename*=UTF-8''<pct-encoded>), so that is what is parsed; the plain filename="..." form is
-// accepted too in case a proxy rewrites it.
-function filenameFromContentDisposition(header) {
-  const value = String(header || '');
-  const extended = value.match(/filename\*=UTF-8''([^;]+)/i);
-  if (extended) {
-    try {
-      return decodeURIComponent(extended[1]);
-    } catch (_error) {
-      // Fall through to the plain form below.
-    }
-  }
-  const plain = value.match(/filename="([^"]+)"/i);
-  return plain ? plain[1] : '';
-}
-
-async function runAttachmentGet(args) {
-  const attachmentId = parseOption(args, '--attachment-id', '');
-  if (!attachmentId) {
-    warn(ATTACHMENT_SUBCOMMAND_USAGE.get);
-    process.exit(1);
-  }
-
-  const accessToken = requireAccessToken();
-  const baseUrl = resolveApiBaseUrl();
-  const memoryId = await resolveTargetMemoryId(args, accessToken, baseUrl, ATTACHMENT_SUBCOMMAND_USAGE.get);
-
-  let result;
-  try {
-    result = await httpDownload(
-      attachmentsUrl(baseUrl, memoryId, `/${encodeURIComponent(attachmentId)}`),
-      buildApiAuthHeaders(accessToken)
-    );
-  } catch (error) {
-    printApiError(error);
-    process.exit(1);
-  }
-
-  const out = parseOption(args, '--out', '');
-  if (out === '-') {
-    process.stdout.write(result.buffer);
-    return;
-  }
-
-  // The server's filename is only ever used as a BASENAME. It is attacker-supplied as far as
-  // this process is concerned, and joining a path that carries .. or a drive letter straight
-  // onto cwd would let a download write outside the directory the user chose.
-  const suggested = path.basename(filenameFromContentDisposition(result.headers['content-disposition']) || '') || 'attachment';
-  let target = out ? path.resolve(out) : path.resolve(process.cwd(), suggested);
-  if (out) {
-    try {
-      if (fs.statSync(target).isDirectory()) target = path.join(target, suggested);
-    } catch (_error) {
-      // --out names a file that does not exist yet, which is the normal case.
-    }
-  }
-
-  if (fs.existsSync(target) && !parseFlag(args, '--force')) {
-    fail('file_exists', `${target} already exists. Pass --force to overwrite, or --out <path> to write elsewhere.`, { path: target });
-  }
-
-  try {
-    fs.writeFileSync(target, result.buffer);
-  } catch (error) {
-    fail('write_failed', `Could not write ${target}: ${error.message}`);
-  }
-
-  log(JSON.stringify({ downloaded: true, memoryId, attachmentId, path: target, bytes: result.buffer.length }));
-}
-
-async function runAttachmentDelete(args) {
-  const attachmentId = parseOption(args, '--attachment-id', '');
-  if (!attachmentId) {
-    warn(ATTACHMENT_SUBCOMMAND_USAGE.delete);
-    process.exit(1);
-  }
-
-  const accessToken = requireAccessToken();
-  const baseUrl = resolveApiBaseUrl();
-  const memoryId = await resolveTargetMemoryId(args, accessToken, baseUrl, ATTACHMENT_SUBCOMMAND_USAGE.delete);
-
-  // Same gate as `memory delete`: without --confirm this only reports what it would do.
-  if (!parseFlag(args, '--confirm')) {
-    log(JSON.stringify({ dryRun: true, wouldDelete: true, memoryId, attachmentId, note: 'Re-run with --confirm. The file stays restorable for 30 days.' }));
-    return;
-  }
-
-  let response;
-  try {
-    response = await httpJson(
-      attachmentsUrl(baseUrl, memoryId, `/${encodeURIComponent(attachmentId)}`),
-      'DELETE',
-      null,
-      buildApiAuthHeaders(accessToken)
-    );
-  } catch (error) {
-    printApiError(error);
-    process.exit(1);
-  }
-
-  const data = (response && response.data) ? response.data : response;
-  log(JSON.stringify({ deleted: true, ...data }));
-}
-
-async function runAttachmentRestore(args) {
-  const attachmentId = parseOption(args, '--attachment-id', '');
-  if (!attachmentId) {
-    warn(ATTACHMENT_SUBCOMMAND_USAGE.restore);
-    process.exit(1);
-  }
-
-  const accessToken = requireAccessToken();
-  const baseUrl = resolveApiBaseUrl();
-  const memoryId = await resolveTargetMemoryId(args, accessToken, baseUrl, ATTACHMENT_SUBCOMMAND_USAGE.restore);
-
-  let response;
-  try {
-    response = await httpJson(
-      attachmentsUrl(baseUrl, memoryId, `/${encodeURIComponent(attachmentId)}/restore`),
-      'POST',
-      {},
-      buildApiAuthHeaders(accessToken)
-    );
-  } catch (error) {
-    printApiError(error);
-    process.exit(1);
-  }
-
-  const data = (response && response.data) ? response.data : response;
-  log(JSON.stringify({ restored: true, ...data }));
-}
-
-const ATTACHMENT_SUBCOMMANDS = {
-  list: runAttachmentList,
-  ls: runAttachmentList,
-  add: runAttachmentAdd,
-  upload: runAttachmentAdd,
-  get: runAttachmentGet,
-  download: runAttachmentGet,
-  delete: runAttachmentDelete,
-  rm: runAttachmentDelete,
-  remove: runAttachmentDelete,
-  restore: runAttachmentRestore
-};
-
-async function runAttachmentCommand(subArgs) {
-  const sub = subArgs[0] && !subArgs[0].startsWith('-') ? subArgs[0] : undefined;
-  if (!sub || subArgs.includes('--help') || subArgs.includes('-h')) {
-    printAttachmentHelp(sub);
-    return undefined;
-  }
-
-  const handler = ATTACHMENT_SUBCOMMANDS[sub];
-  if (!handler) {
-    warn('Unknown attachment subcommand: ' + sub);
-    printAttachmentHelp();
-    process.exit(1);
-  }
-
-  return handler(subArgs.slice(1));
-}
-
-module.exports = {
-  ATTACHMENT_SUBCOMMAND_USAGE,
-  guessContentType,
-  filenameFromContentDisposition,
-  runAttachmentList,
-  runAttachmentAdd,
-  runAttachmentGet,
-  runAttachmentDelete,
-  runAttachmentRestore,
-  runAttachmentCommand
-};
+'use strict';
+
+// `empirical memory attachment <list|add|get|delete|restore>` over the four REST routes in
+// packages/server/src/routes/memories.ts (POST/GET/DELETE /:id/attachments[/:attachmentId] and
+// the restore POST). Attachments shipped REST-only; this is the first non-REST door.
+//
+// Two things here are not style choices:
+//  1. `get` writes BYTES. It never goes through httpJson, which decodes utf8 and would corrupt
+//     every non-text file, and it never prints the body to stdout unless asked (--out -), so a
+//     stray download cannot dump a binary into a terminal or a piped JSON stream.
+//  2. The per-file cap is checked locally BEFORE the upload. The server refuses an oversized
+//     body at ingress, but only after the client has pushed 25MB+ up the wire for nothing.
+
+const fs = require('fs');
+const path = require('path');
+const { log, warn } = require('./ui');
+const { httpJson, httpMultipart, httpDownload, printApiError } = require('./http');
+const { parseOption, parseFlag } = require('./env');
+const { requireAccessToken, resolveApiBaseUrl, buildApiAuthHeaders } = require('./auth');
+const { resolveMemoryByQuery, parseMatchFilters, printMemoryResolveError } = require('./memoryResolve');
+
+// Mirrors MAX_ATTACHMENT_BYTES / MAX_ATTACHMENTS_PER_MEMORY in packages/shared/src/
+// subscriptionPlans.ts. The CLI is published as its own npm package and cannot depend on the
+// workspace, so these are copied; they are used for a friendlier local error only, never to
+// decide anything the server does not re-check.
+const MAX_ATTACHMENT_BYTES = 25 * 1024 * 1024;
+
+// Enough to label the common cases. The server sniffs magic bytes and overrides anything
+// renderable or executable, so a wrong guess here is corrected, never trusted.
+const MIME_BY_EXTENSION = {
+  '.txt': 'text/plain',
+  '.md': 'text/markdown',
+  '.json': 'application/json',
+  '.csv': 'text/csv',
+  '.pdf': 'application/pdf',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.svg': 'image/svg+xml',
+  '.zip': 'application/zip',
+  '.mp3': 'audio/mpeg',
+  '.m4a': 'audio/mp4',
+  '.wav': 'audio/wav',
+  '.mp4': 'video/mp4'
+};
+
+const ATTACHMENT_SUBCOMMAND_USAGE = {
+  list: 'Usage: empirical memory attachment list (--memory-id <id> | --match <query>) [--include-deleted] [--format table] [--pretty]',
+  add: 'Usage: empirical memory attachment add (--memory-id <id> | --match <query>) --file <path> [--author-type user|agent] [--min-score 0.35]',
+  get: 'Usage: empirical memory attachment get (--memory-id <id> | --match <query>) --attachment-id <id> [--out <path>] [--force]\n  --out - writes the bytes to stdout.',
+  delete: 'Usage: empirical memory attachment delete (--memory-id <id> | --match <query>) --attachment-id <id> [--confirm]\n  Soft delete: the file is restorable for 30 days, then purged.',
+  restore: 'Usage: empirical memory attachment restore (--memory-id <id> | --match <query>) --attachment-id <id>'
+};
+
+function printAttachmentHelp(sub) {
+  if (sub && ATTACHMENT_SUBCOMMAND_USAGE[sub]) {
+    log(ATTACHMENT_SUBCOMMAND_USAGE[sub]);
+    return;
+  }
+  log('Files attached to a memory. Up to 20 per memory, 25MB each; a delete is reversible for 30 days.');
+  log('');
+  for (const usage of Object.values(ATTACHMENT_SUBCOMMAND_USAGE)) log(usage);
+  log('');
+  log('Shorthands: `memory attach` = `memory attachment add`, `memory attachments` = `memory attachment list`.');
+}
+
+function guessContentType(filename) {
+  return MIME_BY_EXTENSION[path.extname(String(filename || '')).toLowerCase()] || 'application/octet-stream';
+}
+
+function fail(code, message, extra = {}) {
+  warn(JSON.stringify({ error: true, code, message, ...extra }));
+  process.exit(1);
+}
+
+// Every subcommand takes the same target: an explicit id, or a --match query resolved the same
+// way `memory note` and `memory delete` resolve theirs.
+async function resolveTargetMemoryId(args, accessToken, baseUrl, usage) {
+  const memoryId = parseOption(args, '--memory-id', '');
+  if (memoryId) return memoryId;
+
+  const match = parseOption(args, '--match', '');
+  if (!match) {
+    warn(usage);
+    process.exit(1);
+  }
+
+  const minScore = Number(parseOption(args, '--min-score', '0.35'));
+  const result = await resolveMemoryByQuery(match, minScore, accessToken, baseUrl, parseMatchFilters(args));
+  if (!result.found) {
+    printMemoryResolveError(result);
+    process.exit(1);
+  }
+  return result.memory.id;
+}
+
+function attachmentsUrl(baseUrl, memoryId, suffix = '') {
+  return new URL(`/api/v1/memories/${encodeURIComponent(memoryId)}/attachments${suffix}`, baseUrl).toString();
+}
+
+function renderAttachmentsTable(rows) {
+  const header = ['ID', 'FILENAME', 'BYTES', 'TYPE', 'STATE'];
+  const body = rows.map((row) => [
+    String(row.id || ''),
+    String(row.filename || ''),
+    String(row.bytes != null ? row.bytes : ''),
+    String(row.mimeType || ''),
+    row.deletedAt ? `deleted, purges ${String(row.purgeAfter || '').slice(0, 10)}` : 'live'
+  ]);
+  const widths = header.map((_h, i) => Math.max(header[i].length, ...body.map((r) => r[i].length), 1));
+  const line = (cells) => cells.map((c, i) => c.padEnd(widths[i])).join('  ').trimEnd();
+  log(line(header));
+  log(widths.map((w) => '-'.repeat(w)).join('  '));
+  for (const row of body) log(line(row));
+}
+
+async function runAttachmentList(args) {
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const memoryId = await resolveTargetMemoryId(args, accessToken, baseUrl, ATTACHMENT_SUBCOMMAND_USAGE.list);
+
+  const url = attachmentsUrl(baseUrl, memoryId) + (parseFlag(args, '--include-deleted') ? '?includeDeleted=true' : '');
+
+  let response;
+  try {
+    response = await httpJson(url, 'GET', undefined, buildApiAuthHeaders(accessToken));
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+
+  // This route answers with `attachments` at the TOP level, not under `data` like most of the
+  // memory routes; reading response.data here would silently print nothing.
+  const attachments = Array.isArray(response && response.attachments) ? response.attachments : [];
+
+  if (parseOption(args, '--format', '') === 'table') {
+    if (!attachments.length) {
+      log('No attachments on this memory.');
+      return;
+    }
+    renderAttachmentsTable(attachments);
+    return;
+  }
+
+  const payload = {
+    memoryId: response.memoryId || memoryId,
+    attachmentsCount: response.attachmentsCount != null ? response.attachmentsCount : attachments.length,
+    attachments
+  };
+  log(parseFlag(args, '--pretty') ? JSON.stringify(payload, null, 2) : JSON.stringify(payload));
+}
+
+async function runAttachmentAdd(args) {
+  const filePath = parseOption(args, '--file', '');
+  if (!filePath) {
+    warn(ATTACHMENT_SUBCOMMAND_USAGE.add);
+    process.exit(1);
+  }
+
+  const resolved = path.resolve(filePath);
+  let stat;
+  try {
+    stat = fs.statSync(resolved);
+  } catch (_error) {
+    fail('file_not_found', `No such file: ${resolved}`);
+  }
+  if (!stat.isFile()) {
+    fail('not_a_file', `Not a file: ${resolved}`);
+  }
+  if (stat.size === 0) {
+    fail('empty_file', `File is empty: ${resolved}`);
+  }
+  // Local pre-check, see note 2 at the top of this file.
+  if (stat.size > MAX_ATTACHMENT_BYTES) {
+    fail('attachment_too_large', `File is ${stat.size} bytes; the per-file limit is ${MAX_ATTACHMENT_BYTES} bytes (25MB).`, {
+      bytes: stat.size,
+      maxBytes: MAX_ATTACHMENT_BYTES
+    });
+  }
+
+  const authorType = parseOption(args, '--author-type', '');
+  if (authorType && !['user', 'agent', 'system'].includes(authorType)) {
+    fail('invalid_author_type', `Invalid --author-type "${authorType}". Valid: user, agent, system`);
+  }
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const memoryId = await resolveTargetMemoryId(args, accessToken, baseUrl, ATTACHMENT_SUBCOMMAND_USAGE.add);
+
+  const filename = path.basename(resolved);
+  let response;
+  try {
+    response = await httpMultipart(
+      attachmentsUrl(baseUrl, memoryId),
+      'POST',
+      {
+        // Same authorship contract as `memory record`: `source` is observable truth, authorType
+        // is only declared when the caller says so, never guessed.
+        fields: { source: 'cli', ...(authorType ? { authorType } : {}) },
+        file: { field: 'file', filename, contentType: guessContentType(filename), buffer: fs.readFileSync(resolved) }
+      },
+      buildApiAuthHeaders(accessToken)
+    );
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+
+  const data = (response && response.data) ? response.data : response;
+  log(JSON.stringify({ attached: true, ...data, ...(response.warnings ? { warnings: response.warnings } : {}) }));
+}
+
+// Content-Disposition from the download route is always the RFC 5987 form
+// (filename*=UTF-8''<pct-encoded>), so that is what is parsed; the plain filename="..." form is
+// accepted too in case a proxy rewrites it.
+function filenameFromContentDisposition(header) {
+  const value = String(header || '');
+  const extended = value.match(/filename\*=UTF-8''([^;]+)/i);
+  if (extended) {
+    try {
+      return decodeURIComponent(extended[1]);
+    } catch (_error) {
+      // Fall through to the plain form below.
+    }
+  }
+  const plain = value.match(/filename="([^"]+)"/i);
+  return plain ? plain[1] : '';
+}
+
+async function runAttachmentGet(args) {
+  const attachmentId = parseOption(args, '--attachment-id', '');
+  if (!attachmentId) {
+    warn(ATTACHMENT_SUBCOMMAND_USAGE.get);
+    process.exit(1);
+  }
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const memoryId = await resolveTargetMemoryId(args, accessToken, baseUrl, ATTACHMENT_SUBCOMMAND_USAGE.get);
+
+  let result;
+  try {
+    result = await httpDownload(
+      attachmentsUrl(baseUrl, memoryId, `/${encodeURIComponent(attachmentId)}`),
+      buildApiAuthHeaders(accessToken)
+    );
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+
+  const out = parseOption(args, '--out', '');
+  if (out === '-') {
+    process.stdout.write(result.buffer);
+    return;
+  }
+
+  // The server's filename is only ever used as a BASENAME. It is attacker-supplied as far as
+  // this process is concerned, and joining a path that carries .. or a drive letter straight
+  // onto cwd would let a download write outside the directory the user chose.
+  const suggested = path.basename(filenameFromContentDisposition(result.headers['content-disposition']) || '') || 'attachment';
+  let target = out ? path.resolve(out) : path.resolve(process.cwd(), suggested);
+  if (out) {
+    try {
+      if (fs.statSync(target).isDirectory()) target = path.join(target, suggested);
+    } catch (_error) {
+      // --out names a file that does not exist yet, which is the normal case.
+    }
+  }
+
+  if (fs.existsSync(target) && !parseFlag(args, '--force')) {
+    fail('file_exists', `${target} already exists. Pass --force to overwrite, or --out <path> to write elsewhere.`, { path: target });
+  }
+
+  try {
+    fs.writeFileSync(target, result.buffer);
+  } catch (error) {
+    fail('write_failed', `Could not write ${target}: ${error.message}`);
+  }
+
+  log(JSON.stringify({ downloaded: true, memoryId, attachmentId, path: target, bytes: result.buffer.length }));
+}
+
+async function runAttachmentDelete(args) {
+  const attachmentId = parseOption(args, '--attachment-id', '');
+  if (!attachmentId) {
+    warn(ATTACHMENT_SUBCOMMAND_USAGE.delete);
+    process.exit(1);
+  }
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const memoryId = await resolveTargetMemoryId(args, accessToken, baseUrl, ATTACHMENT_SUBCOMMAND_USAGE.delete);
+
+  // Same gate as `memory delete`: without --confirm this only reports what it would do.
+  if (!parseFlag(args, '--confirm')) {
+    log(JSON.stringify({ dryRun: true, wouldDelete: true, memoryId, attachmentId, note: 'Re-run with --confirm. The file stays restorable for 30 days.' }));
+    return;
+  }
+
+  let response;
+  try {
+    response = await httpJson(
+      attachmentsUrl(baseUrl, memoryId, `/${encodeURIComponent(attachmentId)}`),
+      'DELETE',
+      null,
+      buildApiAuthHeaders(accessToken)
+    );
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+
+  const data = (response && response.data) ? response.data : response;
+  log(JSON.stringify({ deleted: true, ...data }));
+}
+
+async function runAttachmentRestore(args) {
+  const attachmentId = parseOption(args, '--attachment-id', '');
+  if (!attachmentId) {
+    warn(ATTACHMENT_SUBCOMMAND_USAGE.restore);
+    process.exit(1);
+  }
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const memoryId = await resolveTargetMemoryId(args, accessToken, baseUrl, ATTACHMENT_SUBCOMMAND_USAGE.restore);
+
+  let response;
+  try {
+    response = await httpJson(
+      attachmentsUrl(baseUrl, memoryId, `/${encodeURIComponent(attachmentId)}/restore`),
+      'POST',
+      {},
+      buildApiAuthHeaders(accessToken)
+    );
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+
+  const data = (response && response.data) ? response.data : response;
+  log(JSON.stringify({ restored: true, ...data }));
+}
+
+const ATTACHMENT_SUBCOMMANDS = {
+  list: runAttachmentList,
+  ls: runAttachmentList,
+  add: runAttachmentAdd,
+  upload: runAttachmentAdd,
+  get: runAttachmentGet,
+  download: runAttachmentGet,
+  delete: runAttachmentDelete,
+  rm: runAttachmentDelete,
+  remove: runAttachmentDelete,
+  restore: runAttachmentRestore
+};
+
+async function runAttachmentCommand(subArgs) {
+  const sub = subArgs[0] && !subArgs[0].startsWith('-') ? subArgs[0] : undefined;
+  if (!sub || subArgs.includes('--help') || subArgs.includes('-h')) {
+    printAttachmentHelp(sub);
+    return undefined;
+  }
+
+  const handler = ATTACHMENT_SUBCOMMANDS[sub];
+  if (!handler) {
+    warn('Unknown attachment subcommand: ' + sub);
+    printAttachmentHelp();
+    process.exit(1);
+  }
+
+  return handler(subArgs.slice(1));
+}
+
+module.exports = {
+  ATTACHMENT_SUBCOMMAND_USAGE,
+  guessContentType,
+  filenameFromContentDisposition,
+  runAttachmentList,
+  runAttachmentAdd,
+  runAttachmentGet,
+  runAttachmentDelete,
+  runAttachmentRestore,
+  runAttachmentCommand
+};