@factorialco/fcode-cli 2.3.0 → 3.0.0

package/dist/services/locale-resolver.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.flattenTranslations = flattenTranslations;
+exports.localeFallbackChain = localeFallbackChain;
 exports.resolveLocalTranslations = resolveLocalTranslations;
 const fs = require("fs-extra");
 const path = require("node:path");
@@ -8,6 +9,7 @@ const yaml_1 = require("yaml");
 const cli_1 = require("../utils/cli");
 const color_1 = require("@oclif/color");
 const types_1 = require("../core/types");
+const settings_1 = require("../repositories/settings");
 const I18N_DIRECTORY = 'i18n';
 const YAML_EXTENSION = '.yaml';
 const KEY_SEPARATOR = '.';
@@ -71,8 +73,9 @@ function readLocale(workspaceDir, locale) {
 }
 function chosenPrimaryLocaleOf(workspaceDir) {
     try {
-        const team = fs.readJsonSync(path.join(workspaceDir, 'team.json'));
-        return typeof team?.primaryLocale === 'string' && team.primaryLocale.length > 0 ? team.primaryLocale : undefined;
+        (0, settings_1.migrateLegacySettingsFile)(workspaceDir);
+        const settings = fs.readJsonSync(path.join(workspaceDir, settings_1.SETTINGS_FILENAME));
+        return typeof settings?.primaryLocale === 'string' && settings.primaryLocale.length > 0 ? settings.primaryLocale : undefined;
     }
     catch {
         return undefined;
@@ -95,7 +98,7 @@ function availableLocales(workspaceDir) {
     return [...new Set(localeFileSlugs(workspaceDir).map((slug) => identifierOf(slug)))].sort();
 }
 /**
- * The workspace's primary locale: the one chosen in `team.json`, or its first locale when none is
+ * The workspace's primary locale: the one chosen in `settings.json`, or its first locale when none is
  * chosen — or when the chosen one has no file anymore, which would otherwise resolve zero keys.
  * Mirrors the platform's `PrimaryLocale.resolve`, so a local run and the cloud agree on which
  * locale a process without an explicit one resolves against.
@@ -105,16 +108,68 @@ function primaryLocaleOf(workspaceDir) {
     const chosen = chosenPrimaryLocaleOf(workspaceDir);
     return chosen && available.includes(chosen) ? chosen : available[0];
 }
+/**
+ * The available locale a candidate opens: the one named exactly, or — only when no name matches —
+ * the one that differs from it in case alone, alphabetically first if there are several. Locale
+ * identifiers are case-sensitive, so `pt-BR` and `pt-br` are two files and each keeps answering its
+ * own name; ignoring case only ever rescues a lookup that would otherwise find nothing.
+ */
+function matchingLocale(candidate, available) {
+    if (available.includes(candidate)) {
+        return candidate;
+    }
+    return available.filter((locale) => locale.toLowerCase() === candidate.toLowerCase()).sort()[0];
+}
+/**
+ * The locale files that answer a requested identifier, lowest precedence first. Mirrors the
+ * platform's `LocaleFallbackChain`, so a local run and the cloud resolve the same text.
+ *
+ * A viewer's locale is usually a regional variant (`en-gb`, `pt-BR`) while a workspace usually
+ * publishes plain languages, so the request degrades one segment at a time — split on `-` or `_`,
+ * without parsing a language tag, since any short slug is a legal identifier here — and every step
+ * that matches stays in the chain: a variant file translates the keys that differ and leaves the
+ * rest to the language it came from.
+ */
+function localeFallbackChain(requested, primary, available) {
+    const chain = [];
+    const add = (candidate) => {
+        const match = candidate ? matchingLocale(candidate, available) : undefined;
+        if (match && !chain.includes(match)) {
+            chain.push(match);
+        }
+    };
+    add(primary);
+    const candidates = [];
+    let candidate = requested?.trim();
+    while (candidate) {
+        candidates.unshift(candidate);
+        const lastSeparator = Math.max(candidate.lastIndexOf('-'), candidate.lastIndexOf('_'));
+        candidate = lastSeparator > 0 ? candidate.slice(0, lastSeparator) : undefined;
+    }
+    for (const shorterOrExact of candidates)
+        add(shorterOrExact);
+    return chain;
+}
 /**
  * @param requestedLocale the locale to run with, or undefined to use the workspace's primary
- * @returns the locale actually used and its flat translations, with the primary locale underneath
+ * @returns the locale actually used and its flat translations, with the primary locale — and any
+ * shorter form of the requested one the workspace publishes — layered underneath, plus each
+ * locale's own map (inherited file layered under its own, but NOT merged over the primary) so a
+ * call naming a locale (`fcode.i18n(key, args, { locale })`) resolves like the cloud's `by_locale`:
+ * key by key in the requested locale first, falling back to the merged translations
  */
 function resolveLocalTranslations(requestedLocale, workspaceDir = process.cwd()) {
     const primary = primaryLocaleOf(workspaceDir);
     const locale = requestedLocale || primary;
+    const byLocale = Object.fromEntries(availableLocales(workspaceDir).map((slug) => [slug, readLocale(workspaceDir, slug)]));
     if (!locale) {
-        return { locale: undefined, translations: {} };
+        return { locale: undefined, translations: {}, byLocale };
+    }
+    // `byLocale` already holds every locale's own file, so the merged map — the fallback chain
+    // layered lowest precedence first — is derived from it rather than read from disk a second time.
+    const translations = {};
+    for (const layer of localeFallbackChain(requestedLocale, primary, Object.keys(byLocale))) {
+        Object.assign(translations, byLocale[layer]);
     }
-    const fallback = primary && primary !== locale ? readLocale(workspaceDir, primary) : {};
-    return { locale, translations: { ...fallback, ...readLocale(workspaceDir, locale) } };
+    return { locale, translations, byLocale };
 }

package/dist/services/resource-differ.d.ts

@@ -0,0 +1,60 @@
+import { Locale, Process, ProgrammingLanguageManifest, Resource, ResourceStatus, ScriptLibrary, Variable } from '../core/types';
+import { PseudoFile } from '../utils/diff';
+/** Stands in for a variable's value wherever one side declares it sensitive, so no secret is ever printed. */
+export declare const SENSITIVE_PLACEHOLDER = "<sensitive value hidden>";
+export declare const VARIABLES_DIFF_PATH = "variables.env";
+/** What a workspace inherits is regenerated on pull into its own file, which the parent owns. */
+export declare const INHERITED_VARIABLES_DIFF_PATH = "variables.inherited.env";
+export declare const SETTINGS_DIFF_PATH = "settings.json";
+/**
+ * A resource as both sides hold it, kept whole. `ResourceMerger.mergeStatus` collapses the two into
+ * one object and loses the remote body, which is exactly what a diff needs.
+ */
+export type ResourcePair<R extends Resource> = {
+    slug: string;
+    remote?: R;
+    local?: R;
+    status: ResourceStatus;
+};
+/** A set of pseudo-files presented together under one heading (usually one resource). */
+export type DiffSection = {
+    label: string;
+    files: PseudoFile[];
+};
+/** Files keyed by the path they are stored at, for one side of a comparison. */
+type SideFiles = Record<string, string>;
+export declare function pairResources<R extends Resource>(remoteResources: Array<R>, localResources: Array<R>, existsMetadata: (slug: string) => Promise<boolean>): Promise<Array<ResourcePair<R>>>;
+/**
+ * The workspace a resource is inherited from, when it is. An overridden variable resolves to
+ * undefined on its local side, which is what makes an override diffable while the parent's copy
+ * stays read-only.
+ */
+export declare function inheritedFrom<R extends Resource>(pair: ResourcePair<R>): string | undefined;
+/** A process as the four files it is stored as, plus its own dependencies file when it scopes them. */
+export declare function processFiles(process: Process): SideFiles;
+export declare function moduleFiles(module: ScriptLibrary): SideFiles;
+export declare function localeFiles(locale: Locale): SideFiles;
+/**
+ * Only the workspace's own dependencies, matching what `contentHash` covers and what the manifest
+ * file holds: the inherited ones live in their own file and belong to a parent.
+ */
+export declare function manifestFiles(manifest: ProgrammingLanguageManifest): SideFiles;
+export declare const processDiffFiles: (pair: ResourcePair<Process>) => Array<PseudoFile>;
+export declare const moduleDiffFiles: (pair: ResourcePair<ScriptLibrary>) => Array<PseudoFile>;
+export declare const localeDiffFiles: (pair: ResourcePair<Locale>) => Array<PseudoFile>;
+export declare const manifestDiffFiles: (pair: ResourcePair<ProgrammingLanguageManifest>) => Array<PseudoFile>;
+/**
+ * Every variable as the .env files they share, rather than one pseudo-file each: that is how they
+ * are stored, and it keeps a rename or a reordering readable as one patch.
+ *
+ * The workspace's own keys and the inherited ones are separate files, because they are separate
+ * files on disk — a drifted inherited variable is a stale `variables.inherited.env` that a pull
+ * regenerates, not something to push. The inherited file only appears when something is inherited.
+ *
+ * A key either side marks sensitive is rendered as a placeholder on both, so a diff never prints a
+ * secret and a value-only change to a sensitive variable shows up as nothing (its status does).
+ */
+export declare function variablesEnvDiffFiles(pairs: Array<ResourcePair<Variable>>): Array<PseudoFile>;
+/** The singleton workspace settings file. Both sides arrive already serialized by `SettingsRepository.toFile`. */
+export declare function settingsDiffFile(remote: Record<string, any> | undefined, local: Record<string, any> | undefined): PseudoFile;
+export {};

package/dist/services/resource-differ.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.manifestDiffFiles = exports.localeDiffFiles = exports.moduleDiffFiles = exports.processDiffFiles = exports.SETTINGS_DIFF_PATH = exports.INHERITED_VARIABLES_DIFF_PATH = exports.VARIABLES_DIFF_PATH = exports.SENSITIVE_PLACEHOLDER = void 0;
+exports.pairResources = pairResources;
+exports.inheritedFrom = inheritedFrom;
+exports.processFiles = processFiles;
+exports.moduleFiles = moduleFiles;
+exports.localeFiles = localeFiles;
+exports.manifestFiles = manifestFiles;
+exports.variablesEnvDiffFiles = variablesEnvDiffFiles;
+exports.settingsDiffFile = settingsDiffFile;
+const resource_merger_1 = require("../core/resource-merger");
+const dependencies_1 = require("../core/utils/dependencies");
+const process_1 = require("../repositories/process");
+const env_utils_1 = require("../utils/env-utils");
+const filenamify_1 = require("../utils/filenamify");
+/** Stands in for a variable's value wherever one side declares it sensitive, so no secret is ever printed. */
+exports.SENSITIVE_PLACEHOLDER = '<sensitive value hidden>';
+exports.VARIABLES_DIFF_PATH = 'variables.env';
+/** What a workspace inherits is regenerated on pull into its own file, which the parent owns. */
+exports.INHERITED_VARIABLES_DIFF_PATH = 'variables.inherited.env';
+exports.SETTINGS_DIFF_PATH = 'settings.json';
+async function pairResources(remoteResources, localResources, existsMetadata) {
+    const pairs = [];
+    const slugs = [...new Set([...localResources, ...remoteResources].map((resource) => resource.slug))];
+    for (const slug of slugs) {
+        const remote = remoteResources.find((resource) => resource.slug === slug);
+        const local = localResources.find((resource) => resource.slug === slug);
+        pairs.push({ slug, remote, local, status: await (0, resource_merger_1.mapResourceStatus)(remote, local, await existsMetadata(slug)) });
+    }
+    return pairs;
+}
+/**
+ * The workspace a resource is inherited from, when it is. An overridden variable resolves to
+ * undefined on its local side, which is what makes an override diffable while the parent's copy
+ * stays read-only.
+ */
+function inheritedFrom(pair) {
+    return (pair.local ?? pair.remote)?.resolvingTeamSlug;
+}
+function mergeSides(remoteFiles, localFiles) {
+    const paths = [...new Set([...Object.keys(remoteFiles), ...Object.keys(localFiles)])].sort();
+    return paths.map((path) => {
+        const file = { path };
+        if (path in remoteFiles) {
+            file.remote = remoteFiles[path];
+        }
+        if (path in localFiles) {
+            file.local = localFiles[path];
+        }
+        return file;
+    });
+}
+function sideFiles(pair, toFiles) {
+    return mergeSides(pair.remote ? toFiles(pair.remote) : {}, pair.local ? toFiles(pair.local) : {});
+}
+/** A process as the four files it is stored as, plus its own dependencies file when it scopes them. */
+function processFiles(process) {
+    const directory = `processes/${(0, filenamify_1.default)(process.slug)}`;
+    const { programmingLanguage } = process.script;
+    const files = {
+        [`${directory}/${(0, process_1.PROCESS_SOURCE_CODE_FILE_NAME)(programmingLanguage)}`]: process.script.sourceCode || '',
+        [`${directory}/README.md`]: process.readme || '',
+        [`${directory}/metadata.json`]: JSON.stringify((0, process_1.buildProcessMetadata)(process), null, 2),
+        [`${directory}/parametersSchema.json`]: JSON.stringify(process.script.parametersSchema ?? {}, null, 2),
+    };
+    if (process.settings?.dependencies?.scopedToProcess) {
+        files[`${directory}/${(0, process_1.PROCESS_DEPENDENCIES_FILE_NAME)(programmingLanguage)}`] = (0, dependencies_1.dependenciesToFile)(programmingLanguage, process.manifest?.dependencies);
+    }
+    return files;
+}
+function moduleFiles(module) {
+    const name = (0, filenamify_1.default)(module.name);
+    const extension = module.programmingLanguage === 'PYTHON' ? 'py' : 'js';
+    return { [`modules/${name}/${name}.${extension}`]: module.sourceCode || '' };
+}
+function localeFiles(locale) {
+    return { [`i18n/${locale.slug}.yaml`]: locale.content || '' };
+}
+/**
+ * Only the workspace's own dependencies, matching what `contentHash` covers and what the manifest
+ * file holds: the inherited ones live in their own file and belong to a parent.
+ */
+function manifestFiles(manifest) {
+    const fileName = manifest.programmingLanguage === 'JAVASCRIPT' ? 'package.json' : 'requirements.txt';
+    return { [`dependencies/${fileName}`]: (0, dependencies_1.dependenciesToFile)(manifest.programmingLanguage, manifest.dependencies) };
+}
+const processDiffFiles = (pair) => sideFiles(pair, processFiles);
+exports.processDiffFiles = processDiffFiles;
+const moduleDiffFiles = (pair) => sideFiles(pair, moduleFiles);
+exports.moduleDiffFiles = moduleDiffFiles;
+const localeDiffFiles = (pair) => sideFiles(pair, localeFiles);
+exports.localeDiffFiles = localeDiffFiles;
+const manifestDiffFiles = (pair) => sideFiles(pair, manifestFiles);
+exports.manifestDiffFiles = manifestDiffFiles;
+function renderVariablesFile(pairs, path, include) {
+    const sensitiveKeys = new Set(pairs.filter((pair) => pair.remote?.isSensitive || pair.local?.isSensitive).map((pair) => pair.slug));
+    const renderSide = (side) => pairs
+        .map(side)
+        .filter((variable) => variable !== undefined && include(variable))
+        .sort((a, b) => a.key.localeCompare(b.key))
+        .map((variable) => `${variable.key}=${sensitiveKeys.has(variable.key) ? exports.SENSITIVE_PLACEHOLDER : (0, env_utils_1.escapeEnvValue)(variable.value || '')}`)
+        .join('\n');
+    return { path, remote: renderSide((pair) => pair.remote), local: renderSide((pair) => pair.local) };
+}
+/**
+ * Every variable as the .env files they share, rather than one pseudo-file each: that is how they
+ * are stored, and it keeps a rename or a reordering readable as one patch.
+ *
+ * The workspace's own keys and the inherited ones are separate files, because they are separate
+ * files on disk — a drifted inherited variable is a stale `variables.inherited.env` that a pull
+ * regenerates, not something to push. The inherited file only appears when something is inherited.
+ *
+ * A key either side marks sensitive is rendered as a placeholder on both, so a diff never prints a
+ * secret and a value-only change to a sensitive variable shows up as nothing (its status does).
+ */
+function variablesEnvDiffFiles(pairs) {
+    const isInherited = (variable) => Boolean(variable.resolvingTeamSlug);
+    const files = [renderVariablesFile(pairs, exports.VARIABLES_DIFF_PATH, (variable) => !isInherited(variable))];
+    if (pairs.some((pair) => (pair.remote && isInherited(pair.remote)) || (pair.local && isInherited(pair.local)))) {
+        files.push(renderVariablesFile(pairs, exports.INHERITED_VARIABLES_DIFF_PATH, isInherited));
+    }
+    return files;
+}
+/** The singleton workspace settings file. Both sides arrive already serialized by `SettingsRepository.toFile`. */
+function settingsDiffFile(remote, local) {
+    const file = { path: exports.SETTINGS_DIFF_PATH };
+    if (remote !== undefined) {
+        file.remote = JSON.stringify(remote, null, 2);
+    }
+    if (local !== undefined) {
+        file.local = JSON.stringify(local, null, 2);
+    }
+    return file;
+}

package/dist/services/skills-installer.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Installs the Factorial Code agent skills into `targetDir`. The skills CLI writes the skills
+ * themselves under `.agents/skills/` and symlinks them from `.claude/skills/`; it only installs
+ * to agents it detects, so `.claude/` is created first to make sure Claude Code is targeted.
+ */
+export declare function installSkillsAt(targetDir: string): Promise<void>;
+export declare function skillsInstalledAt(rootDir: string): boolean;
+/**
+ * Points `targetDir`'s `.claude/skills` at the ones installed in `rootDir`, so a team clone
+ * installs the skills once and every App still resolves them.
+ *
+ * The link is relative, so moving the whole tree keeps it working, and the per-skill symlinks
+ * inside it resolve against the real directory — not against the link — so they stay valid.
+ * Returns false when there is nothing to link to (the install failed, and it is not fatal).
+ */
+export declare function linkSkillsInto(targetDir: string, rootDir: string): boolean;

package/dist/services/skills-installer.js

@@ -0,0 +1,77 @@
+"use strict";
+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 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.
+const SKILLS_SOURCES = [
+    { repo: 'factorialco/factorial-code-skills', skills: '*' },
+    { repo: 'factorialco/factorial-api-sdks', skills: 'factorial-api-sdks' },
+];
+/** Where the skills CLI symlinks the installed skills for Claude Code to find them. */
+const CLAUDE_SKILLS_PATH = path.join('.claude', 'skills');
+function skillsInstallHint(repo, skills) {
+    cli_1.default.log('💡 Install the Factorial Code agent skills later with:');
+    cli_1.default.log(`   npx skills add ${repo} -s '${skills}' -y`);
+}
+async function installSkills(repo, skills, cwd) {
+    // `npx --yes skills add <repo> -s <skills> -y` — non-interactive install with
+    // 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' });
+        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?).");
+            skillsInstallHint(repo, skills);
+            resolve();
+        });
+        child.on('close', (code) => {
+            if (code !== 0) {
+                cli_1.default.log("\n⚠️  Skill installation didn't complete.");
+                skillsInstallHint(repo, skills);
+            }
+            resolve();
+        });
+    });
+}
+/**
+ * Installs the Factorial Code agent skills into `targetDir`. The skills CLI writes the skills
+ * themselves under `.agents/skills/` and symlinks them from `.claude/skills/`; it only installs
+ * to agents it detects, so `.claude/` is created first to make sure Claude Code is targeted.
+ */
+async function installSkillsAt(targetDir) {
+    cli_1.default.log('');
+    fs.ensureDirSync(path.join(targetDir, '.claude'));
+    for (const source of SKILLS_SOURCES) {
+        await installSkills(source.repo, source.skills, targetDir);
+    }
+}
+function skillsInstalledAt(rootDir) {
+    return fs.pathExistsSync(path.join(rootDir, CLAUDE_SKILLS_PATH));
+}
+/**
+ * Points `targetDir`'s `.claude/skills` at the ones installed in `rootDir`, so a team clone
+ * installs the skills once and every App still resolves them.
+ *
+ * The link is relative, so moving the whole tree keeps it working, and the per-skill symlinks
+ * inside it resolve against the real directory — not against the link — so they stay valid.
+ * Returns false when there is nothing to link to (the install failed, and it is not fatal).
+ */
+function linkSkillsInto(targetDir, rootDir) {
+    if (!skillsInstalledAt(rootDir)) {
+        return false;
+    }
+    const link = path.join(targetDir, CLAUDE_SKILLS_PATH);
+    if (fs.pathExistsSync(link) || fs.lstatSync(link, { throwIfNoEntry: false })) {
+        return true;
+    }
+    fs.ensureDirSync(path.dirname(link));
+    fs.symlinkSync(path.relative(path.dirname(link), path.join(rootDir, CLAUDE_SKILLS_PATH)), link, 'dir');
+    return true;
+}

