@factorialco/fcode-cli 3.2.0 → 3.4.0

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

@@ -33,6 +33,24 @@ const TEAM_VERSION_ALIAS_FIELDS = `
   createdAt
   updatedAt
 `;
+// What a list query adds to know a deleted resource a workspace version still contains. Asked
+// for together with `includeDeleted`, and dropped as one when the api predates them.
+const DELETION_FIELDS = `
+  deletedAt
+  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 = `
@@ -42,6 +60,7 @@ const PROCESS_FIELDS = `
   description
   tags
   resolvingTeamSlug
+  lifecycleRole
   script {
     parametersSchema
     sourceCode
@@ -78,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
     }
@@ -154,24 +203,35 @@ class FcodeGraphQLClient {
         const message = typeof error?.message === 'string' ? error.message : '';
         return NETWORK_ERROR_CODES.some((code) => message.includes(code)) || message.includes('fetch failed');
     }
-    allProcesses() {
+    /**
+     * Every process of the workspace, the deleted ones a workspace version still contains included:
+     * they are pulled read-only with their versions, so the local copy keeps what the versions run.
+     * An api that predates deleted-marked processes rejects the query over the unknown field, and
+     * the fallback lists the live ones as it always did.
+     */
+    allProcesses(includeDeleted = true) {
         return this.client
             .request((0, graphql_request_1.gql) `
