@bergetai/odoo-cli 0.7.3 → 0.8.1

package/README.md

@@ -40,7 +40,9 @@ odoo project tasks list --project "Content Pipeline" --open
 odoo project tasks show 850
 odoo documents tree --count
 odoo documents records list --folder "Product Backlog" --limit 20
+odoo documents records list --folder "Projects > Product Backlog"  # nested path
 odoo documents records show 25
+odoo documents records download 25 --out ./spec.pdf
 
 # Mutations (support --dry-run)
 odoo crm leads create --name "New lead" --email info@example.com
@@ -78,7 +80,7 @@ Note: `odoo --version` prints the CLI's own version; `odoo version` queries the
 - Read-only Helpdesk surface (`helpdesk tickets list/show`) — `--open`/`--closed` via stage `fold`, strict team-scoped stage resolution, module-not-installed error (exit 4)
 - Read-only Project surface (`project list/show`) — `--user` (project manager) and `--tag` filters, archived projects excluded by default, module-not-installed error (exit 4)
 - Read-only Project task surface (`project tasks list/show`) — `--project` (required on list, resolved by name or id), project-scoped `--stage`, `--assignee` (many2many `user_ids`), `--tag`, `--priority` (0/Low, 1/High), `--open`/`--closed` via the task's `is_closed` flag, `--domain`/`--filter`, table/JSON output with `search_count` envelope, module-not-installed error (exit 4)
-- Documents surface (`documents`) — `tree` (hierarchical folder listing with `--count`/`--depth`/`--folder`), `records list/show` (folders excluded by default, `--type folder|binary|url|all`, `--folder`/`--owner`/`--partner`/`--tag`), `folders list`, `records create` (folder via `--folder-type folder`, link via `--link <url>`), `records update` (move via `--folder`), `records delete`, and `upload` (local file → base64 `datas`, MIME guessed from extension, `--dry-run` previews without sending bytes). Folders are `documents.document` rows with `type='folder'`; the hierarchy is `folder_id`. Module-not-installed error (exit 4)
+- Documents surface (`documents`) — `tree` (hierarchical folder listing with `--count`/`--depth`/`--folder`), `records list/show` (folders excluded by default, `--type folder|binary|url|all`, `--folder`/`--owner`/`--partner`/`--tag`), `folders list`, `records create` (folder via `--folder-type folder`, link via `--link <url>`), `records update` (move via `--folder`), `records delete`, `upload` (local file → base64 `datas`, MIME guessed from extension, `--dry-run` previews without sending bytes), and `records download <id>` (binary document → local file, `--out <path>`/`--force`, `--out -` streams to stdout). Everywhere a `--folder` is accepted, folders resolve by name, numeric id, or nested `'Parent > Child'` path (segments resolved within their parent, which disambiguates repeated folder names). Folders are `documents.document` rows with `type='folder'`; the hierarchy is `folder_id`. Module-not-installed error (exit 4)
 - Writes (`create`, `update`, `delete`) — single-call atomic batch `write`, client-side no-op diffing, delete convergence with `skipped` ids, post-failure "record may have been created" hint on `create`
 - `--dry-run` for all mutations — full validation, resolution, and before/after diffs without mutating
 - Internal notes (`add-note`) — creates internal Log Notes only (subtype_id=2, message_type=comment), **NEVER sends email to customer**, by design prevents accidental customer communication. Optional `--author <email|name|id>` attributes the note to the partner who actually sent the logged message (resolved via `res.partner`; ambiguous matches list candidates and never guess)

package/dist/cli.js