package/dist/services/team-versioning.d.ts

@@ -0,0 +1,16 @@
+import { TeamAliasFileEntry, TeamVersion, TeamVersionAlias, TeamVersionFileEntry, WorkspaceSettings } from '../core/types';
+/**
+ * What a settings:push must do to make the cloud's versions and aliases match settings.json.
+ * Versions are only ever created or deleted (tags are immutable snapshots); aliases are
+ * name->tag pointers, so a changed tag is an upsert of the same name.
+ */
+export interface TeamVersioningSyncPlan {
+    createVersions: TeamVersionFileEntry[];
+    deleteVersions: TeamVersion[];
+    setAliases: TeamAliasFileEntry[];
+    deleteAliases: TeamVersionAlias[];
+}
+export declare function planTeamVersioningSync(settings: WorkspaceSettings, cloudVersions: TeamVersion[], cloudAliases: TeamVersionAlias[]): TeamVersioningSyncPlan;
+export declare function teamVersioningSyncPlanIsEmpty(plan: TeamVersioningSyncPlan): boolean;
+/** Logs the per-entity outcome of publishing a workspace version and returns how many failed. */
+export declare function logTeamVersionManifest(teamVersion: TeamVersion): number;

package/dist/services/team-versioning.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planTeamVersioningSync = planTeamVersioningSync;
+exports.teamVersioningSyncPlanIsEmpty = teamVersioningSyncPlanIsEmpty;
+exports.logTeamVersionManifest = logTeamVersionManifest;
+const color_1 = require("@oclif/color");
+const cli_1 = require("../utils/cli");
+function planTeamVersioningSync(settings, cloudVersions, cloudAliases) {
+    const localVersions = settings.versions ?? [];
+    const localAliases = settings.aliases ?? [];
+    const cloudVersionTags = new Set(cloudVersions.map(({ tag }) => tag));
+    const localVersionTags = new Set(localVersions.map(({ tag }) => tag));
+    const cloudAliasesByName = new Map(cloudAliases.map((alias) => [alias.name, alias]));
+    const localAliasNames = new Set(localAliases.map(({ name }) => name));
+    return {
+        createVersions: localVersions.filter(({ tag }) => !cloudVersionTags.has(tag)),
+        deleteVersions: cloudVersions.filter(({ tag }) => !localVersionTags.has(tag)),
+        setAliases: localAliases.filter(({ name, tag }) => cloudAliasesByName.get(name)?.tag !== tag),
+        deleteAliases: cloudAliases.filter(({ name }) => !localAliasNames.has(name)),
+    };
+}
+function teamVersioningSyncPlanIsEmpty(plan) {
+    return (plan.createVersions.length === 0 &&
+        plan.deleteVersions.length === 0 &&
+        plan.setAliases.length === 0 &&
+        plan.deleteAliases.length === 0);
+}
+/** Logs the per-entity outcome of publishing a workspace version and returns how many failed. */
+function logTeamVersionManifest(teamVersion) {
+    const created = teamVersion.manifest.filter(({ outcome }) => outcome === 'CREATED');
+    const skipped = teamVersion.manifest.filter(({ outcome }) => outcome === 'SKIPPED_EXISTS');
+    const failed = teamVersion.manifest.filter(({ outcome }) => outcome === 'FAILED');
+    cli_1.default.log(color_1.default.green(`✅ ${created.length} created`) +
+        `, ${skipped.length} skipped (tag already exists)` +
+        (failed.length > 0 ? `, ${color_1.default.red(`${failed.length} failed`)}` : ''));
+    for (const entry of failed) {
+        cli_1.default.error(`${entry.resourceType.toLowerCase()} ${entry.slug} — ${entry.error ?? 'unknown error'}`);
+    }
+    return failed.length;
+}

