zinkee 0.1.23 → 0.1.25

package/src/commands/teamspace.ts

@@ -385,7 +385,7 @@ export function registerTeamspaceCommands(
   folders
     .command("list")
     .description("List teamspace folders")
-    .option("--include-resources", "include nested resources")
+    .option("--include-resources", "include the published resources inside each folder")
     .action(async function action(this: Command, commandOptions: FolderListCommandOptions) {
       const { api, json } = createTeamspaceApi(this, filePath);
       const data = await api.listFolders(Boolean(commandOptions.includeResources));
@@ -402,7 +402,7 @@ export function registerTeamspaceCommands(
     .command("get")
     .description("Get a teamspace folder by exact name or UUID")
     .argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector)
-    .option("--include-resources", "include nested resources")
+    .option("--include-resources", "include the published resources inside each folder")
     .action(async function action(
       this: Command,
       folder: NormalizedUuidOrSlug,
@@ -425,9 +425,9 @@ export function registerTeamspaceCommands(
     .command("create")
     .description("Create a teamspace folder")
     .requiredOption("--name <name>", "folder name")
-    .option("--order <n>", "folder order", parseNonNegativeInteger)
-    .option("--props <json>", "folder properties payload")
-    .option("--props-file <path>", "path to a folder properties JSON payload")
+    .option("--order <n>", "display order (lower values appear first)", parseNonNegativeInteger)
+    .option("--props <json>", "additionalProperties JSON: free-form client metadata, e.g. {\"icon\":\"folder-users\",\"color\":\"gold\"}")
+    .option("--props-file <path>", "path to a file with the additionalProperties JSON")
     .action(async function action(
       this: Command,
       commandOptions: FolderCreateCommandOptions,
@@ -450,9 +450,9 @@ export function registerTeamspaceCommands(
     .description("Update a teamspace folder")
     .argument("<folder>", "folder UUID or exact name", parseUuidOrSlugSelector)
     .option("--name <name>", "folder name")
-    .option("--order <n>", "folder order", parseNonNegativeInteger)
-    .option("--props <json>", "folder properties payload")
-    .option("--props-file <path>", "path to a folder properties JSON payload")
+    .option("--order <n>", "display order (lower values appear first)", parseNonNegativeInteger)
+    .option("--props <json>", "additionalProperties JSON: free-form client metadata, e.g. {\"icon\":\"folder-users\",\"color\":\"gold\"}")
+    .option("--props-file <path>", "path to a file with the additionalProperties JSON")
     .action(async function action(
       this: Command,
       folder: NormalizedUuidOrSlug,
@@ -495,9 +495,15 @@ export function registerTeamspaceCommands(
 
   resources
     .command("publish")
-    .description("Publish a resource to a teamspace folder")
-    .argument("<resource>", "resource UUID or exact name", parseUuidOrSlugSelector)
-    .requiredOption("--to <folder>", "target folder", parseUuidOrSlugSelector)
+    .description(
+      "Publish a resource to a teamspace folder. Publishing an already-published resource moves it to the new folder.",
+    )
+    .argument("<resource>", "schema UUID, schema slug, or display UUID", parseUuidOrSlugSelector)
+    .requiredOption(
+      "--to <folder>",
+      "target folder UUID or exact name (root folder UUID is 00000000-0000-0000-0000-000000000000)",
+      parseUuidOrSlugSelector,
+    )
     .action(async function action(
       this: Command,
       resource: NormalizedUuidOrSlug,
@@ -522,8 +528,8 @@ export function registerTeamspaceCommands(
 
   resources
     .command("unpublish")
-    .description("Unpublish a resource from teamspace")
-    .argument("<resource>", "resource UUID or exact name", parseUuidOrSlugSelector)
+    .description("Unpublish a resource from teamspace (removes it from its shared folder)")
+    .argument("<resource>", "schema UUID, schema slug, or display UUID", parseUuidOrSlugSelector)
     .action(async function action(this: Command, resource: NormalizedUuidOrSlug) {
       const { api, json, readOnly } = createTeamspaceApi(this, filePath);
       ensureWritable("teamspace resources unpublish", readOnly, "write");

package/src/program.ts

@@ -6,6 +6,7 @@ import { registerConfigCommands } from "./commands/config.js";
 import { registerAutomationsCommands } from "./commands/automations.js";
 import { registerCommentsCommands } from "./commands/comments.js";
 import { registerDisplaysCommands } from "./commands/displays.js";
+import { registerDocumentTemplatesCommands } from "./commands/document-templates.js";
 import { registerFilesCommands } from "./commands/files.js";
 import { registerLogsCommands } from "./commands/logs.js";
 import { registerNavigationCommands } from "./commands/navigation.js";
@@ -48,6 +49,7 @@ export function buildProgram(options: BuildProgramOptions = {}): Command {
   registerAutomationsCommands(program, options);
   registerConfigCommands(program, options);
   registerDisplaysCommands(program, options);
+  registerDocumentTemplatesCommands(program, options);
   registerFilesCommands(program, options);
   registerNavigationCommands(program, options);
   registerSchemasCommands(program, options);

package/src/utils/examples.test.ts

@@ -211,14 +211,23 @@ describe("getCommandExamples", () => {
     expect(rawPayloads.some((raw) => raw.includes('"dynamicOption": "thisMonth"'))).toBe(true);
   });
 
-  it("covers SCHEMA, WORKFLOW and DISPLAY variants in navigation resources move", () => {
+  it("documents navigation resources move as schema-only with no resourceType", () => {
     const examples = getCommandExamples("navigation resources move");
     const rawPayloads = examples.map((example) => example.raw ?? "");
 
-    expect(examples.length).toBeGreaterThanOrEqual(5);
-    for (const resourceType of ["SCHEMA", "WORKFLOW", "DISPLAY", "SCHEDULE"]) {
-      expect(rawPayloads.some((raw) => raw.includes(`"resourceType": "${resourceType}"`))).toBe(true);
+    expect(examples.length).toBeGreaterThanOrEqual(2);
+    // Navigation only moves schemas now, so the payload no longer carries a
+    // resourceType and the example commands must not pass --type.
+    for (const raw of rawPayloads) {
+      expect(raw).not.toContain("resourceType");
     }
+    for (const example of examples) {
+      expect(example.command).not.toContain("--type");
+    }
+    // Covers moving into a folder and back to the root folder.
+    expect(
+      rawPayloads.some((raw) => raw.includes('"targetFolderId": "00000000-0000-0000-0000-000000000000"')),
+    ).toBe(true);
   });
 
   it("covers slug and UUID variants in teamspace resources publish", () => {

package/src/utils/examples.ts

@@ -818,12 +818,12 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
   ]),
   "navigation resources move": buildCommandExamples([
     {
-      description: "Move a schema into a navigation folder.",
+      description:
+        "Move a schema into a navigation folder. Only schemas can be moved; the navigation menu holds databases.",
       command:
-        'zinkee --json navigation resources move 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --type SCHEMA --to Sales',
+        'zinkee --json navigation resources move 2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e --to Sales',
       raw: `{
   "resourceId": "2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e",
-  "resourceType": "SCHEMA",
   "targetFolderId": "84a0fca4-37ef-4c83-a8ed-9ef67ad9324a"
 }`,
       response: `{
@@ -832,43 +832,12 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
 }`,
     },
     {
-      description: "Move a workflow.",
-      command:
-        'zinkee --json navigation resources move 3f8a2c1b-9d4e-4a5b-8c6d-7e8f90123456 --type WORKFLOW --to Operations',
-      raw: `{
-  "resourceId": "3f8a2c1b-9d4e-4a5b-8c6d-7e8f90123456",
-  "resourceType": "WORKFLOW",
-  "targetFolderId": "b8c9d0e1-f2a3-4b5c-6d7e-8f9012345678"
-}`,
-    },
-    {
-      description: "Move a display.",
+      description: "Move a schema back to the root folder (root is always UUID 00000000-0000-0000-0000-000000000000).",
       command:
-        'zinkee --json navigation resources move 0f6f062f-1478-4df2-96a1-c495d037d260 --type DISPLAY --to Operations',
-      raw: `{
-  "resourceId": "0f6f062f-1478-4df2-96a1-c495d037d260",
-  "resourceType": "DISPLAY",
-  "targetFolderId": "b8c9d0e1-f2a3-4b5c-6d7e-8f9012345678"
-}`,
-    },
-    {
-      description: "Move a resource back to the root folder (root is always UUID 00000000-0000-0000-0000-000000000000).",
-      command:
-        'zinkee --json navigation resources move 5223cbc8-8c6c-4694-93bc-dd176364df9b --type SCHEMA --to 00000000-0000-0000-0000-000000000000',
+        'zinkee --json navigation resources move 5223cbc8-8c6c-4694-93bc-dd176364df9b --to 00000000-0000-0000-0000-000000000000',
       raw: `{
   "resourceId": "5223cbc8-8c6c-4694-93bc-dd176364df9b",
-  "resourceType": "SCHEMA",
   "targetFolderId": "00000000-0000-0000-0000-000000000000"
-}`,
-    },
-    {
-      description: "Move a schedule resource.",
-      command:
-        'zinkee --json navigation resources move a1b2c3d4-e5f6-7890-1234-567890abcdef --type SCHEDULE --to Operations',
-      raw: `{
-  "resourceId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
-  "resourceType": "SCHEDULE",
-  "targetFolderId": "b8c9d0e1-f2a3-4b5c-6d7e-8f9012345678"
 }`,
     },
   ]),
@@ -2421,7 +2390,7 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
     "resources": [
       {
         "id": "2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e",
-        "name": "Contacts",
+        "name": "Customer records",
         "type": "SCHEMA",
         "isInSpace": false,
         "additionalProperties": {}
@@ -2445,19 +2414,10 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
     "resources": [
       {
         "id": "3f8a2c1b-9d4e-4a5b-8c6d-7e8f90123456",
-        "name": "Quote approval",
-        "type": "WORKFLOW",
+        "name": "Shipments",
+        "type": "SCHEMA",
         "isInSpace": false,
         "additionalProperties": {}
-      },
-      {
-        "id": "0f6f062f-1478-4df2-96a1-c495d037d260",
-        "name": "Executive Revenue",
-        "type": "DISPLAY",
-        "isInSpace": true,
-        "additionalProperties": {
-          "pinned": true
-        }
       }
     ],
     "additionalProperties": {
@@ -2504,8 +2464,13 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
     "name": "Shared Dashboards",
     "order": 1,
     "isRoot": false,
-    "resourceCount": 1,
+    "resourceCount": 2,
     "resources": [
+      {
+        "id": "2eb8bdcf-6d9c-4fbb-9018-7fa8180f4c5e",
+        "name": "Customer records",
+        "type": "SCHEMA"
+      },
       {
         "id": "0f6f062f-1478-4df2-96a1-c495d037d260",
         "name": "Executive Revenue",
@@ -2727,6 +2692,85 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
       command: "zinkee --json displays delete 0f6f062f-1478-4df2-96a1-c495d037d260",
     },
   ]),
+  "displays folders list": buildCommandExamples([
+    {
+      description: "List flat display folders (non-root folders plus the root bucket).",
+      command: "zinkee --json displays folders list",
+      response: `[
+  {
+    "id": "e7a1c3d2-5f4b-4a6c-9d8e-1f2a3b4c5d6e",
+    "name": "Executive Dashboards",
+    "isRoot": false,
+    "displayCount": 2
+  },
+  {
+    "id": "8b22282b-3db3-4dd7-87f7-b29365dcf3f6",
+    "name": null,
+    "isRoot": true,
+    "displayCount": 4
+  }
+]`,
+    },
+  ]),
+  "displays folders create": buildCommandExamples([
+    {
+      description: "Create one flat display folder.",
+      command: 'zinkee --json displays folders create --name "Executive Dashboards"',
+      raw: `{
+  "name": "Executive Dashboards"
+}`,
+      response: `{
+  "id": "e7a1c3d2-5f4b-4a6c-9d8e-1f2a3b4c5d6e",
+  "name": "Executive Dashboards",
+  "isRoot": false,
+  "displayCount": 0
+}`,
+    },
+  ]),
+  "displays folders update": buildCommandExamples([
+    {
+      description: "Rename a display folder. The folder argument accepts a UUID or an exact name.",
+      command:
+        'zinkee --json displays folders update "Executive Dashboards" --name "Executive Dashboards (2026)"',
+      raw: `{
+  "name": "Executive Dashboards (2026)"
+}`,
+      response: `{
+  "id": "e7a1c3d2-5f4b-4a6c-9d8e-1f2a3b4c5d6e",
+  "name": "Executive Dashboards (2026)",
+  "isRoot": false,
+  "displayCount": 2
+}`,
+    },
+  ]),
+  "displays folders delete": buildCommandExamples([
+    {
+      description: "Delete a non-root display folder. Its displays move back to the root folder.",
+      command: 'zinkee --json displays folders delete "Executive Dashboards"',
+      response: `{
+  "id": "e7a1c3d2-5f4b-4a6c-9d8e-1f2a3b4c5d6e",
+  "name": "Executive Dashboards",
+  "isRoot": false,
+  "displayCount": 2
+}`,
+    },
+  ]),
+  "displays folders move": buildCommandExamples([
+    {
+      description: "Move one display into a target folder by exact folder name.",
+      command:
+        'zinkee --json displays folders move 0f6f062f-1478-4df2-96a1-c495d037d260 --to "Executive Dashboards"',
+      raw: `{
+  "displayId": "0f6f062f-1478-4df2-96a1-c495d037d260",
+  "targetFolderId": "e7a1c3d2-5f4b-4a6c-9d8e-1f2a3b4c5d6e"
+}`,
+      response: `{
+  "id": "e7a1c3d2-5f4b-4a6c-9d8e-1f2a3b4c5d6e",
+  "name": "Executive Dashboards",
+  "isRoot": false
+}`,
+    },
+  ]),
   "displays layout get": buildCommandExamples([
     {
       description: "Get the layout block of a display (template + tabs/freeformLayouts/slots).",
@@ -3797,7 +3841,8 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
       description: "Move one automation into a target folder by exact folder name.",
       command: 'zinkee --json automations folders move automation-1 --to "Codex Frontend Demo"',
       raw: `{
-  "automationId": "automation-1"
+  "automationId": "automation-1",
+  "targetFolderId": "cdfc14e3-3169-4ffb-8d9b-b11858a9240f"
 }`,
       response: `{
   "id": "cdfc14e3-3169-4ffb-8d9b-b11858a9240f",
@@ -3806,6 +3851,191 @@ const specificExamples: Record<string, readonly CommandExample[]> = {
 }`,
     },
   ]),
+  "document-templates list": buildCommandExamples([
+    {
+      description:
+        "List every document template in the workspace. Each asset's link is a relative path to the asset download endpoint, ready to call without composition.",
+      command: "zinkee --json document-templates list",
+      response: `[
+  {
+    "id": "7c4a8d3f-1b2e-4a5c-9d6e-1f2a3b4c5d6e",
+    "name": "Quarterly report",
+    "assets": [
+      {
+        "id": "9e8d7c6b-5a4f-3e2d-1c0b-9a8b7c6d5e4f",
+        "name": "Requirements.docx",
+        "link": "/api/v2/document-templates/7c4a8d3f-1b2e-4a5c-9d6e-1f2a3b4c5d6e/assets/9e8d7c6b-5a4f-3e2d-1c0b-9a8b7c6d5e4f/download"
+      }
+    ],
+    "createdAt": "2026-01-15T10:00:00Z",
+    "updatedAt": "2026-01-20T14:30:00Z",
+    "createdBy": "creator@example.com",
+    "updatedBy": "updater@example.com"
+  }
+]`,
+    },
+  ]),
+  "document-templates get": buildCommandExamples([
+    {
+      description:
+        "Look up one template by UUID. The CLI filters the list endpoint locally (the backend does not expose a get-one route).",
+      command:
+        "zinkee --json document-templates get 7c4a8d3f-1b2e-4a5c-9d6e-1f2a3b4c5d6e",
+      response: `{
+  "id": "7c4a8d3f-1b2e-4a5c-9d6e-1f2a3b4c5d6e",
+  "name": "Quarterly report",
+  "assets": [
+    {
+      "id": "9e8d7c6b-5a4f-3e2d-1c0b-9a8b7c6d5e4f",
+      "name": "Requirements.docx",
+      "link": "/api/v2/document-templates/7c4a8d3f-1b2e-4a5c-9d6e-1f2a3b4c5d6e/assets/9e8d7c6b-5a4f-3e2d-1c0b-9a8b7c6d5e4f/download"
+    }
+  ],
+  "createdAt": "2026-01-15T10:00:00Z",
+  "updatedAt": "2026-01-20T14:30:00Z",
+  "createdBy": "creator@example.com",
+  "updatedBy": "creator@example.com"
+}`,
+    },
+    {
+      description:
+        "Look up by exact template name. Names are unique within the workspace; ambiguity is reported as an error.",
+      command: 'zinkee --json document-templates get "Quarterly report"',
+    },
+  ]),
+  "document-templates create": buildCommandExamples([
+    {
+      description:
+        "Typical create: empty template by name. Assets are uploaded afterwards via document-templates assets add.",
+      command: 'zinkee --json document-templates create --name "Quarterly report"',
+      raw: `{
+  "name": "Quarterly report",
+  "assets": []
+}`,
+      response: `{
+  "id": "7c4a8d3f-1b2e-4a5c-9d6e-1f2a3b4c5d6e",
+  "name": "Quarterly report",
+  "assets": [],
+  "createdAt": "2026-01-15T10:00:00Z",
+  "updatedAt": "2026-01-15T10:00:00Z",
+  "createdBy": "creator@example.com",
+  "updatedBy": "creator@example.com"
+}`,
+    },
+    {
+      description:
+        "Create with pre-existing asset records via --raw. Used for import/migration flows where the assets already exist elsewhere; the typical UX is to create empty and upload via assets add.",
+      command:
+        `zinkee --json document-templates create --raw '{"name":"Annual report","assets":[{"id":"9e8d7c6b-5a4f-3e2d-1c0b-9a8b7c6d5e4f","name":"Cover.docx","link":"/existing/cover.docx"},{"id":"3f2e1d0c-9b8a-7654-3210-fedcba987654","name":"Appendix.docx","link":"/existing/appendix.docx"}]}'`,
+      raw: `{
+  "name": "Annual report",
+  "assets": [
+    {
+      "id": "9e8d7c6b-5a4f-3e2d-1c0b-9a8b7c6d5e4f",
+      "name": "Cover.docx",
+      "link": "/existing/cover.docx"
+    },
+    {
+      "id": "3f2e1d0c-9b8a-7654-3210-fedcba987654",
+      "name": "Appendix.docx",
+      "link": "/existing/appendix.docx"
+    }
+  ]
+}`,
+    },
+  ]),
+  "document-templates update": buildCommandExamples([
+    {
+      description:
+        "Rename a template. The template argument accepts a UUID or an exact current name. Only the name is updatable through this endpoint; assets are managed via the assets subcommands.",
+      command:
+        'zinkee --json document-templates update "Quarterly report" --name "Annual report"',
+      raw: `{
+  "name": "Annual report"
+}`,
+      response: `{
+  "id": "7c4a8d3f-1b2e-4a5c-9d6e-1f2a3b4c5d6e",
+  "name": "Annual report",
+  "assets": [
+    {
+      "id": "9e8d7c6b-5a4f-3e2d-1c0b-9a8b7c6d5e4f",
+      "name": "Requirements.docx",
+      "link": "/api/v2/document-templates/7c4a8d3f-1b2e-4a5c-9d6e-1f2a3b4c5d6e/assets/9e8d7c6b-5a4f-3e2d-1c0b-9a8b7c6d5e4f/download"
+    }
+  ],
+  "createdAt": "2026-01-15T10:00:00Z",
+  "updatedAt": "2026-01-22T09:15:00Z",
+  "createdBy": "creator@example.com",
+  "updatedBy": "updater@example.com"
+}`,
+    },
+  ]),
+  "document-templates delete": buildCommandExamples([
+    {
+      description:
+        "Delete a template and remove its asset files from storage. Record fields that reference previously generated documents are not modified.",
+      command:
+        "zinkee --json document-templates delete 7c4a8d3f-1b2e-4a5c-9d6e-1f2a3b4c5d6e",
+      response: `{
+  "id": "7c4a8d3f-1b2e-4a5c-9d6e-1f2a3b4c5d6e",
+  "deleted": true
+}`,
+    },
+  ]),
+  "document-templates assets add": buildCommandExamples([
+    {
+      description:
+        "Upload a local file as an asset of a template. The CLI sends a multipart form with a part named \"file\"; the asset display name defaults to the uploaded filename.",
+      command:
+        'zinkee --json document-templates assets add "Quarterly report" ./contract.docx',
+      response: `{
+  "id": "7c4a8d3f-1b2e-4a5c-9d6e-1f2a3b4c5d6e",
+  "name": "Quarterly report",
+  "assets": [
+    {
+      "id": "9e8d7c6b-5a4f-3e2d-1c0b-9a8b7c6d5e4f",
+      "name": "contract.docx",
+      "link": "/api/v2/document-templates/7c4a8d3f-1b2e-4a5c-9d6e-1f2a3b4c5d6e/assets/9e8d7c6b-5a4f-3e2d-1c0b-9a8b7c6d5e4f/download"
+    }
+  ],
+  "createdAt": "2026-01-15T10:00:00Z",
+  "updatedAt": "2026-01-22T09:15:00Z",
+  "createdBy": "creator@example.com",
+  "updatedBy": "updater@example.com"
+}`,
+    },
+    {
+      description:
+        "Override the asset display name with --name (otherwise the uploaded filename is used).",
+      command:
+        'zinkee --json document-templates assets add "Quarterly report" ./contract.docx --name "Customer Contract"',
+    },
+  ]),
+  "document-templates assets delete": buildCommandExamples([
+    {
+      description: "Delete one asset from a template and remove its file from storage.",
+      command:
+        "zinkee --json document-templates assets delete 7c4a8d3f-1b2e-4a5c-9d6e-1f2a3b4c5d6e 9e8d7c6b-5a4f-3e2d-1c0b-9a8b7c6d5e4f",
+      response: `{
+  "id": "9e8d7c6b-5a4f-3e2d-1c0b-9a8b7c6d5e4f",
+  "deleted": true
+}`,
+    },
+  ]),
+  "document-templates assets download": buildCommandExamples([
+    {
+      description:
+        "Download asset bytes to disk. The CLI streams the raw bytes to --output; in --json mode --output is required and the JSON envelope only carries metadata.",
+      command:
+        "zinkee --json document-templates assets download 7c4a8d3f-1b2e-4a5c-9d6e-1f2a3b4c5d6e 9e8d7c6b-5a4f-3e2d-1c0b-9a8b7c6d5e4f --output ./contract.docx",
+    },
+    {
+      description:
+        "Stream asset bytes to stdout (omit --json and --output). Useful for piping into other tools.",
+      command:
+        "zinkee document-templates assets download 7c4a8d3f-1b2e-4a5c-9d6e-1f2a3b4c5d6e 9e8d7c6b-5a4f-3e2d-1c0b-9a8b7c6d5e4f > contract.docx",
+    },
+  ]),
 };
 
 function fallbackExamples(commandName: string): readonly CommandExample[] {