@@ -7,7 +7,7 @@ import { ticketsCreateCommand, ticketsDeleteCommand, ticketsListCommand, tickets
 import { addNoteCommand, deleteMessageCommand, listMessagesCommand, updateMessageCommand, } from "./commands/notes.js";
 import { activitiesListCommand, activityDoneCommand, activityUpdateCommand, scheduleCommand, } from "./commands/activities.js";
 import { createTaskCommand, projectListCommand, projectShowCommand, tasksListCommand, tasksShowCommand, } from "./commands/project.js";
-import { documentsDocuments, documentsListCommand, foldersListCommand, documentsShowCommand, documentsCreateCommand, documentsUpdateCommand, documentsDeleteCommand, treeCommand, uploadCommand, } from "./commands/documents.js";
+import { documentsDocuments, documentsListCommand, foldersListCommand, documentsShowCommand, documentsCreateCommand, documentsUpdateCommand, documentsDeleteCommand, treeCommand, uploadCommand, downloadCommand, } from "./commands/documents.js";
 import { versionCommand } from "./commands/version.js";
 import { partnersCreateCommand, partnersDeleteCommand, partnersListCommand, partnersShowCommand, partnersUpdateCommand, resPartner, } from "./commands/partners.js";
 import { CliError } from "./errors.js";
@@ -576,7 +576,7 @@ Examples:
         .command("list")
         .description("search and list documents (folders excluded by default)")
         .option("--type <type>", "record type: document (default), folder, or all")
-        .option("--folder <name|id>", "only records directly in this folder (resolved by name)")
+        .option("--folder <name|id|path>", "only records directly in this folder (name, id, or 'Parent > Child' path)")
         .option("--owner <name|id>", "filter by owner (login, email, or name)")
         .option("--partner <name|id>", "filter by linked contact")
         .option("--tag <name|id>", "filter by tag; repeatable, AND-ed", collect, [])
@@ -598,6 +598,15 @@ Examples:
         .action(async (id, opts) => {
         await run((g) => documentsShowCommand(id, opts, g), program);
     });
+    records
+        .command("download")
+        .description("download a document's file content to disk")
+        .argument("<id>", "record id")
+        .option("--out <path>", "output path (default: document name in cwd; '-' for stdout)")
+        .option("--force", "overwrite an existing output file")
+        .action(async (id, opts) => {
+        await run((g) => downloadCommand(id, opts, g), program);
+    });
     addMutationFlags(records
         .command("create")
         .description("create a folder or URL link (preview with --dry-run; upload files via 'documents upload')"), documentsDocuments).action(async (opts) => {
@@ -631,7 +640,7 @@ Examples:
     documents
         .command("tree")
         .description("print the folder tree with document counts")
-        .option("--folder <name|id>", "start from this folder (default: roots)")
+        .option("--folder <name|id|path>", "start from this folder (default: roots; name, id, or 'Parent > Child' path)")
         .option("--depth <n>", "max depth", "10")
         .option("--count", "show the number of documents per folder")
         .action(async (opts) => {
@@ -642,7 +651,7 @@ Examples:
         .description("upload a local file as a document (preview with --dry-run)")
         .requiredOption("--file <path>", "local file path ('-' for stdin)")
         .option("--name <name>", "document name (default: file basename)")
-        .option("--folder <name|id>", "target folder (resolved by name)")
+        .option("--folder <name|id|path>", "target folder (name, id, or 'Parent > Child' path)")
         .option("--owner <name|id>", "owner (login, email, or name)")
         .option("--partner <name|id>", "linked contact")
         .option("--tag <name|id>", "tag; repeatable, AND-ed", collect, [])

package/dist/commands/documents.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
-import { readFile, stat } from "node:fs/promises";
+import { readFile, stat, writeFile } from "node:fs/promises";
 import { basename, extname, resolve } from "node:path";
-import { usageError } from "../errors.js";
+import { notFoundError, usageError } from "../errors.js";
 import { ModelFields, resolveReference } from "../model.js";
 import { createCommand, deleteCommand, updateCommand, } from "../mutation.js";
 import { colorEnabled, printJson } from "../output.js";
@@ -19,10 +19,10 @@ const documentsMutation = {
             requiredOnCreate: true,
         },
         {
-            flags: "--folder <name|id>",
+            flags: "--folder <name|id|path>",
             option: "folder",
             field: "folder_id",
-            help: "Parent folder",
+            help: "Parent folder (name, id, or 'Parent > Child' path)",
             reference: { model: "documents.document", label: "folder" },
         },
         {
@@ -391,12 +391,88 @@ export async function uploadCommand(opts, globals) {
     const line = `Uploaded documents.document ${id} (${name})`;
     process.stdout.write((color ? `\x1b[32m${line}\x1b[0m` : line) + "\n");
 }
-/** Resolve a folder by name or id (must be type=folder). */
+export async function downloadCommand(idArg, opts, globals) {
+    const client = await authenticatedClient(globals);
+    await ModelFields.load(client, "documents.document"); // module-installed check
+    if (!/^\d+$/.test(idArg)) {
+        throw usageError(`invalid document id ${JSON.stringify(idArg)}`, "expected a numeric id (see 'documents records list')");
+    }
+    const id = Number(idArg);
+    const rows = (await client.executeKw("documents.document", "read", [
+        [id],
+        ["name", "type", "datas", "mimetype"],
+    ]));
+    if (rows.length === 0) {
+        throw notFoundError("reference_not_found", `no document with id ${id}`);
+    }
+    const rec = rows[0];
+    if (rec.type === "folder") {
+        throw usageError(`document ${id} "${rec.name}" is a folder`, "download expects a binary document (folders excluded by default in 'records list')");
+    }
+    if (rec.type !== "binary" || rec.datas === false || rec.datas === "") {
+        throw usageError(`document ${id} "${rec.name}" has no file content (type: ${rec.type})`);
+    }
+    const buffer = Buffer.from(rec.datas, "base64");
+    // '--out -' streams raw bytes to stdout (for piping).
+    if (opts.out === "-") {
+        process.stdout.write(buffer);
+        return;
+    }
+    const outPath = resolve(opts.out ?? rec.name);
+    try {
+        await stat(outPath);
+        if (!opts.force) {
+            throw usageError(`file already exists: ${outPath}`, "pass --force to overwrite");
+        }
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+    await writeFile(outPath, buffer);
+    if (globals.json) {
+        printJson({
+            model: "documents.document",
+            action: "download",
+            id,
+            name: rec.name,
+            path: outPath,
+            file_size: buffer.length,
+            mimetype: rec.mimetype,
+        });
+        return;
+    }
+    const color = colorEnabled(false) && process.stdout.isTTY === true;
+    const line = `Downloaded documents.document ${id} → ${outPath} (${buffer.length} bytes)`;
+    process.stdout.write((color ? `\x1b[32m${line}\x1b[0m` : line) + "\n");
+}
+/**
+ * Resolve a folder by name, id, or "Parent > Child > ..." path
+ * (must be type=folder). Path segments are resolved within their parent,
+ * which disambiguates repeated folder names (e.g. per-customer subfolders).
+ */
 async function resolveFolderId(client, input) {
-    const resolved = await resolveReference(client, "documents.document", input, {
-        label: "folder",
-        domain: FOLDER_DOMAIN,
-    });
-    return resolved.id;
+    const segments = input
+        .split(">")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    if (segments.length <= 1) {
+        const resolved = await resolveReference(client, "documents.document", input, {
+            label: "folder",
+            domain: FOLDER_DOMAIN,
+        });
+        return resolved.id;
+    }
+    let parentId = false;
+    let id = 0;
+    for (const segment of segments) {
+        const resolved = await resolveReference(client, "documents.document", segment, {
+            label: parentId === false ? "root folder" : `folder under ${parentId}`,
+            domain: [...FOLDER_DOMAIN, ["folder_id", "=", parentId]],
+        });
+        id = resolved.id;
+        parentId = id;
+    }
+    return id;
 }
 export { formatTable, humanCell };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bergetai/odoo-cli",
-  "version": "0.7.3",
+  "version": "0.8.1",
   "description": "Agent-first CLI for the Odoo External API",
   "publishConfig": {
     "access": "public"