package/dist/services/webhook-auth.js

@@ -37,7 +37,7 @@ function resolveEffectiveAuth(webhook, teamWebhookAuth) {
     }
     if (authMode === 'TEAM') {
         if (!teamWebhookAuth) {
-            throw new Error('this webhook inherits the workspace webhook auth, which is not set in team.json');
+            throw new Error('this webhook inherits the workspace webhook auth, which is not set in settings.json');
         }
         return teamWebhookAuth;
     }

package/dist/services/workspace-cloner.d.ts

@@ -0,0 +1,31 @@
+import { TeamOrigin } from '../core/types';
+/**
+ * Creating and syncing a workspace directory, independent of the command that asks for it, so
+ * `fcode clone` (one workspace) and `fcode team:clone` (one per App) share the same behaviour.
+ *
+ * Everything below a resource command resolves the workspace from `process.cwd()` — the
+ * repositories, `WorkspaceConfig`, and the GraphQL client bound to the workspace slug through the
+ * `Fcode-Team` header. `runInWorkspace` is therefore the seam: it moves into the directory,
+ * runs the command, and always moves back. Commands run sequentially and each `Command.run()`
+ * builds a fresh instance, so every workspace gets its own config and its own client.
+ */
+/** Runs `body` with the process rooted at `workspaceDir`, restoring the previous cwd afterwards. */
+export declare function runInWorkspace<T>(workspaceDir: string, body: () => Promise<T>): Promise<T>;
+export declare class WorkspaceNotEmpty extends Error {
+    readonly workspaceDir: string;
+    constructor(workspaceDir: string);
+}
+export declare class WorkspaceAlreadyCloned extends Error {
+    readonly workspaceDir: string;
+    constructor(workspaceDir: string);
+}
+/** True when the directory already holds a Factorial Code workspace (`.fcode/workspace.json`). */
+export declare function isClonedWorkspace(workspaceDir: string): Promise<boolean>;
+/**
+ * Lays out an empty workspace at `workspaceDir`: the resource directories, the `.fcode` metadata
+ * pointing at `origin`, and the files a pull expects to already exist.
+ *
+ * Throws `WorkspaceAlreadyCloned` / `WorkspaceNotEmpty` rather than exiting, so a caller cloning
+ * many workspaces can report the failure and carry on with the rest.
+ */
+export declare function scaffoldWorkspace(workspaceDir: string, origin: TeamOrigin): Promise<void>;

