contensis-cli 1.6.1-beta.9 → 1.7.1-beta.0

package/docs/copy_field_templates.md

@@ -352,3 +352,115 @@ Or we can refer to other fields in the `entry` variable
 ```handlebars
 {{entry.text}}{% if entry.heading %} - {{entry.heading}}{% endif %}
 ```
+
+### Transforming fields inside Canvas blocks
+
+Canvas fields contain an array of blocks (objects with `id`, `type`, `value`, `properties`). Some blocks are components (`_component` type with `properties.component`) that hold nested fields inside `value`. To transform those inner fields - for example converting a rich text field inside a component to canvas format - you need to rebuild the canvas array by iterating over the blocks and selectively transforming the ones you need.
+
+This is done using the `capture` tag to build the output as a JSON string, then `from_json | json` to validate and minify the result.
+
+#### Example: Convert rich text to canvas inside a component block
+
+Given a canvas field containing a `linkedComponent` block with a `richText` field:
+
+```json
+{
+  "id": "5b03fe6a",
+  "type": "_component",
+  "properties": { "component": "linkedComponent" },
+  "value": {
+    "entry": [{ "sys": { "id": "abc123", "dataFormat": "entry" } }],
+    "title": "My component",
+    "richText": "<h2>Original rich text</h2>",
+    "canvas": null
+  }
+}
+```
+
+This template converts `richText` to canvas via `html_to_canvas`, storing it in the `canvas` field. Other blocks pass through unchanged:
+
+```handlebars
+{% capture out %}
+[
+{%- for b in value -%}
+{%- if forloop.index0 > 0 %},{% endif -%}
+{%- if b.properties.component == "linkedComponent" -%}
+{
+  "id": {{ b.id | json }},
+  "type": {{ b.type | json }},
+  "properties": {{ b.properties | json }},
+  "value": {
+    "entry": {{ b.value.entry | json }},
+    "title": {{ b.value.title | json }},
+    "richText": {{ b.value.richText | json }},
+    "canvas": {% if b.value.richText and b.value.richText != "" %}{{ b.value.richText | html_to_canvas | json }}{% else %}{{ b.value.canvas | json }}{% endif %}
+  }
+}
+{%- else -%}
+{{ b | json }}
+{%- endif -%}
+{%- endfor -%}
+]
+{% endcapture %}
+{{ out | from_json | json }}
+```
+
+#### How it works
+
+1. `{% capture out %}` starts building the output as a JSON string
+2. The outer `[` opens the canvas array
+3. `{% for b in value %}` iterates over every block in the canvas
+4. `{% if b.properties.component == "linkedComponent" %}` matches the block we want to transform
+5. Each field in the block is mapped with `|json` to ensure valid JSON output (strings get quotes, objects serialize correctly)
+6. The `canvas` field conditionally applies `html_to_canvas` when `richText` exists, otherwise passes the existing value through
+7. `{% else %}` passes non-matching blocks through unchanged via `{{ b | json }}`
+8. `{% endcapture %}` closes the string, then `{{ out | from_json | json }}` parses and re-serializes to validate the JSON
+
+#### Why `|json` is needed on every mapped field
+
+Without it, strings would render bare (invalid JSON: `hello` instead of `"hello"`) and objects would render as `[object Object]`. The `|json` filter handles strings, objects, arrays, nulls, and booleans correctly.
+
+#### Handling nested component blocks
+
+If a canvas block contains a repeatable array of sub-components, you can nest the same pattern. For example, a `nestingLinkedComponent` block has `linkedComponent[]` items, each with their own `richText` and `canvas`:
+
+```handlebars
+{% capture out %}
+[
+{%- for b in value -%}
+{%- if forloop.index0 > 0 %},{% endif -%}
+{%- if b.properties.component == "nestingLinkedComponent" -%}
+{
+  "id": {{ b.id | json }},
+  "type": {{ b.type | json }},
+  "properties": {{ b.properties | json }},
+  "value": {
+    "linkedComponent": [
+    {%- for it in b.value.linkedComponent -%}
+    {%- if forloop.index0 > 0 %},{% endif -%}
+    {
+      "entry": {{ it.entry | json }},
+      "title": {{ it.title | json }},
+      "richText": {{ it.richText | json }},
+      "canvas": {% if it.richText and it.richText != "" %}{{ it.richText | html_to_canvas | json }}{% else %}{{ it.canvas | json }}{% endif %}
+    }
+    {%- endfor -%}
+    ],
+    "singleLinkedComponent": {
+      "entry": {{ b.value.singleLinkedComponent.entry | json }},
+      "title": {{ b.value.singleLinkedComponent.title | json }},
+      "richText": {{ b.value.singleLinkedComponent.richText | json }},
+      "canvas": {% if b.value.singleLinkedComponent.richText and b.value.singleLinkedComponent.richText != "" %}{{ b.value.singleLinkedComponent.richText | html_to_canvas | json }}{% else %}{{ b.value.singleLinkedComponent.canvas | json }}{% endif %}
+    }
+  }
+}
+{%- else -%}
+{{ b | json }}
+{%- endif -%}
+{%- endfor -%}
+]
+{% endcapture %}
+{{ out | from_json | json }}
+```
+
+The same `richText` to `canvas` conversion is applied to each item in the repeatable `linkedComponent` array and to the singular `singleLinkedComponent` block.