-          query processes($first: Int!, $after: String) {
-            processes(first: $first, after: $after) {
+          query processes($filter: ProcessesFilter, $first: Int!, $after: String) {
+            processes(filter: $filter, first: $first, after: $after) {
               edges {
                 node {
                   ${PROCESS_FIELDS}
+                  ${includeDeleted ? DELETION_FIELDS : ''}
                 }
               }
             }
           }
         `, {
+            filter: includeDeleted ? { includeDeleted: true } : null,
             after: null,
             first: 200,
         })
             .then(({ processes: { edges } }) => edges.map(({ node: process }) => this.mapProcess(process)))
             .catch((error) => {
+            if (includeDeleted && this.isUndefinedDeletionFieldError(error)) {
+                return this.allProcesses(false);
+            }
             return Promise.reject(this.cleanError(error));
         });
     }
@@ -217,11 +277,12 @@ class FcodeGraphQLClient {
             return Promise.reject(this.cleanError(error));
         });
     }
-    allScriptLibraries() {
+    /** Same deleted-inclusive listing, and the same fallback, as {@link allProcesses}. */
+    allScriptLibraries(includeDeleted = true) {
         return this.client
             .request((0, graphql_request_1.gql) `
-          query scriptLibraries($first: Int!, $after: String) {
-            scriptLibraries(first: $first, after: $after) {
+          query scriptLibraries($filter: ScriptLibrariesFilter, $first: Int!, $after: String) {
+            scriptLibraries(filter: $filter, first: $first, after: $after) {
               edges {
                 node {
                   id
@@ -229,16 +290,21 @@ class FcodeGraphQLClient {
                   sourceCode
                   programmingLanguage
                   resolvingTeamSlug
+                  ${includeDeleted ? DELETION_FIELDS : ''}
                 }
               }
             }
           }
         `, {
+            filter: includeDeleted ? { includeDeleted: true } : null,
             after: null,
             first: 200,
         })
-            .then(({ scriptLibraries: { edges } }) => edges.map(({ node: { id, name, programmingLanguage, sourceCode, resolvingTeamSlug } }) => new types_1.ScriptLibrary(id, name, sourceCode || '', programmingLanguage, this.inheritedTeam(resolvingTeamSlug))))
+            .then(({ scriptLibraries: { edges } }) => edges.map(({ node: { id, name, programmingLanguage, sourceCode, resolvingTeamSlug, deletedAt, retainingVersionTags } }) => new types_1.ScriptLibrary(id, name, sourceCode || '', programmingLanguage, this.inheritedTeam(resolvingTeamSlug), this.deletionOf(deletedAt, retainingVersionTags))))
             .catch((error) => {
+            if (includeDeleted && this.isUndefinedDeletionFieldError(error)) {
+                return this.allScriptLibraries(false);
+            }
             return Promise.reject(this.cleanError(error));
         });
     }
@@ -325,40 +391,16 @@ class FcodeGraphQLClient {
      * kept twice here — an override is layered over the parent's file key by key, so the parent's
      * keys are still what the ones it does not mention resolve to.
      */
-    async allLocales() {
-        const pageSize = 200;
-        const locales = [];
-        let after = null;
+    async allLocales(includeDeleted = true) {
+        let locales;
         try {
-            do {
-                const { locales: { edges, pageInfo }, } = await this.client.request((0, graphql_request_1.gql) `
-            query locales($first: Int!, $after: String) {
-              locales(first: $first, after: $after) {
-                edges {
-                  node {
-                    id
-                    locale
-                    content
-                    resolvingTeamSlug
-                  }
-                }
-                pageInfo {
-                  hasNextPage
-                  endCursor
-                }
-              }
-            }
-          `, {
-                    after,
-                    first: pageSize,
-                });
-                for (const { node: { id, locale, content, resolvingTeamSlug }, } of edges) {
-                    locales.push(new types_1.Locale(id, locale, content, this.inheritedTeam(resolvingTeamSlug)));
-                }
-                after = pageInfo?.hasNextPage ? pageInfo.endCursor : null;
-            } while (after);
+            locales = await this.fetchLocales(includeDeleted);
         }
         catch (error) {
+            // Same fallback as allProcesses: an api that predates deleted-marked locales lists the live ones.
+            if (includeDeleted && this.isUndefinedDeletionFieldError(error)) {
+                return this.allLocales(false);
+            }
             return Promise.reject(this.cleanError(error));
         }
         // The cloud team's parent order is the inheritance precedence the merge must replicate; the
@@ -368,6 +410,41 @@ class FcodeGraphQLClient {
         (0, locale_merger_1.assertLocaleFilesCanCoexist)(merged);
         return merged;
     }
+    async fetchLocales(includeDeleted) {
+        const pageSize = 200;
+        const locales = [];
+        let after = null;
+        do {
+            const { locales: { edges, pageInfo }, } = await this.client.request((0, graphql_request_1.gql) `
+          query locales($filter: LocalesFilter, $first: Int!, $after: String) {
+            locales(filter: $filter, first: $first, after: $after) {
+              edges {
+                node {
+                  id
+                  locale
+                  content
+                  resolvingTeamSlug
+                  ${includeDeleted ? DELETION_FIELDS : ''}
+                }
+              }
+              pageInfo {
+                hasNextPage
+                endCursor
+              }
+            }
+          }
+        `, {
+                filter: includeDeleted ? { includeDeleted: true } : null,
+                after,
+                first: pageSize,
+            });
+            for (const { node: { id, locale, content, resolvingTeamSlug, deletedAt, retainingVersionTags }, } of edges) {
+                locales.push(new types_1.Locale(id, locale, content, this.inheritedTeam(resolvingTeamSlug), this.deletionOf(deletedAt, retainingVersionTags)));
+            }
+            after = pageInfo?.hasNextPage ? pageInfo.endCursor : null;
+        } while (after);
+        return locales;
+    }
     pushLocale(locale) {
         return this.client
             .request((0, graphql_request_1.gql) `
@@ -417,12 +494,14 @@ class FcodeGraphQLClient {
           mutation deleteLocale($locale: String!) {
             deleteLocale(locale: $locale) {
               id
+              deletedAt
+              retainingVersionTags
             }
           }
         `, {
             locale,
         })
-            .then(() => undefined)
+            .then((data) => data.deleteLocale)
             .catch((error) => {
             return Promise.reject(this.cleanError(error));
         });
@@ -431,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;
@@ -531,11 +624,14 @@ class FcodeGraphQLClient {
           mutation deleteProcess($id: ID!) {
             deleteProcess(id: $id) {
               id
+              deletedAt
+              retainingVersionTags
             }
           }
         `, {
             id,
         })
+            .then((data) => data.deleteProcess)
             .catch((error) => {
             return Promise.reject(this.cleanError(error));
         });
@@ -590,11 +686,14 @@ class FcodeGraphQLClient {
           mutation deleteScriptLibrary($id: ID!) {
             deleteScriptLibrary(id: $id) {
               id
+              deletedAt
+              retainingVersionTags
             }
           }
         `, {
             id,
         })
+            .then((data) => data.deleteScriptLibrary)
             .catch((error) => {
             return Promise.reject(this.cleanError(error));
         });
@@ -725,6 +824,12 @@ class FcodeGraphQLClient {
     inheritedTeam(resolvingTeamSlug) {
         return resolvingTeamSlug && resolvingTeamSlug !== this.teamSlug ? resolvingTeamSlug : undefined;
     }
+    deletionOf(deletedAt, retainingVersionTags) {
+        return deletedAt ? { deletedAt, retainingVersionTags: retainingVersionTags ?? [] } : undefined;
+    }
+    isUndefinedDeletionFieldError(error) {
+        return DELETION_QUERY_FIELDS.some((field) => this.isUndefinedFieldError(error, field));
+    }
     /**
      * The public mode and the default header name are left out, so a public webhook — or one
      * using the default header — keeps the metadata.json it already had on disk.
@@ -747,7 +852,112 @@ class FcodeGraphQLClient {
         }
         return webhook;
     }
-    mapProcess({ id, slug, name, description, tags, script, readme, manifest, settings, triggers, resolvingTeamSlug }) {
+    /**
+     * 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 };
         });
@@ -783,7 +993,15 @@ class FcodeGraphQLClient {
                 metadata.uiTrigger.awaitResult = true;
             }
         }
-        return new types_1.Process(id, slug, script, readme, { dependencies }, settings, metadata, this.inheritedTeam(resolvingTeamSlug));
+        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/dist/services/skills-installer.js

@@ -3,9 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.installSkillsAt = installSkillsAt;
 exports.skillsInstalledAt = skillsInstalledAt;
 exports.linkSkillsInto = linkSkillsInto;
-const node_child_process_1 = require("node:child_process");
 const fs = require("fs-extra");
 const path = require("node:path");
+const child_process_1 = require("../utils/child-process");
 const cli_1 = require("../utils/cli");
 // Skill sources installed on clone. `release-sdk` in factorial-api-sdks is a
 // maintainer-only skill, so we pick `factorial-api-sdks` explicitly there.
@@ -24,7 +24,7 @@ async function installSkills(repo, skills, cwd) {
     // the skills CLI defaults: project scope (no -g), symlinked (no --copy).
     const skillsArgs = ['--yes', 'skills', 'add', repo, '-s', skills, '-y'];
     await new Promise((resolve) => {
-        const child = (0, node_child_process_1.spawn)('npx', skillsArgs, { cwd, stdio: 'inherit' });
+        const child = (0, child_process_1.spawnCommand)('npx', skillsArgs, { cwd, stdio: 'inherit' });
         child.on('error', () => {
             // npx not available (or failed to launch) — don't fail the clone, just tell the user how to do it.
             cli_1.default.log("\n⚠️  Couldn't run npx automatically (is Node.js / npx installed?).");

package/dist/services/version-pull-reporter.d.ts

@@ -0,0 +1,20 @@
+/** One resource's version pull, named so a failure can say which resource it belongs to. */
+export interface VersionPull {
+    slug: string;
+    failure: Promise<string | undefined>;
+}
+/**
+ * Starts tracking one resource's version pull.
+ *
+ * The outcome is captured here rather than where it is reported, because the pulls are started in
+ * a loop that waits between them: a rejection would otherwise sit unhandled until the loop ends.
+ */
+export declare function trackVersionPull(slug: string, done: Promise<void>): VersionPull;
+/**
+ * Awaits every version pull and reports the ones that failed.
+ *
+ * The pulls run in parallel and must not take each other down — one resource the cloud refuses is
+ * not a reason to abandon the rest — but a swallowed rejection leaves `versions/` silently empty,
+ * which reads exactly like a resource that has no versions. This is what tells the two apart.
+ */
+export declare function reportFailedVersionPulls(pulls: Array<VersionPull>, resourceName: string): Promise<void>;

package/dist/services/version-pull-reporter.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trackVersionPull = trackVersionPull;
+exports.reportFailedVersionPulls = reportFailedVersionPulls;
+const color_1 = require("@oclif/color");
+const cli_1 = require("../utils/cli");
+/**
+ * Starts tracking one resource's version pull.
+ *
+ * The outcome is captured here rather than where it is reported, because the pulls are started in
+ * a loop that waits between them: a rejection would otherwise sit unhandled until the loop ends.
+ */
+function trackVersionPull(slug, done) {
+    return {
+        slug,
+        failure: done.then(() => undefined, (reason) => (reason instanceof Error ? reason.message : String(reason))),
+    };
+}
+/**
+ * Awaits every version pull and reports the ones that failed.
+ *
+ * The pulls run in parallel and must not take each other down — one resource the cloud refuses is
+ * not a reason to abandon the rest — but a swallowed rejection leaves `versions/` silently empty,
+ * which reads exactly like a resource that has no versions. This is what tells the two apart.
+ */
+async function reportFailedVersionPulls(pulls, resourceName) {
+    for (const { slug, failure } of pulls) {
+        const reason = await failure;
+        if (reason !== undefined) {
+            cli_1.default.log(color_1.default.yellow(`⚠️  could not pull the versions of ${resourceName} '${slug}': ${reason}`));
+        }
+    }
+}

package/dist/utils/child-process.d.ts

@@ -0,0 +1,26 @@
+import { type ChildProcess, type SpawnOptions } from 'node:child_process';
+export type Platform = NodeJS.Platform;
+export interface CommandLine {
+    command: string;
+    args: string[];
+    shell: boolean;
+}
+/**
+ * How to invoke a package-manager executable (`npm`, `npx`, a `node_modules/.bin` shim) on `platform`.
+ *
+ * On Windows those are `.cmd` batch files, which Node refuses to spawn without a shell, so the
+ * command line goes through `cmd.exe` with every part quoted for it.
+ */
+export declare function commandLineFor(command: string, args: string[], platform?: Platform): CommandLine;
+export declare function spawnCommand(command: string, args: string[], options?: SpawnOptions): ChildProcess;
+/** The `node_modules/.bin` shim `name` resolves to on `platform`. */
+export declare function binShimPath(nodeModulesPath: string, name: string, platform?: Platform): string;
+/** The executable `name` a Python virtual environment at `envPath` exposes on `platform`. */
+export declare function venvExecutablePath(envPath: string, name: string, platform?: Platform): string;
+/** The Python interpreter of the virtual environment at `envPath`; Windows venvs ship no `python3` alias. */
+export declare function venvPythonPath(envPath: string, platform?: Platform): string;
+/**
+ * An environment for a process run locally: the entries given plus, on Windows, the system
+ * variables Node and Python cannot start without (`SYSTEMROOT`, `TEMP`, ...).
+ */
+export declare function childEnv(entries: Record<string, string | undefined>, platform?: Platform, hostEnv?: NodeJS.ProcessEnv): Record<string, string>;

package/dist/utils/child-process.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.commandLineFor = commandLineFor;
+exports.spawnCommand = spawnCommand;
+exports.binShimPath = binShimPath;
+exports.venvExecutablePath = venvExecutablePath;
+exports.venvPythonPath = venvPythonPath;
+exports.childEnv = childEnv;
+const node_child_process_1 = require("node:child_process");
+const path = require("node:path");
+const quoteForCmd = (part) => (/[\s"]/.test(part) ? `"${part.replace(/"/g, '""')}"` : part);
+/**
+ * How to invoke a package-manager executable (`npm`, `npx`, a `node_modules/.bin` shim) on `platform`.
+ *
+ * On Windows those are `.cmd` batch files, which Node refuses to spawn without a shell, so the
+ * command line goes through `cmd.exe` with every part quoted for it.
+ */
+function commandLineFor(command, args, platform = process.platform) {
+    if (platform !== 'win32') {
+        return { command, args, shell: false };
+    }
+    return { command: quoteForCmd(command), args: args.map(quoteForCmd), shell: true };
+}
+function spawnCommand(command, args, options = {}) {
+    const line = commandLineFor(command, args);
+    return (0, node_child_process_1.spawn)(line.command, line.args, { ...options, shell: line.shell });
+}
+/** The `node_modules/.bin` shim `name` resolves to on `platform`. */
+function binShimPath(nodeModulesPath, name, platform = process.platform) {
+    return path.join(nodeModulesPath, '.bin', platform === 'win32' ? `${name}.cmd` : name);
+}
+/** The executable `name` a Python virtual environment at `envPath` exposes on `platform`. */
+function venvExecutablePath(envPath, name, platform = process.platform) {
+    return platform === 'win32' ? path.join(envPath, 'Scripts', `${name}.exe`) : path.join(envPath, 'bin', name);
+}
+/** The Python interpreter of the virtual environment at `envPath`; Windows venvs ship no `python3` alias. */
+function venvPythonPath(envPath, platform = process.platform) {
+    return venvExecutablePath(envPath, platform === 'win32' ? 'python' : 'python3', platform);
+}
+const WINDOWS_SYSTEM_ENV_KEYS = ['SYSTEMROOT', 'SYSTEMDRIVE', 'WINDIR', 'COMSPEC', 'PATHEXT', 'TEMP', 'TMP', 'USERPROFILE', 'APPDATA', 'LOCALAPPDATA'];
+/**
+ * An environment for a process run locally: the entries given plus, on Windows, the system
+ * variables Node and Python cannot start without (`SYSTEMROOT`, `TEMP`, ...).
+ */
+function childEnv(entries, platform = process.platform, hostEnv = process.env) {
+    const env = {};
+    if (platform === 'win32') {
+        for (const [key, value] of Object.entries(hostEnv)) {
+            if (value !== undefined && WINDOWS_SYSTEM_ENV_KEYS.includes(key.toUpperCase())) {
+                env[key] = value;
+            }
+        }
+    }
+    for (const [key, value] of Object.entries(entries)) {
+        if (value !== undefined) {
+            env[key] = value;
+        }
+    }
+    return env;
+}

package/oclif.manifest.json

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

package/package.json

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