package/dist/services/workspace-cloner.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkspaceAlreadyCloned = exports.WorkspaceNotEmpty = void 0;
+exports.runInWorkspace = runInWorkspace;
+exports.isClonedWorkspace = isClonedWorkspace;
+exports.scaffoldWorkspace = scaffoldWorkspace;
+const fs = require("fs-extra");
+const path = require("node:path");
+const global_1 = require("../config/global");
+const workspace_1 = require("../config/workspace");
+const settings_1 = require("../config/settings");
+/**
+ * Creating and syncing a workspace directory, independent of the command that asks for it, so
+ * `fcode clone` (one workspace) and `fcode team:clone` (one per App) share the same behaviour.
+ *
+ * Everything below a resource command resolves the workspace from `process.cwd()` — the
+ * repositories, `WorkspaceConfig`, and the GraphQL client bound to the workspace slug through the
+ * `Fcode-Team` header. `runInWorkspace` is therefore the seam: it moves into the directory,
+ * runs the command, and always moves back. Commands run sequentially and each `Command.run()`
+ * builds a fresh instance, so every workspace gets its own config and its own client.
+ */
+/** Runs `body` with the process rooted at `workspaceDir`, restoring the previous cwd afterwards. */
+async function runInWorkspace(workspaceDir, body) {
+    const previousCwd = process.cwd();
+    process.chdir(workspaceDir);
+    try {
+        return await body();
+    }
+    finally {
+        process.chdir(previousCwd);
+    }
+}
+class WorkspaceNotEmpty extends Error {
+    constructor(workspaceDir) {
+        super(`Destination path '${workspaceDir}' already exists and is not empty.`);
+        this.workspaceDir = workspaceDir;
+    }
+}
+exports.WorkspaceNotEmpty = WorkspaceNotEmpty;
+class WorkspaceAlreadyCloned extends Error {
+    constructor(workspaceDir) {
+        super(`Workspace '${workspaceDir}' already cloned.`);
+        this.workspaceDir = workspaceDir;
+    }
+}
+exports.WorkspaceAlreadyCloned = WorkspaceAlreadyCloned;
+/** True when the directory already holds a Factorial Code workspace (`.fcode/workspace.json`). */
+async function isClonedWorkspace(workspaceDir) {
+    try {
+        await new workspace_1.default(workspaceDir).getActiveTeam();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function ignoreWorkspaceNotEmpty() {
+    const envValue = process.env.IGNORE_WORKSPACE_NOT_EMPTY;
+    if (envValue === 'true' || envValue === 'false') {
+        return envValue === 'true';
+    }
+    return (await new global_1.default().getSetting(settings_1.SettingKeys.IGNORE_WORKSPACE_NOT_EMPTY)) === 'true';
+}
+/**
+ * Lays out an empty workspace at `workspaceDir`: the resource directories, the `.fcode` metadata
+ * pointing at `origin`, and the files a pull expects to already exist.
+ *
+ * Throws `WorkspaceAlreadyCloned` / `WorkspaceNotEmpty` rather than exiting, so a caller cloning
+ * many workspaces can report the failure and carry on with the rest.
+ */
+async function scaffoldWorkspace(workspaceDir, origin) {
+    if (fs.pathExistsSync(workspaceDir)) {
+        // Listed up front, and `.fcode` probed only when it is already there: constructing a
+        // WorkspaceConfig creates the directory, which would make an empty target read as occupied.
+        const entries = fs.readdirSync(workspaceDir);
+        if (entries.includes('.fcode') && (await isClonedWorkspace(workspaceDir))) {
+            throw new WorkspaceAlreadyCloned(workspaceDir);
+        }
+        if (entries.length > 0 && !(await ignoreWorkspaceNotEmpty())) {
+            throw new WorkspaceNotEmpty(workspaceDir);
+        }
+    }
+    const globalConfig = new global_1.default();
+    const variablesFileName = await globalConfig.getSetting(settings_1.SettingKeys.VARIABLES_FILE_NAME);
+    const localVariablesFileName = await globalConfig.getSetting(settings_1.SettingKeys.LOCAL_VARIABLES_FILE_NAME);
+    fs.mkdirpSync(workspaceDir);
+    for (const directory of ['processes', 'modules', 'dependencies', 'i18n', 'storage']) {
+        fs.mkdirpSync(path.join(workspaceDir, directory));
+    }
+    fs.createFileSync(path.join(workspaceDir, variablesFileName));
+    fs.outputFileSync(path.join(workspaceDir, localVariablesFileName), '');
+    fs.outputFileSync(path.join(workspaceDir, 'datastore.json'), '{}');
+    fs.outputFileSync(path.join(workspaceDir, '.gitignore'), [localVariablesFileName, 'datastore.json', '.env', 'storage/*'].join('\n'));
+    await new workspace_1.default(workspaceDir).init(origin);
+}

package/dist/utils/dev-slug.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Workspace slugs embed an App's UUID base36-encoded: the platform derives a Postgres database
+ * name from the slug and a raw UUID overflows the 63-char identifier limit, so 128 bits become
+ * 25 lowercase alphanumeric characters.
+ *
+ * Ported from the dashboard's `lib/slug.ts` because no REST endpoint exposes the slug — the
+ * dashboard builds it from the App id the same way. The round-trip test pins them together.
+ */
+export declare function encodeUuid(uuid: string): string;
+export declare function decodeUuid(token: string): string;
+/** The development workspace of an App: what `fcode clone` takes and `team:clone` clones per app. */
+export declare const devSlug: (appId: string) => string;

package/dist/utils/dev-slug.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * Workspace slugs embed an App's UUID base36-encoded: the platform derives a Postgres database
+ * name from the slug and a raw UUID overflows the 63-char identifier limit, so 128 bits become
+ * 25 lowercase alphanumeric characters.
+ *
+ * Ported from the dashboard's `lib/slug.ts` because no REST endpoint exposes the slug — the
+ * dashboard builds it from the App id the same way. The round-trip test pins them together.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.devSlug = void 0;
+exports.encodeUuid = encodeUuid;
+exports.decodeUuid = decodeUuid;
+const TOKEN_LENGTH = 25; // ceil(128 / log2(36))
+const ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz';
+function encodeUuid(uuid) {
+    const hex = uuid.replaceAll('-', '').toLowerCase();
+    if (!/^[\da-f]{32}$/.test(hex)) {
+        throw new Error(`Not a UUID: ${uuid}`);
+    }
+    return BigInt(`0x${hex}`).toString(36).padStart(TOKEN_LENGTH, '0');
+}
+function decodeUuid(token) {
+    let value = 0n;
+    for (const char of token.toLowerCase()) {
+        const digit = ALPHABET.indexOf(char);
+        if (digit === -1) {
+            throw new Error(`Invalid slug token: ${token}`);
+        }
+        value = value * 36n + BigInt(digit);
+    }
+    const hex = value.toString(16).padStart(32, '0');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+/** The development workspace of an App: what `fcode clone` takes and `team:clone` clones per app. */
+const devSlug = (appId) => `dev-${encodeUuid(appId)}`;
+exports.devSlug = devSlug;