package/esbuild.config.js

@@ -1,3 +1,4 @@
+const fs = require('fs');
 const { rimraf } = require('rimraf');
 const esbuild = require('esbuild');
 const chalk = require('chalk');
@@ -5,7 +6,12 @@ const { globPlugin } = require('esbuild-plugin-glob');
 const { nodeExternalsPlugin } = require('esbuild-node-externals');
 const { replaceTscAliasPaths } = require('tsc-alias');
 
-// const watch = !!process.argv.includes('--watch');
+// embed the current package version into the build
+// (package.json is the single source of truth; this used to be a `prebuild`
+// npm lifecycle script, which lerna/yarn builds never fire - see release 1.7.0)
+const { version } = require('./package.json');
+fs.writeFileSync('./src/version.ts', `export const LIB_VERSION = ${JSON.stringify(version)};\n`);
+
 const completed = `${chalk.green('[contensis-cli]')} Build successful 👍\n`;
 
 console.time(completed);
@@ -16,9 +22,9 @@ rimraf('./dist').then(() => {
   console.time(' - esbuild complete');
   esbuild
     .build({
-      entryPoints: ['src/**/*.[jt]s'],
+      entryPoints: ['src/index.ts', 'src/shell.ts'],
       outdir: 'dist',
-      bundle: false,
+      bundle: true,
       minify: false,
       platform: 'node',
       format: 'cjs',
@@ -26,16 +32,12 @@ rimraf('./dist').then(() => {
       // needs to be node12 to transform dynamic imports into requires
       // so the bundles are compatible with the pkg exe builds
       target: 'node12',
-      plugins: [globPlugin(), nodeExternalsPlugin()],
-      // watch: watch && {
-      //   onRebuild(error) {
-      //     if (error) console.error('esbuild watch build failed:', error);
-      //     else
-      //       console.log(
-      //         'esbuild watch build succeeded, waiting for changes...'
-      //       );
-      //   },
-      // },
+      plugins: [globPlugin(), nodeExternalsPlugin({
+        allowList: [/^@inquirer\//],
+        dependencies: true,
+        forceExternalList: ['enterprise-fetch']
+        // forceExternalList: ['keytar', '@action-validator/core', 'figlet', 'node-fetch', 'enterprise-fetch']
+      })],
     })
     .then(() => {
       console.timeEnd(' - esbuild complete');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contensis-cli",
-  "version": "1.6.1-beta.9",
+  "version": "1.7.1-beta.0",
   "description": "A fully featured Contensis command line interface with a shell UI provides simple and intuitive ways to manage or profile your content in any NodeJS terminal.",
   "repository": {
     "type": "git",
@@ -16,7 +16,6 @@
     "prestart": "npm run build",
     "start": "npm run cli",
     "dev:shell": "npm run prestart && nodemon --watch dist --inspect=9229 ./dist/shell.js",
-    "prebuild": "node -p \"'export const LIB_VERSION = ' + JSON.stringify(require('./package.json').version) + ';'\" > src/version.ts",
     "build": "node esbuild.config.js",
     "build:watch": "node esbuild.config.js --watch",
     "cli": "node --inspect=9229 ./cli.js",
@@ -25,7 +24,7 @@
     "package-lock": "npm i --package-lock-only --workspaces false"
   },
   "author": "Zengenti",
-  "license": "ISC",
+  "license": "GPL-3.0",
   "dependencies": {
     "@action-validator/core": "^0.6.0",
     "@inquirer/prompts": "^8.2.0",
@@ -43,7 +42,7 @@
     "inquirer-command-prompt": "^0.1.0",
     "keytar": "^7.9.0",
     "lodash": "^4.17.21",
-    "migratortron": "^1.0.0-beta.86",
+    "migratortron": "^1.0.0-beta.89",
     "nanospinner": "^1.2.0",
     "node-fetch": "^2.6.7",
     "parse-git-config": "^3.0.0",

package/src/commands/create.ts

@@ -71,6 +71,54 @@ Example call:
       );
     });
 
+  create
+    .command('node')
+    .description('create a new site view node')
+    .argument('<"node path or id">', 'the path or id of the node to create')
+    .argument(
+      '["display name"]',
+      'provide a separate display name for the node (optional)'
+    )
+    .argument(
+      '["slug"]',
+      'provide a slug for the node (defaults to slug from provided node path)'
+    )
+    .option(
+      '--include-in-menu',
+      'set include in menu flag on the created node',
+      false
+    )
+    .option(
+      '--language <language>',
+      'language of the node to create (defaults to current project primary language)'
+    )
+    .option('--entry-id <entryId>', 'attach an entry to the node')
+    .usage(
+      '<"node path or id"> ["display name"] (both args in "double quotes")'
+    )
+    .addHelpText(
+      'after',
+      `
+Example call:
+  > create node /test "Test Node" --include-in-menu\n`
+    )
+    .action(
+      async (
+        pathOrId: string,
+        displayName: string,
+        slug: string,
+        opts: any
+      ) => {
+        await cliCommand(['create', 'node', pathOrId], opts).CreateOrUpdateNode(
+          pathOrId,
+          opts,
+          displayName,
+          slug,
+          opts.language
+        );
+      }
+    );
+
   create
     .command('role')
     .description('create a new role')

package/src/commands/dev.ts

@@ -62,6 +62,12 @@ Example call:
       '--override [override...]',
       'override configurations for other blocks'
     )
+    .addOption(
+      new Option(
+        '-ll --log-level <logLevel>',
+        'set the request handler logging level'
+      ).choices(['debug', 'information', 'warning', 'error', 'none'])
+    )
     .usage('[block-id] [local-uri]')
     .addHelpText(
       'after',

package/src/commands/push.ts

@@ -212,6 +212,13 @@ Example call:
         },
         projectId: () => cli.env.currentProject || '',
         source: {
+          // Provenance resolution order per field:
+          //  1. explicit cli flag (camelCase key from commander opts)
+          //  2. CONTENSIS_* env var - a safe channel for CI actions to supply
+          //     values without embedding them in the command string (where mapped)
+          //  3. generic CI variables the runner exports
+          // The mapper skips empty/undefined candidates and uses the first
+          // non-empty value, so unset optional vars never mask a fallback.
           provider: {
             $path: ['provider'],
             $return: (provider: string, { GITHUB_ACTIONS, GITLAB_CI }) => {
@@ -221,9 +228,15 @@ Example call:
             },
           },
           repositoryUrl: {
-            $path: ['repositoryUrl', 'CI_PROJECT_URL', 'GITHUB_REPOSITORY'],
+            $path: [
+              'repositoryUrl',
+              'CONTENSIS_REPOSITORY_URL',
+              'CI_PROJECT_URL',
+              'GITHUB_REPOSITORY',
+            ],
             $formatting: (url: string, { GITHUB_ACTIONS }) => {
-              if (GITHUB_ACTIONS) url = `https://github.com/${url}`;
+              if (GITHUB_ACTIONS && !url.startsWith(`https://`))
+                url = `https://github.com/${url}`;
 
               if (url && !url.endsWith('.git')) return `${url}.git`;
               return url;
@@ -231,16 +244,35 @@ Example call:
           },
           branch: ['branch', 'CI_COMMIT_REF_NAME', 'GITHUB_REF_NAME'],
           commit: {
-            id: ['commitId', 'CI_COMMIT_SHORT_SHA', 'GITHUB_SHA'],
+            id: [
+              'commitId',
+              'CONTENSIS_COMMIT_ID',
+              'CI_COMMIT_SHORT_SHA',
+              'GITHUB_SHA',
+            ],
             message: {
-              $path: ['commitMessage', 'CI_COMMIT_MESSAGE'], // ${{ github.event.head_commit.message }}
+              $path: [
+                'commitMessage',
+                'CONTENSIS_COMMIT_MESSAGE',
+                'CI_COMMIT_MESSAGE',
+              ], // ${{ github.event.head_commit.message }}
               $formatting: (msg?: string) =>
                 msg?.replace(/\\n/g, ' ').replace(/\\n/g, ' ').trim(),
             },
-            dateTime: ['commitDatetime', 'CI_COMMIT_TIMESTAMP'], // ${{ github.event.head_commit.timestamp }}
-            authorEmail: ['authorEmail', 'GITLAB_USER_EMAIL', 'GITHUB_ACTOR'], // ${{ github.event.head_commit.author.email }}
+            dateTime: [
+              'commitDatetime',
+              'CONTENSIS_COMMIT_DATETIME',
+              'CI_COMMIT_TIMESTAMP',
+            ], // ${{ github.event.head_commit.timestamp }}
+            authorEmail: [
+              'authorEmail',
+              'CONTENSIS_AUTHOR_EMAIL',
+              'GITLAB_USER_EMAIL',
+              'GITHUB_ACTOR',
+            ], // ${{ github.event.head_commit.author.email }}
             committerEmail: [
               'committerEmail',
+              'CONTENSIS_COMMITTER_EMAIL',
               'GITLAB_USER_EMAIL',
               'GITHUB_TRIGGERING_ACTOR',
             ], // ${{ github.event.head_commit.committer.email }}

package/src/commands/set.ts

@@ -1,4 +1,4 @@
-import { Argument, Command } from 'commander';
+import { Argument, Command, Option } from 'commander';
 import { cliCommand } from '~/services/ContensisCliService';
 import { shell } from '~/shell';
 
@@ -10,6 +10,57 @@ export const makeSetCommand = () => {
     .showHelpAfterError(true)
     .exitOverride();
 
+  const node = set.command('node').description('update a site view node');
+
+  node
+    .command('entry')
+    .description('assign an entry to a node')
+    .argument('<"node path or id">', 'the path or id of the node to update')
+    .argument('<entryId>', 'the new entry id to assign to the node')
+    .usage('<"node path or id"> <entryId>')
+    .addHelpText(
+      'after',
+      `
+Example call:
+  > set node entry /path 1502f64e-e9b1-436b-b62f-e273f639ecb6\n`
+    )
+    .action(async (nodePathOrId: string, entryId: string, opts) => {
+      await cliCommand(['set', 'node', 'entry'], opts).CreateOrUpdateNode(
+        nodePathOrId,
+        { entryId }
+      );
+    });
+
+  node
+    .command('renderer')
+    .description('assign a renderer to a node')
+    .argument('<"node path or id">', 'the path or id of the node to update')
+    .argument('<rendererUuidOrName>', 'the renderer uuid, id or name to assign to the node')
+    .option(
+      '--is-partial-match-root',
+      'should the renderer be used as the partial match root for the node',
+      false
+    )
+    .usage('<"node path or id"> <rendererUuidOrName>')
+    .addHelpText(
+      'after',
+      `
+Example call:
+  > set node renderer /path 1502f64e-e9b1-436b-b62f-e273f639ecb6 --is-partial-match-root
+  > set node renderer /path my-block --is-partial-match-root\n`
+    )
+    .action(async (nodePathOrId: string, rendererId: string, opts) => {
+      await cliCommand(['set', 'node', 'renderer'], opts).CreateOrUpdateNode(
+        nodePathOrId,
+        {
+          renderer: {
+            id: rendererId,
+            isPartialMatchRoot: opts.isPartialMatchRoot,
+          },
+        }
+      );
+    });
+
   const project = set
     .command('project')
     .description('set current working project')
@@ -178,6 +229,21 @@ Example call:
       '--entry-languages [entry-languages...]',
       'the entry languages to add to the role permissions'
     )
+    .addOption(
+      new Option(
+        '--block-actions [block-actions...]',
+        'the block actions to add to the role permissions'
+      ).choices([
+        'push',
+        'release',
+        'manageLive',
+        'manualStartStop',
+        'markAsBroken',
+        'delete',
+        'view',
+        '*',
+      ])
+    )
     .addHelpText(
       'after',
       `
@@ -194,6 +260,9 @@ Example call:
               actions: opts.entryActions || [],
               languages: opts.entryLanguages || [],
             })),
+            blocks: opts.blockActions
+              ? { actions: opts.blockActions }
+              : undefined,
           },
         }
       );

package/src/localisation/en-GB.ts

@@ -188,6 +188,14 @@ export const LogMessages = {
         depth ? ` to a depth of ${depth}` : ``
       }\n`,
     noChange: (env: string) => `[${env}] No changes to be made`,
+    setPayload: () => `Updating node with details\n`,
+    set: (env: string) => `[${env}] Succesfully updated node\n`,
+    failedSet: (env: string, name?: string) =>
+      `[${env}] Unable to update node ${Logger.highlightText(name)}`,
+    created: (env: string, name: string) =>
+      `[${env}] Created node ${Logger.highlightText(name)}\n`,
+    failedCreate: (env: string, name?: string) =>
+      `[${env}] Unable to create node ${Logger.highlightText(name)}`,
   },
   contenttypes: {
     list: (projectId: string) =>
@@ -317,6 +325,10 @@ export const LogMessages = {
       `[${env}] Unable to find renderer ${Logger.highlightText(
         name
       )} in project ${projectId}`,
+    resolved: (env: string, name: string, uuid: string) =>
+      `[${env}] Resolved renderer ${Logger.highlightText(
+        name
+      )} to uuid ${Logger.highlightText(uuid)}`,
     created: (env: string, name: string, projectId: string) =>
       `[${env}] Created renderer ${Logger.highlightText(
         name

package/src/mappers/DevRequests-to-RequestHanderCliArgs.ts

@@ -179,6 +179,9 @@ class RequestHandlerArgs {
         args.push('--password', client.password);
     }
 
+    if (cli.logLevel && !args.find(a => a === '--log-level'))
+      args.push('--log-level', cli.logLevel);
+
     return args;
   };
 

package/src/models/CliService.d.ts

@@ -1,3 +1,5 @@
+import ContensisCli from '~/services/ContensisCliService';
+
 export type CliUrls =
   | {
       api: string;
@@ -33,7 +35,9 @@ export interface IImportOptions {
   sourceProjectId?: string;
 }
 
-export type OutputOptionsConstructorArg = OutputOptions &
+export type OutputOptionsConstructorArg = {
+  logLevel?: ContensisCli['logLevel'];
+} & OutputOptions &
   IConnectOptions &
   IImportOptions;