@factorialco/fcode-cli 3.3.0 → 3.4.0

package/README.md

@@ -20,7 +20,7 @@ $ npm install -g @factorialco/fcode-cli
 $ fcode COMMAND
 running command...
 $ fcode (--version)
-@factorialco/fcode-cli/3.3.0 linux-x64 node-v22.22.3
+@factorialco/fcode-cli/3.4.0 linux-x64 node-v22.22.3
 $ fcode --help [COMMAND]
 USAGE
   $ fcode COMMAND

package/dist/core/types.d.ts

@@ -161,6 +161,62 @@ export interface ProcessUiTrigger {
      */
     awaitResult?: boolean;
 }
+export interface ProcessFactorial {
+    /** Master switch: nothing below is exposed while false. */
+    enabled: boolean;
+    /**
+     * Whether Factorial waits for the execution and receives its result. Defaults to true, and is
+     * omitted from metadata.json when it does.
+     */
+    awaitResult?: boolean;
+    /**
+     * Monolith policy keys the caller must hold: the outer list is an OR of alternatives, each
+     * inner list an AND. Free text as far as fcode is concerned. Omitted when empty.
+     */
+    requiredPolicies?: string[][];
+    uiTrigger?: ProcessFactorialUiTrigger;
+    form?: ProcessFactorialForm;
+    agentTool?: ProcessFactorialAgentTool;
+    backend?: ProcessFactorialBackend;
+}
+export interface ProcessFactorialUiTrigger {
+    enabled: boolean;
+    /** Identifier of the UI location the button is rendered in. Required while enabled. */
+    locationId?: string;
+    /** Button text; the only field of the block that accepts fcode.i18n("key") tokens. */
+    label?: string;
+    /** f0 icon name, e.g. "Globe". */
+    icon?: string;
+}
+export interface ProcessFactorialForm {
+    enabled: boolean;
+    /** Whether the form may be embedded anonymously. Omitted from metadata.json when false. */
+    public?: boolean;
+    /**
+     * Whether the app offers the form to its users from its own page in Factorial. The `factorial`
+     * block's name for `form.appRole: "USER_FACING_FORM"`. Omitted from metadata.json when false.
+     */
+    appTool?: boolean;
+}
+export type AgentToolEffect = 'READ' | 'WRITE' | 'DESTRUCTIVE';
+export interface ProcessFactorialAgentTool {
+    enabled: boolean;
+    /** What the tool does, written for the model. */
+    description?: string;
+    effect?: AgentToolEffect;
+    whenToUse?: string;
+    whenNotToUse?: string[];
+    preconditions?: string[];
+    doesNotDo?: string[];
+    /** What the agent should do when the tool is unavailable or fails. */
+    degradation?: string;
+    /** Slug of the process this one previews the outcome of, when it is a dry run. */
+    simulatesFor?: string;
+}
+export interface ProcessFactorialBackend {
+    enabled: boolean;
+}
+export type LifecycleRole = 'INSTALL' | 'SETTINGS' | 'UNINSTALL' | 'SYNC';
 export interface ProcessMetadataFields {
     name: string;
     description?: string;
@@ -168,6 +224,7 @@ export interface ProcessMetadataFields {
     webhook?: ProcessWebhook;
     form?: ProcessForm;
     uiTrigger?: ProcessUiTrigger;
+    factorial?: ProcessFactorial;
 }
 export declare class Process extends Resource {
     id: string;
@@ -179,6 +236,9 @@ export declare class Process extends Resource {
     webhook?: ProcessWebhook;
     form?: ProcessForm;
     uiTrigger?: ProcessUiTrigger;
+    factorial?: ProcessFactorial;
+    /** Set by the platform for the reserved lifecycle slugs; not part of the content hash. */
+    lifecycleRole?: LifecycleRole;
     script: {
         parametersSchema: any;
         programmingLanguage: ProgrammingLanguage;

package/dist/core/types.js

@@ -73,6 +73,7 @@ class Process extends Resource {
         this.webhook = metadata.webhook;
         this.form = metadata.form;
         this.uiTrigger = metadata.uiTrigger;
+        this.factorial = metadata.factorial;
         this.script = script;
         this.readme = readme;
         this.manifest = settings.dependencies.scopedToProcess && manifest !== null ? manifest : { dependencies: [] };
@@ -92,6 +93,7 @@ class Process extends Resource {
             // Inserted only when set, so every process that predates UI triggers keeps the
             // content hash already stored in .fcode (mirrors WorkspaceSettings.contentHash).
             ...(this.uiTrigger && { uiTrigger: this.uiTrigger }),
+            ...(this.factorial && { factorial: this.factorial }),
             manifestDependencies: this.manifest.dependencies,
             dependenciesScopedToProcess: this.settings.dependencies.scopedToProcess,
             ...(this.deletion && { deletion: deletionHashPart(this.deletion) }),

package/dist/repositories/process.js

@@ -37,8 +37,23 @@ function buildProcessMetadata(process) {
     if (process.uiTrigger !== undefined) {
         metadata.uiTrigger = process.uiTrigger;
     }
+    if (process.factorial !== undefined) {
+        metadata.factorial = process.factorial;
+    }
     return metadata;
 }
+/**
+ * The `factorial` block as the file has it, minus the `title` and `description` keys an earlier
+ * draft of the block carried: the process's own name and description took their place, so a file
+ * that still has them is read as if it did not, and the next save drops them.
+ */
+function readFactorialBlock(raw) {
+    if (raw === undefined || raw === null || typeof raw !== 'object') {
+        return raw ?? undefined;
+    }
+    const { title: _title, description: _description, ...factorial } = raw;
+    return factorial;
+}
 const PROCESS_SOURCE_CODE_FILE_NAME = (programmingLanguage) => (programmingLanguage === 'PYTHON' ? 'main.py' : 'index.js');
 exports.PROCESS_SOURCE_CODE_FILE_NAME = PROCESS_SOURCE_CODE_FILE_NAME;
 const PROCESS_DEPENDENCIES_FILE_NAME = (programmingLanguage) => PROGRAMMING_LANGUAGE_DEPENDENCIES_FILE_NAME[programmingLanguage];
@@ -163,6 +178,7 @@ class ProcessRepository extends resource_1.default {
                 webhook: raw.webhook,
                 form: raw.form,
                 uiTrigger: raw.uiTrigger,
+                factorial: readFactorialBlock(raw.factorial),
             };
         }
         catch (error) {

package/dist/services/fcode-graphql-client.d.ts

@@ -67,7 +67,26 @@ declare class FcodeGraphQLClient {
      * using the default header — keeps the metadata.json it already had on disk.
      */
     private mapWebhook;
-    mapProcess({ id, slug, name, description, tags, script, readme, manifest, settings, triggers, resolvingTeamSlug, deletedAt, retainingVersionTags }: any): Process;
+    /**
+     * metadata.json omits every defaulted field of the `factorial` block, so the input restores
+     * them explicitly: every input field left out means "leave unchanged" on the platform, and the
+     * file is the source of truth. That includes the agent tool's clearable texts, sent as "" when
+     * the file has none so deleting the line clears the value. The platform reads a null or empty
+     * `uiTrigger.locationId` / `label` / `icon` and `agentTool.effect` as unchanged, though, so
+     * those are sent only when present (like the legacy `uiTrigger.label`).
+     */
+    private toFactorialInput;
+    /**
+     * The `factorial` block as metadata.json writes it: defaulted fields omitted, and a block or
+     * sub-block omitted only when disabled AND all defaults — a disabled sub-block that still carries
+     * settings (a tool contract, a trigger location, a public form) is kept, or a pull followed by a
+     * push would clear them on the platform. The platform always returns the block, so a process
+     * that never configured one comes back as all defaults and is mapped to no block at all, or every
+     * process in every workspace would gain a `factorial` key (and a new content hash) on its next
+     * pull.
+     */
+    private mapFactorialSettings;
+    mapProcess({ id, slug, name, description, tags, script, readme, manifest, settings, triggers, resolvingTeamSlug, lifecycleRole, deletedAt, retainingVersionTags, }: any): Process;
     /**
      * GraphQL nests the webhook configuration under `settings`, while settings.json and the REST API
      * keep it flat. Mapping it explicitly is what keeps that mismatch from silently reading as

package/dist/services/fcode-graphql-client.js

@@ -40,6 +40,17 @@ const DELETION_FIELDS = `
   retainingVersionTags
 `;
 const DELETION_QUERY_FIELDS = ['includeDeleted', 'deletedAt', 'retainingVersionTags'];
+// The optional fields of the agent tool contract, by kind. All are written to metadata.json only
+// when present. On push a list is always sent and a clearable text always sent as at least "",
+// since the platform clears both on an empty value; `effect` is the one text it does not clear,
+// so that one is sent only when present.
+const AGENT_TOOL_CLEARABLE_TEXT_FIELDS = ['description', 'whenToUse', 'degradation', 'simulatesFor'];
+const AGENT_TOOL_TEXT_FIELDS = [...AGENT_TOOL_CLEARABLE_TEXT_FIELDS, 'effect'];
+const AGENT_TOOL_LIST_FIELDS = ['whenNotToUse', 'preconditions', 'doesNotDo'];
+/** A settings block that is disabled and holds nothing else is omitted from metadata.json. */
+function unlessAllDefaults(block) {
+    return !block.enabled && Object.keys(block).length === 1 ? undefined : block;
+}
 // Shared process selection so pull queries and push mutations return the same
 // fields, keeping mapProcess (and therefore contentHash) consistent.
 const PROCESS_FIELDS = `
@@ -49,6 +60,7 @@ const PROCESS_FIELDS = `
   description
   tags
   resolvingTeamSlug
+  lifecycleRole
   script {
     parametersSchema
     sourceCode
@@ -85,6 +97,36 @@ const PROCESS_FIELDS = `
       icon
       awaitResult
     }
+    factorial {
+      enabled
+      awaitResult
+      requiredPolicies
+      uiTrigger {
+        enabled
+        locationId
+        label
+        icon
+      }
+      form {
+        enabled
+        public
+        appTool
+      }
+      agentTool {
+        enabled
+        description
+        effect
+        whenToUse
+        whenNotToUse
+        preconditions
+        doesNotDo
+        degradation
+        simulatesFor
+      }
+      backend {
+        enabled
+      }
+    }
     dependencies {
       scopedToProcess
     }
@@ -468,16 +510,30 @@ class FcodeGraphQLClient {
         const settings = {
             dependencies: { scopedToProcess: process.settings.dependencies.scopedToProcess },
         };
+        // The platform mirrors `factorial` into the legacy `formSettings` / `uiTrigger` blocks, so
+        // once metadata.json carries it the legacy keys only contribute what the mirror leaves alone
+        // (the form's auth mode, and every app role but `USER_FACING_FORM`, which the block owns as
+        // `form.appTool`); their enablement is not sent, or the last one applied would win over the
+        // block the developer actually edits.
+        if (process.factorial) {
+            settings.factorial = this.toFactorialInput(process.factorial, process.form);
+        }
         if (process.form) {
-            settings.formSettings = { enabled: process.form.enabled };
-            if (process.form.appRole) {
-                settings.formSettings.appRole = process.form.appRole;
+            const formSettings = process.factorial ? {} : { enabled: process.form.enabled };
+            // `USER_FACING_FORM` is the one app role the `factorial` block owns, as `form.appTool`, so
+            // once the block is there that value travels with it; the lifecycle roles, which the block
+            // has no switch for, keep coming from here.
+            if (process.form.appRole && !(process.factorial && process.form.appRole === 'USER_FACING_FORM')) {
+                formSettings.appRole = process.form.appRole;
             }
             if (process.form.authMode) {
-                settings.formSettings.authMode = process.form.authMode;
+                formSettings.authMode = process.form.authMode;
+            }
+            if (Object.keys(formSettings).length > 0) {
+                settings.formSettings = formSettings;
             }
         }
-        if (process.uiTrigger) {
+        if (process.uiTrigger && !process.factorial) {
             settings.uiTrigger = { enabled: process.uiTrigger.enabled };
             if (process.uiTrigger.locationId) {
                 settings.uiTrigger.locationId = process.uiTrigger.locationId;
@@ -796,7 +852,112 @@ class FcodeGraphQLClient {
         }
         return webhook;
     }
-    mapProcess({ id, slug, name, description, tags, script, readme, manifest, settings, triggers, resolvingTeamSlug, deletedAt, retainingVersionTags }) {
+    /**
+     * metadata.json omits every defaulted field of the `factorial` block, so the input restores
+     * them explicitly: every input field left out means "leave unchanged" on the platform, and the
+     * file is the source of truth. That includes the agent tool's clearable texts, sent as "" when
+     * the file has none so deleting the line clears the value. The platform reads a null or empty
+     * `uiTrigger.locationId` / `label` / `icon` and `agentTool.effect` as unchanged, though, so
+     * those are sent only when present (like the legacy `uiTrigger.label`).
+     */
+    toFactorialInput(factorial, form) {
+        const input = {
+            enabled: factorial.enabled,
+            awaitResult: factorial.awaitResult ?? true,
+            requiredPolicies: factorial.requiredPolicies ?? [],
+            uiTrigger: { enabled: Boolean(factorial.uiTrigger?.enabled) },
+            form: {
+                enabled: Boolean(factorial.form?.enabled),
+                public: Boolean(factorial.form?.public),
+                // A file written before the flag existed says nothing about `appTool`, and the block wins
+                // over the legacy `appRole` applied before it — so an absent flag falls back to the role
+                // rather than to `false`, which would release it.
+                appTool: factorial.form?.appTool ?? form?.appRole === 'USER_FACING_FORM',
+            },
+            agentTool: {
+                enabled: Boolean(factorial.agentTool?.enabled),
+                whenNotToUse: factorial.agentTool?.whenNotToUse ?? [],
+                preconditions: factorial.agentTool?.preconditions ?? [],
+                doesNotDo: factorial.agentTool?.doesNotDo ?? [],
+            },
+            backend: { enabled: Boolean(factorial.backend?.enabled) },
+        };
+        for (const field of AGENT_TOOL_CLEARABLE_TEXT_FIELDS) {
+            input.agentTool[field] = factorial.agentTool?.[field] ?? '';
+        }
+        if (factorial.agentTool?.effect) {
+            input.agentTool.effect = factorial.agentTool.effect;
+        }
+        if (factorial.uiTrigger?.locationId) {
+            input.uiTrigger.locationId = factorial.uiTrigger.locationId;
+        }
+        if (factorial.uiTrigger?.label) {
+            input.uiTrigger.label = factorial.uiTrigger.label;
+        }
+        if (factorial.uiTrigger?.icon) {
+            input.uiTrigger.icon = factorial.uiTrigger.icon;
+        }
+        return input;
+    }
+    /**
+     * The `factorial` block as metadata.json writes it: defaulted fields omitted, and a block or
+     * sub-block omitted only when disabled AND all defaults — a disabled sub-block that still carries
+     * settings (a tool contract, a trigger location, a public form) is kept, or a pull followed by a
+     * push would clear them on the platform. The platform always returns the block, so a process
+     * that never configured one comes back as all defaults and is mapped to no block at all, or every
+     * process in every workspace would gain a `factorial` key (and a new content hash) on its next
+     * pull.
+     */
+    mapFactorialSettings(factorial) {
+        if (!factorial) {
+            return undefined;
+        }
+        const mapped = { enabled: Boolean(factorial.enabled) };
+        if (factorial.awaitResult === false) {
+            mapped.awaitResult = false;
+        }
+        if (Array.isArray(factorial.requiredPolicies) && factorial.requiredPolicies.length > 0) {
+            mapped.requiredPolicies = factorial.requiredPolicies;
+        }
+        if (factorial.uiTrigger) {
+            const uiTrigger = { enabled: Boolean(factorial.uiTrigger.enabled) };
+            for (const field of ['locationId', 'label', 'icon']) {
+                if (factorial.uiTrigger[field]) {
+                    uiTrigger[field] = factorial.uiTrigger[field];
+                }
+            }
+            mapped.uiTrigger = unlessAllDefaults(uiTrigger);
+        }
+        if (factorial.form) {
+            const form = { enabled: Boolean(factorial.form.enabled) };
+            if (factorial.form.public) {
+                form.public = true;
+            }
+            if (factorial.form.appTool) {
+                form.appTool = true;
+            }
+            mapped.form = unlessAllDefaults(form);
+        }
+        if (factorial.agentTool) {
+            const agentTool = { enabled: Boolean(factorial.agentTool.enabled) };
+            for (const field of AGENT_TOOL_TEXT_FIELDS) {
+                if (factorial.agentTool[field]) {
+                    agentTool[field] = factorial.agentTool[field];
+                }
+            }
+            for (const field of AGENT_TOOL_LIST_FIELDS) {
+                if (Array.isArray(factorial.agentTool[field]) && factorial.agentTool[field].length > 0) {
+                    agentTool[field] = factorial.agentTool[field];
+                }
+            }
+            mapped.agentTool = unlessAllDefaults(agentTool);
+        }
+        if (factorial.backend?.enabled) {
+            mapped.backend = { enabled: true };
+        }
+        return unlessAllDefaults(_.omitBy(mapped, _.isUndefined));
+    }
+    mapProcess({ id, slug, name, description, tags, script, readme, manifest, settings, triggers, resolvingTeamSlug, lifecycleRole, deletedAt, retainingVersionTags, }) {
         const dependencies = _.map(manifest?.dependencies, (dependency) => {
             return { name: dependency.name, specifier: dependency.gitUrl ?? dependency.semVer };
         });
@@ -832,7 +993,15 @@ class FcodeGraphQLClient {
                 metadata.uiTrigger.awaitResult = true;
             }
         }
-        return new types_1.Process(id, slug, script, readme, { dependencies }, settings, metadata, this.inheritedTeam(resolvingTeamSlug), this.deletionOf(deletedAt, retainingVersionTags));
+        const factorial = this.mapFactorialSettings(settings?.factorial);
+        if (factorial) {
+            metadata.factorial = factorial;
+        }
+        const process = new types_1.Process(id, slug, script, readme, { dependencies }, settings, metadata, this.inheritedTeam(resolvingTeamSlug), this.deletionOf(deletedAt, retainingVersionTags));
+        if (lifecycleRole) {
+            process.lifecycleRole = lifecycleRole;
+        }
+        return process;
     }
     /**
      * GraphQL nests the webhook configuration under `settings`, while settings.json and the REST API

package/oclif.manifest.json

@@ -2516,5 +2516,5 @@
       ]
     }
   },
-  "version": "3.3.0"
+  "version": "3.4.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@factorialco/fcode-cli",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "packageManager": "pnpm@11.7.0",
   "description": "Factorial Code Command Line Interface",
   "homepage": "https://code.factorialhr.com/docs/cli/",