@factorialco/fcode-cli 2.4.0 → 3.1.0

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

@@ -1,6 +1,6 @@
-import { Team, TeamAliasFileEntry, TeamVersion, TeamVersionAlias, TeamVersionFileEntry } from '../core/types';
+import { TeamAliasFileEntry, TeamVersion, TeamVersionAlias, TeamVersionFileEntry, WorkspaceSettings } from '../core/types';
 /**
- * What a team:push must do to make the cloud's team versions and aliases match team.json.
+ * 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.
  */
@@ -10,7 +10,7 @@ export interface TeamVersioningSyncPlan {
     setAliases: TeamAliasFileEntry[];
     deleteAliases: TeamVersionAlias[];
 }
-export declare function planTeamVersioningSync(team: Team, cloudVersions: TeamVersion[], cloudAliases: TeamVersionAlias[]): TeamVersioningSyncPlan;
+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 team version and returns how many failed. */
+/** 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

@@ -5,9 +5,9 @@ exports.teamVersioningSyncPlanIsEmpty = teamVersioningSyncPlanIsEmpty;
 exports.logTeamVersionManifest = logTeamVersionManifest;
 const color_1 = require("@oclif/color");
 const cli_1 = require("../utils/cli");
-function planTeamVersioningSync(team, cloudVersions, cloudAliases) {
-    const localVersions = team.versions ?? [];
-    const localAliases = team.aliases ?? [];
+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]));
@@ -25,7 +25,7 @@ function teamVersioningSyncPlanIsEmpty(plan) {
         plan.setAliases.length === 0 &&
         plan.deleteAliases.length === 0);
 }
-/** Logs the per-entity outcome of publishing a team version and returns how many failed. */
+/** 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');

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;

package/dist/utils/diff.d.ts

@@ -0,0 +1,19 @@
+export declare const DEV_NULL = "/dev/null";
+/**
+ * One comparable artifact of a resource, named after the file it is stored in. A side left
+ * undefined does not exist there (a process only in the cloud, a module only on disk); an empty
+ * string is a file that exists and is empty, which is a different thing and diffs differently.
+ */
+export type PseudoFile = {
+    path: string;
+    remote?: string;
+    local?: string;
+};
+export declare const hasDifference: (file: PseudoFile) => boolean;
+/**
+ * A unified diff of one pseudo-file, remote as the old side and local as the new one, so the
+ * patch reads as what a push would apply to the cloud. Empty when the sides are equal.
+ */
+export declare function renderUnifiedDiff(file: PseudoFile): string;
+/** Colors a rendered patch the way git does. Chalk no-ops when the output is not a TTY. */
+export declare function colorizeDiff(patch: string): string;

package/dist/utils/diff.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasDifference = exports.DEV_NULL = void 0;
+exports.renderUnifiedDiff = renderUnifiedDiff;
+exports.colorizeDiff = colorizeDiff;
+const diff_1 = require("diff");
+const chalk = require("chalk");
+exports.DEV_NULL = '/dev/null';
+const hasDifference = (file) => file.remote !== file.local;
+exports.hasDifference = hasDifference;
+/**
+ * A hunk range the way git writes one: the count is left out when it is 1, and an empty range
+ * points at the line it would be inserted after, so a whole-file addition reads `-0,0`.
+ */
+function formatRange(start, lines) {
+    if (lines === 1) {
+        return `${start}`;
+    }
+    return `${lines === 0 ? start - 1 : start},${lines}`;
+}
+/**
+ * A unified diff of one pseudo-file, remote as the old side and local as the new one, so the
+ * patch reads as what a push would apply to the cloud. Empty when the sides are equal.
+ */
+function renderUnifiedDiff(file) {
+    if (!(0, exports.hasDifference)(file)) {
+        return '';
+    }
+    const oldName = file.remote === undefined ? exports.DEV_NULL : `remote/${file.path}`;
+    const newName = file.local === undefined ? exports.DEV_NULL : `local/${file.path}`;
+    const { hunks } = (0, diff_1.structuredPatch)(oldName, newName, file.remote ?? '', file.local ?? '', undefined, undefined, { context: 3 });
+    const lines = [`--- ${oldName}`, `+++ ${newName}`];
+    for (const hunk of hunks) {
+        lines.push(`@@ -${formatRange(hunk.oldStart, hunk.oldLines)} +${formatRange(hunk.newStart, hunk.newLines)} @@`, ...hunk.lines);
+    }
+    return lines.join('\n');
+}
+/** Colors a rendered patch the way git does. Chalk no-ops when the output is not a TTY. */
+function colorizeDiff(patch) {
+    return patch
+        .split('\n')
+        .map((line) => {
+        if (line.startsWith('---') || line.startsWith('+++')) {
+            return chalk.bold(line);
+        }
+        if (line.startsWith('@@')) {
+            return chalk.cyan(line);
+        }
+        if (line.startsWith('+')) {
+            return chalk.green(line);
+        }
+        if (line.startsWith('-')) {
+            return chalk.red(line);
+        }
+        return line;
+    })
+        .join('\n');
+}

package/dist/utils/slugify.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Folder name for a development team or an App, derived from its display name. Names are free
+ * text — accents, punctuation, emoji — while the folder has to be portable and typeable, so
+ * everything outside `[a-z0-9-]` collapses into a single dash.
+ */
+export declare function slugify(name: string): string;
+/**
+ * `slugify` with a fallback, so a name written entirely in a non-latin script still yields a
+ * usable folder instead of an empty one.
+ */
+export declare function slugifyOr(name: string, fallback: string): string;
+/**
+ * The first claimant of a slug keeps it; the next ones get `-2`, `-3`… Callers assign folders in a
+ * stable order (by app id), so the same team always produces the same layout — and once assigned,
+ * the folder is recorded in the team metadata and never derived again.
+ */
+export declare function uniqueSlug(slug: string, taken: Set<string>): string;

package/dist/utils/slugify.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.slugify = slugify;
+exports.slugifyOr = slugifyOr;
+exports.uniqueSlug = uniqueSlug;
+/**
+ * Folder name for a development team or an App, derived from its display name. Names are free
+ * text — accents, punctuation, emoji — while the folder has to be portable and typeable, so
+ * everything outside `[a-z0-9-]` collapses into a single dash.
+ */
+function slugify(name) {
+    return name
+        .normalize('NFKD')
+        .replaceAll(/[̀-ͯ]/g, '')
+        .replaceAll(/[^a-zA-Z\d]+/g, '-')
+        .replaceAll(/^-+|-+$/g, '')
+        .toLowerCase();
+}
+/**
+ * `slugify` with a fallback, so a name written entirely in a non-latin script still yields a
+ * usable folder instead of an empty one.
+ */
+function slugifyOr(name, fallback) {
+    const slug = slugify(name);
+    return slug.length > 0 ? slug : fallback;
+}
+/**
+ * The first claimant of a slug keeps it; the next ones get `-2`, `-3`… Callers assign folders in a
+ * stable order (by app id), so the same team always produces the same layout — and once assigned,
+ * the folder is recorded in the team metadata and never derived again.
+ */
+function uniqueSlug(slug, taken) {
+    if (!taken.has(slug)) {
+        return slug;
+    }
+    let suffix = 2;
+    while (taken.has(`${slug}-${suffix}`)) {
+        suffix += 1;
+    }
+    return `${slug}-${suffix}`;
+}