@factorialco/fcode-cli 1.1.0 → 1.2.0

package/README.md

@@ -2,14 +2,14 @@
 
 Factorial Code is the the all-in-one platform that connects your services and APIs in the most agile way. You may discover every single piece of the Factorial Code Universe in the following links:
 
-- [Factorial Developer Portal](https://code.factorial.dev)
-- [Factorial Code Docs](https://code.factorial.dev/docs)
+- [Factorial Developer Portal](https://code.factorialhr.com)
+- [Factorial Code Docs](https://code.factorialhr.com/docs)
 
-Factorial Code provides both a Graphic User Interface (GUI), accessible at https://code.factorial.dev, and a CLI for interacting with Factorial Code Cloud.
+Factorial Code provides both a Graphic User Interface (GUI), accessible at https://code.factorialhr.com, and a CLI for interacting with Factorial Code Cloud.
 
 The Factorial Code Command Line Interface facilitates interaction with Factorial Code Cloud directly from your local workstation's command line. It's particularly useful if you prefer developing and testing processes' source code locally rather than using the web IDE of Factorial Code Cloud.
 
-See full documentation at [https://code.factorial.dev/docs/cli/](https://code.factorial.dev/docs/cli/).
+See full documentation at [https://code.factorialhr.com/docs/cli/](https://code.factorialhr.com/docs/cli/).
 
 For a guide on writing and running tests for your processes, see [TEST.md](TEST.md).
 
@@ -20,7 +20,7 @@ $ npm install -g @factorialco/fcode-cli
 $ fcode COMMAND
 running command...
 $ fcode (--version)
-@factorialco/fcode-cli/1.1.0 linux-x64 node-v22.22.3
+@factorialco/fcode-cli/1.2.0 linux-x64 node-v22.22.3
 $ fcode --help [COMMAND]
 USAGE
   $ fcode COMMAND
@@ -295,14 +295,15 @@ USAGE
 
 FLAGS
   -a, --authUrl=<value>       Factorial Code Auth endpoint (including realm, ie:
-                              https://code.factorial.dev/auth/realms/fcode)). Only needed if auth domain is different
+                              https://code.factorialhr.com/auth/realms/fcode)). Only needed if auth domain is different
                               than used cloud endpoint
   -c, --clientId=<value>      Client ID (for oauth, to be used with Client Secret)
   -e, --email=<value>         Email (to be used with password)
   -p, --password=<value>      Password (to be used with email)
   -s, --clientSecret=<value>  Client Secret (for oauth, to be used with Client ID)
   -t, --accessToken=<value>   Access Token (to be used instead of email and password)
-  -u, --url=<value>           [default: https://code.factorial.dev/platform] Factorial Code Cloud endpoint
+  -u, --url=<value>           [default: https://code.factorialhr.com/platform] Factorial Code Cloud endpoint (host or
+                              full /platform URL, ie: code.factorialhr.com)
   -x, --prompt                Prompt for email and password (instead of opening browser)
 
 DESCRIPTION
@@ -325,7 +326,8 @@ USAGE
   $ fcode logout [-u <value>]
 
 FLAGS
-  -u, --url=<value>  [default: https://code.factorial.dev/platform] Factorial Code Cloud endpoint
+  -u, --url=<value>  [default: https://code.factorialhr.com/platform] Factorial Code Cloud endpoint (host or full
+                     /platform URL, ie: code.factorialhr.com)
 
 DESCRIPTION
   Logout from Factorial Code

package/dist/commands/login.js

@@ -2,12 +2,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const core_1 = require("@oclif/core");
 const global_1 = require("../config/global");
+const url_utils_1 = require("../utils/url-utils");
 const cli_1 = require("../utils/cli");
 class Login extends core_1.Command {
     async init() {
         const { flags } = await this.parse(Login);
+        const url = (0, url_utils_1.buildCloudUrl)(flags.url);
         const { failures } = await this.config.runHook('auth', {
-            argv: [flags.url, flags.authUrl, flags.email, flags.password, flags.clientId, flags.clientSecret, flags.accessToken, flags.prompt],
+            argv: [url, flags.authUrl, flags.email, flags.password, flags.clientId, flags.clientSecret, flags.accessToken, flags.prompt],
             id: 'login',
         });
         if (failures.length > 0) {
@@ -16,7 +18,7 @@ class Login extends core_1.Command {
     }
     async run() {
         const { flags } = await this.parse(Login);
-        const userInfo = await new global_1.default().getUserInfo(flags.url);
+        const userInfo = await new global_1.default().getUserInfo((0, url_utils_1.buildCloudUrl)(flags.url));
         cli_1.default.log(`👋 Hi, ${userInfo.name}!`);
     }
 }
@@ -26,12 +28,12 @@ Login.examples = ['$ fcode login', '$ fcode login --prompt', '$ fcode login -e y
 Login.flags = {
     url: core_1.Flags.string({
         char: 'u',
-        description: 'Factorial Code Cloud endpoint',
+        description: 'Factorial Code Cloud endpoint (host or full /platform URL, ie: code.factorialhr.com)',
         default: global_1.FCODE_CLOUD_URL,
     }),
     authUrl: core_1.Flags.string({
         char: 'a',
-        description: 'Factorial Code Auth endpoint (including realm, ie: https://code.factorial.dev/auth/realms/fcode)). Only needed if auth domain is different than used cloud endpoint',
+        description: 'Factorial Code Auth endpoint (including realm, ie: https://code.factorialhr.com/auth/realms/fcode)). Only needed if auth domain is different than used cloud endpoint',
     }),
     email: core_1.Flags.string({
         char: 'e',

package/dist/commands/logout.js

@@ -3,13 +3,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const core_1 = require("@oclif/core");
 const auth_service_1 = require("../services/auth-service");
 const global_1 = require("../config/global");
+const url_utils_1 = require("../utils/url-utils");
 const errors_1 = require("../core/errors");
 const cli_1 = require("../utils/cli");
 class Logout extends core_1.Command {
     async run() {
         const { flags } = await this.parse(Logout);
         try {
-            await auth_service_1.default.logout(flags.url);
+            await auth_service_1.default.logout((0, url_utils_1.buildCloudUrl)(flags.url));
         }
         catch (error) {
             if (!(error instanceof errors_1.NotAuthenticated)) {
@@ -27,7 +28,7 @@ Logout.examples = ['$ fcode logout'];
 Logout.flags = {
     url: core_1.Flags.string({
         char: 'u',
-        description: 'Factorial Code Cloud endpoint',
+        description: 'Factorial Code Cloud endpoint (host or full /platform URL, ie: code.factorialhr.com)',
         default: global_1.FCODE_CLOUD_URL,
     }),
 };

package/dist/config/global.js

@@ -7,21 +7,24 @@ const path = require("node:path");
 const errors_1 = require("../core/errors");
 const index_1 = require("./index");
 const settings_1 = require("./settings");
-exports.FCODE_CLOUD_URL = process.env.FCODE_CLOUD_URL || 'https://code.factorial.dev/platform';
+const url_utils_1 = require("../utils/url-utils");
+exports.FCODE_CLOUD_URL = process.env.FCODE_CLOUD_URL || 'https://code.factorialhr.com/platform';
 function parseTeamOrigin(slug) {
     if (!slug) {
         return { url: exports.FCODE_CLOUD_URL, slug: '' };
     }
-    let url;
     try {
-        const { origin } = new URL(slug);
-        slug = slug.replaceAll(origin + '/', '');
-        url = origin;
+        const parsed = new URL(slug);
+        const url = (0, url_utils_1.buildCloudUrl)(parsed.origin);
+        const segments = parsed.pathname.split('/').filter(Boolean);
+        if (segments[0] === 'platform') {
+            segments.shift();
+        }
+        return { url, slug: segments.join('/') };
     }
     catch (e) {
-        url = exports.FCODE_CLOUD_URL;
+        return { url: exports.FCODE_CLOUD_URL, slug };
     }
-    return { url, slug };
 }
 class GlobalConfig extends index_1.default {
     constructor() {

package/dist/core/executors/javascript-execution-task.js

@@ -587,7 +587,14 @@ const main = typeof _hooksModule['${fn}'] === 'function'
               console.log('[fcode] variables.delete removed ' + key + ' from variables.local.env (local run).');
             }
           };
-        })()
+        })(),
+        sendMail: async ({ to, subject, text, html } = {}) => {
+          // No manager locally: log the email contents instead of sending, so
+          // devs can see exactly what would be delivered when run in the cloud.
+          console.log('[fcode] sendMail (local run) — not sent, logging contents below:');
+          console.log(JSON.stringify({ to, subject, text, html }, null, 2));
+          return { messageId: 'local-run', accepted: [].concat(to || []), rejected: [] };
+        }
       };
       ${Object.entries(this.getVariablesObject())
                 .map(([key, value]) => `process.env['${key}'] = process.env['${key}'] ?? ${JSON.stringify(value)}`)

package/dist/env.d.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+/**
+ * Validated environment schema for the fcode CLI. This is the single source of truth
+ * for the environment variables the CLI reads — add new vars here.
+ *
+ * Unlike the long-running services (storage-api, ai), a CLI reads config lazily and
+ * different commands need different vars, so there is currently NO universally required
+ * variable: every entry is optional or carries a default that preserves prior behavior.
+ * The fail-fast (❌ + exit 1) path is kept for parity with the services and so that a
+ * genuinely-required var added later fails at process start listing every problem.
+ */
+export declare const envSchema: z.ZodObject<{
+    FCODE_CLOUD_URL: z.ZodDefault<z.ZodString>;
+    FCODE_AUTH_URL: z.ZodOptional<z.ZodString>;
+    FCODE_CLIENT_ID: z.ZodDefault<z.ZodString>;
+    FCODE_CONFIG_PATH: z.ZodOptional<z.ZodString>;
+    IGNORE_WORKSPACE_NOT_EMPTY: z.ZodOptional<z.ZodEnum<{
+        true: "true";
+        false: "false";
+    }>>;
+    FCODE_DISABLE_UPDATE_NOTIFIER: z.ZodOptional<z.ZodEnum<{
+        true: "true";
+        false: "false";
+    }>>;
+    SILENT_MODE: z.ZodOptional<z.ZodEnum<{
+        true: "true";
+        false: "false";
+    }>>;
+    CLI_UX_SKIP_TTY_CHECK: z.ZodOptional<z.ZodString>;
+    YC_COMMAND: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const env: {
+    FCODE_CLOUD_URL: string;
+    FCODE_CLIENT_ID: string;
+    FCODE_AUTH_URL?: string | undefined;
+    FCODE_CONFIG_PATH?: string | undefined;
+    IGNORE_WORKSPACE_NOT_EMPTY?: "true" | "false" | undefined;
+    FCODE_DISABLE_UPDATE_NOTIFIER?: "true" | "false" | undefined;
+    SILENT_MODE?: "true" | "false" | undefined;
+    CLI_UX_SKIP_TTY_CHECK?: string | undefined;
+    YC_COMMAND?: string | undefined;
+};
+export default env;

package/dist/env.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.env = exports.envSchema = void 0;
+const zod_1 = require("zod");
+/**
+ * Validated environment schema for the fcode CLI. This is the single source of truth
+ * for the environment variables the CLI reads — add new vars here.
+ *
+ * Unlike the long-running services (storage-api, ai), a CLI reads config lazily and
+ * different commands need different vars, so there is currently NO universally required
+ * variable: every entry is optional or carries a default that preserves prior behavior.
+ * The fail-fast (❌ + exit 1) path is kept for parity with the services and so that a
+ * genuinely-required var added later fails at process start listing every problem.
+ */
+exports.envSchema = zod_1.z.object({
+    // --- Cloud / auth endpoints ---
+    FCODE_CLOUD_URL: zod_1.z.string().min(1).default('https://code.factorial.dev/platform'),
+    FCODE_AUTH_URL: zod_1.z.string().min(1).optional(),
+    FCODE_CLIENT_ID: zod_1.z.string().min(1).default('cli'),
+    // --- Local config location (defaults to os.homedir() at the call site) ---
+    FCODE_CONFIG_PATH: zod_1.z.string().min(1).optional(),
+    // --- Behavior flags (compared as the strings 'true' / 'false' at the call sites) ---
+    IGNORE_WORKSPACE_NOT_EMPTY: zod_1.z.enum(['true', 'false']).optional(),
+    FCODE_DISABLE_UPDATE_NOTIFIER: zod_1.z.enum(['true', 'false']).optional(),
+    SILENT_MODE: zod_1.z.enum(['true', 'false']).optional(),
+    CLI_UX_SKIP_TTY_CHECK: zod_1.z.string().min(1).optional(),
+    // --- Debug tooling ---
+    YC_COMMAND: zod_1.z.string().min(1).optional(),
+});
+/** Treat empty strings (e.g. an unset shell/dotenv var rendered as "") as missing. */
+const raw = Object.fromEntries(Object.entries(process.env).filter(([, value]) => value !== ''));
+/**
+ * Skip the hard fail-fast under test runners and when explicitly opted out, so importing
+ * this module never kills a test worker. Real invocations always validate.
+ */
+const skipHardExit = Boolean(process.env.VITEST) || process.env.SKIP_ENV_VALIDATION === 'true';
+const result = exports.envSchema.safeParse(raw);
+let parsed;
+if (result.success) {
+    parsed = result.data;
+}
+else if (skipHardExit) {
+    // No universally-required vars today, so parsing `raw` alone succeeds; this branch stays
+    // for parity with the services if a required var is ever added.
+    parsed = exports.envSchema.parse(raw);
+}
+else {
+    const issues = result.error.issues.map((issue) => `  - ${issue.path.join('.') || '(root)'}: ${issue.message}`).join('\n');
+    process.stderr.write(`❌ Invalid environment variables:\n${issues}\n`);
+    process.exit(1);
+}
+exports.env = parsed;
+exports.default = exports.env;

package/dist/hooks/init/update.js

@@ -20,14 +20,12 @@ const updateNotifier = async function ({ config, id }) {
             await globalConfig.set('versionCheckTime', now);
             if (config.version !== lastestVersion) {
                 console.log(`
-        ${color_1.default.cyan(`__     __         _____          _
-        \\ \\   / /        / ____|        | |
-         \\ \\_/ /__ _ __ | |     ___   __| | ___
-          \\   / _ \\ '_ \\| |    / _ \\ / _\` |/ _ \\
-           | |  __/ |_) | |___| (_) | (_| |  __/
-           |_|\\___| .__/ \\_____\\___/ \\__,_|\\___|
-                  | |
-                  |_|`)}
+        ${color_1.default.cyan(` ______         _             _       _  _____          _
+        |  ____|       | |           (_)     | |/ ____|        | |
+        | |__ __ _  ___| |_ ___  _ __ _  __ _| | |     ___   __| | ___
+        |  __/ _\` |/ __| __/ _ \\| '__| |/ _\` | | |    / _ \\ / _\` |/ _ \\
+        | | | (_| | (__| || (_) | |  | | (_| | | |___| (_) | (_| |  __/
+        |_|  \\__,_|\\___|\\__\\___/|_|  |_|\\__,_|_|\\_____\\___/ \\__,_|\\___|`)}
 
         Update available ${color_1.default.red(config.version)} → ${color_1.default.greenBright(lastestVersion)}
         Run ${color_1.default.bold('`npm i -g @factorialco/fcode-cli`')} to update

package/dist/runtime/libs/python/fcode/context.py

@@ -90,6 +90,25 @@ class FcodeGlobal:
         self.variables = variables
         self.processes = Processes()
 
+    def send_mail(self, to=None, subject=None, text=None, html=None):
+        # No manager locally: log the email contents instead of sending, so devs
+        # can see exactly what would be delivered when run in the cloud.
+        import json
+        import logging
+
+        logger = logging.getLogger("fcode_logger")
+        logger.info(
+            "[fcode] send_mail (local run) — not sent, logging contents below:"
+        )
+        logger.info(
+            json.dumps(
+                {"to": to, "subject": subject, "text": text, "html": html},
+                indent=2,
+            )
+        )
+        accepted = to if isinstance(to, list) else ([to] if to else [])
+        return {"messageId": "local-run", "accepted": accepted, "rejected": []}
+
     def import_module(self, module_name, version=None):
         module_path = module_name
         if version:

package/dist/services/auth-service.js

@@ -99,7 +99,7 @@ const AuthService = {
                 client_id: this.clientId,
                 refresh_token: authInfo.token.refresh_token,
             });
-            await (0, node_fetch_1.default)(`${url}/logout`, {
+            await (0, node_fetch_1.default)(`${authInfo.authUrl}${AUTH_URL_PATH}/logout`, {
                 body: body.toString(),
                 headers: {
                     Authorization: `Bearer ${authInfo.token.access_token}`,

package/dist/utils/url-utils.d.ts

@@ -1,2 +1,4 @@
-export declare function buildAuthUrl(url: string): string;
+export declare function toOrigin(input: string): string;
+export declare function buildCloudUrl(input: string): string;
+export declare function buildAuthUrl(input: string): string;
 export declare function isDefaultAuthUrl(authUrl: string, baseUrl: string): boolean;

package/dist/utils/url-utils.js

@@ -1,9 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.toOrigin = toOrigin;
+exports.buildCloudUrl = buildCloudUrl;
 exports.buildAuthUrl = buildAuthUrl;
 exports.isDefaultAuthUrl = isDefaultAuthUrl;
-function buildAuthUrl(url) {
-    return process.env.FCODE_AUTH_URL || new URL(url).origin + '/auth/realms/fcode';
+const PLATFORM_PATH = '/platform';
+function toUrl(input) {
+    const withScheme = /^[a-z]+:\/\//i.test(input) ? input : `https://${input}`;
+    return new URL(withScheme);
+}
+function toOrigin(input) {
+    return toUrl(input).origin;
+}
+function buildCloudUrl(input) {
+    const url = toUrl(input);
+    const path = url.pathname.replace(/\/+$/, '');
+    if (path !== '' && path !== PLATFORM_PATH) {
+        throw new Error(`Invalid Factorial Code URL '${input}'. Provide a host (ie: code.factorialhr.com) or a ${PLATFORM_PATH} URL (ie: https://code.factorialhr.com${PLATFORM_PATH}).`);
+    }
+    return url.origin + PLATFORM_PATH;
+}
+function buildAuthUrl(input) {
+    return process.env.FCODE_AUTH_URL || toOrigin(input) + '/auth/realms/fcode';
 }
 function isDefaultAuthUrl(authUrl, baseUrl) {
     return authUrl === buildAuthUrl(baseUrl);

package/oclif.manifest.json

@@ -141,16 +141,16 @@
       "flags": {
         "url": {
           "char": "u",
-          "description": "Factorial Code Cloud endpoint",
+          "description": "Factorial Code Cloud endpoint (host or full /platform URL, ie: code.factorialhr.com)",
           "name": "url",
-          "default": "https://code.factorial.dev/platform",
+          "default": "https://code.factorialhr.com/platform",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "authUrl": {
           "char": "a",
-          "description": "Factorial Code Auth endpoint (including realm, ie: https://code.factorial.dev/auth/realms/fcode)). Only needed if auth domain is different than used cloud endpoint",
+          "description": "Factorial Code Auth endpoint (including realm, ie: https://code.factorialhr.com/auth/realms/fcode)). Only needed if auth domain is different than used cloud endpoint",
           "name": "authUrl",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -229,9 +229,9 @@
       "flags": {
         "url": {
           "char": "u",
-          "description": "Factorial Code Cloud endpoint",
+          "description": "Factorial Code Cloud endpoint (host or full /platform URL, ie: code.factorialhr.com)",
           "name": "url",
-          "default": "https://code.factorial.dev/platform",
+          "default": "https://code.factorialhr.com/platform",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
@@ -1779,5 +1779,5 @@
       ]
     }
   },
-  "version": "1.1.0"
+  "version": "1.2.0"
 }

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@factorialco/fcode-cli",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "packageManager": "pnpm@11.7.0",
   "description": "Factorial Code Command Line Interface",
-  "homepage": "https://code.factorial.dev/docs/cli/",
+  "homepage": "https://code.factorialhr.com/docs/cli/",
   "author": "Factorial Code Developers <factorial-code@factorial.dev>",
   "license": "See LICENSE file",
   "keywords": [
@@ -40,7 +40,8 @@
     "open": "^8.4.2",
     "openid-client": "^5.6.5",
     "string-width": "^4.2.3",
-    "strip-comments": "^2.0.1"
+    "strip-comments": "^2.0.1",
+    "zod": "^4.4.3"
   },
   "peerDependencies": {
     "graphql-request": "^7.4.0",