@factorialco/fcode-cli 3.0.0 → 3.2.0

package/dist/config/settings.js

@@ -4,6 +4,7 @@ exports.SETTINGS_DEFINITIONS = exports.SettingKeys = void 0;
 exports.getSettingDefault = getSettingDefault;
 var SettingKeys;
 (function (SettingKeys) {
+    SettingKeys["DISABLE_BROWSER_LOGIN"] = "disableBrowserLogin";
     SettingKeys["DISABLE_UPDATE_NOTIFIER"] = "disableUpdateNotifier";
     SettingKeys["IGNORE_PROCESS_VERSIONS"] = "ignoreProcessVersions";
     SettingKeys["IGNORE_WORKSPACE_NOT_EMPTY"] = "ignoreWorkspaceNotEmpty";
@@ -24,6 +25,11 @@ exports.SETTINGS_DEFINITIONS = [
         default: 'false',
         description: 'Disable update notifier',
     },
+    {
+        key: SettingKeys.DISABLE_BROWSER_LOGIN,
+        default: 'false',
+        description: 'Disable the interactive browser OAuth login; fcode login prompts for email and password instead',
+    },
     {
         key: SettingKeys.SKIP_SKILLS_SETUP,
         default: 'false',

package/dist/hooks/init/auth.d.ts

@@ -1,3 +1,22 @@
 import { Hook } from '@oclif/core';
+import GlobalConfig from '../../config/global';
+export type LoginMethod = 'accessToken' | 'credentials' | 'browser';
+export interface LoginOptions {
+    email?: string;
+    password?: string;
+    clientId?: string;
+    clientSecret?: string;
+    accessToken?: string;
+    prompt?: boolean;
+    browserLoginDisabled?: boolean;
+}
+/**
+ * Picks how to log in from what the user passed. The browser OAuth flow is the default, but it is
+ * skipped when the user asked to be prompted (`--prompt`), when it is disabled through the
+ * `disableBrowserLogin` setting or the `FCODE_DISABLE_BROWSER_LOGIN` env var (headless machines,
+ * CI, remote shells), or when credentials that identify another method were given.
+ */
+export declare function resolveLoginMethod(options: LoginOptions): LoginMethod;
+export declare function isBrowserLoginDisabled(globalConfig?: GlobalConfig): Promise<boolean>;
 declare const auth: Hook<'init'>;
 export default auth;

package/dist/hooks/init/auth.js

@@ -1,27 +1,61 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveLoginMethod = resolveLoginMethod;
+exports.isBrowserLoginDisabled = isBrowserLoginDisabled;
 const dotenv_1 = require("dotenv");
 const auth_service_1 = require("../../services/auth-service");
 const credential_prompter_1 = require("../../services/credential-prompter");
 const oauth_browser_service_1 = require("../../services/oauth-browser-service");
 const global_1 = require("../../config/global");
+const settings_1 = require("../../config/settings");
 const url_utils_1 = require("../../utils/url-utils");
+/**
+ * Picks how to log in from what the user passed. The browser OAuth flow is the default, but it is
+ * skipped when the user asked to be prompted (`--prompt`), when it is disabled through the
+ * `disableBrowserLogin` setting or the `FCODE_DISABLE_BROWSER_LOGIN` env var (headless machines,
+ * CI, remote shells), or when credentials that identify another method were given.
+ */
+function resolveLoginMethod(options) {
+    if (options.accessToken) {
+        return 'accessToken';
+    }
+    if (options.prompt ||
+        options.browserLoginDisabled ||
+        options.email ||
+        options.password ||
+        (options.clientId && options.clientSecret)) {
+        return 'credentials';
+    }
+    return 'browser';
+}
+async function isBrowserLoginDisabled(globalConfig = new global_1.default()) {
+    return (process.env.FCODE_DISABLE_BROWSER_LOGIN === 'true' ||
+        (await globalConfig.getSetting(settings_1.SettingKeys.DISABLE_BROWSER_LOGIN)) === 'true');
+}
 const auth = async function ({ argv }) {
     const url = argv[0] || global_1.FCODE_CLOUD_URL;
     const authUrl = argv[1] || (0, url_utils_1.buildAuthUrl)(url);
     const isAuthenticated = await auth_service_1.default.isAuthenticated(url);
     if (!isAuthenticated) {
         (0, dotenv_1.config)();
-        const accessToken = argv[6];
-        const prompt = argv[7];
-        if (accessToken) {
+        const [, , email, password, clientId, clientSecret, accessToken, prompt] = argv;
+        const method = resolveLoginMethod({
+            email,
+            password,
+            clientId,
+            clientSecret,
+            accessToken,
+            prompt: Boolean(prompt),
+            browserLoginDisabled: await isBrowserLoginDisabled(),
+        });
+        if (method === 'accessToken') {
             await auth_service_1.default.login({ url, authUrl, accessToken });
         }
-        else if (prompt || argv[2] || argv[3] || (argv[4] && argv[5])) {
-            await credential_prompter_1.default.prompt({ url, authUrl, email: argv[2], password: argv[3], clientId: argv[4], clientSecret: argv[5] });
+        else if (method === 'credentials') {
+            await credential_prompter_1.default.prompt({ url, authUrl, email, password, clientId, clientSecret });
         }
         else {
-            await (0, oauth_browser_service_1.loginViaBrowser)(url, authUrl, argv[4]);
+            await (0, oauth_browser_service_1.loginViaBrowser)(url, authUrl, clientId);
         }
     }
 };

package/dist/services/app-metadata-files.d.ts

@@ -0,0 +1,98 @@
+import { CLIError } from '../core/errors';
+import { DevTeamApp } from '../config/dev-team';
+import { AppLogo, AppMarketplace, AppMarketplaceInput, AppMarketplaceMetadata, AppReadme, AppRelease, DevelopmentTeamApp } from './dashboard-client';
+/**
+ * The files an App folder carries next to `settings.json` and the `app/` checkout. README.md and
+ * MARKETPLACE.md are the developer's (pulled, kept when edited, uploaded with `fcode app:push`);
+ * CHANGELOG.md and the logo are mirrors of the dashboard, rewritten on every pull.
+ */
+export declare const APP_README_FILENAME = "README.md";
+export declare const APP_MARKETPLACE_FILENAME = "MARKETPLACE.md";
+export declare const APP_CHANGELOG_FILENAME = "CHANGELOG.md";
+export declare const APP_MARKETPLACE_DIR = "marketplace";
+export type EditableFile = typeof APP_README_FILENAME | typeof APP_MARKETPLACE_FILENAME;
+export declare class InvalidMarketplaceFile extends CLIError {
+    constructor(reason: string);
+}
+export declare function hashText(text: string): string;
+export declare function renderReadme(app: {
+    name: string;
+    description: string | null;
+}, readme: string | null): string;
+/** What the file means for the cloud: a blank README clears it. */
+export declare function readmeForPush(text: string): string | null;
+export type MarketplaceFrontmatter = Omit<AppMarketplaceInput, 'fullDescription'>;
+export interface ParsedMarketplaceFile {
+    frontmatter: MarketplaceFrontmatter;
+    body: string;
+}
+export declare function renderMarketplaceFile(app: {
+    name: string;
+    publicationState: string;
+}, metadata: AppMarketplaceMetadata | null): string;
+export declare function parseMarketplaceFile(rawText: string): ParsedMarketplaceFile;
+/** `'empty'` when nothing was ever written: no description and no field — not an error, just nothing to send. */
+export declare function marketplaceForPush({ frontmatter, body }: ParsedMarketplaceFile): AppMarketplaceInput | 'empty';
+/** Who requested a release stays in the dashboard: the file is meant to be committed. */
+export declare function renderChangelog(app: {
+    name: string;
+}, releases: AppRelease[]): string;
+/** Mirrors the dashboard logo; returns a warning instead of writing when the type is not one we know. */
+export declare function writeAppLogo(appDir: string, logo: AppLogo | null): string | undefined;
+export type MetadataSyncState = 'up-to-date' | 'modified' | 'out-of-date' | 'conflict' | 'unsynced';
+/**
+ * The part of an editable file the developer owns, in one canonical shape — what the sync hash
+ * covers. Comments, YAML quoting, line endings and a BOM are not content, so a listing published
+ * from the dashboard or a Windows checkout never reads as an edit. A MARKETPLACE.md whose
+ * frontmatter does not parse is compared as raw text: it differs from anything the cloud renders,
+ * and `app:push` reports the actual error.
+ */
+export declare function editableContent(file: EditableFile, text: string): string;
+export declare function hashEditable(file: EditableFile, text: string): string;
+/** What a pull writes for one editable file, and whether the cloud actually holds it. */
+export interface EditableRendering {
+    file: EditableFile;
+    text: string;
+    /** A stub the CLI made up because the cloud has nothing: local edits win over its changes. */
+    generated: boolean;
+}
+export declare function readmeRendering(app: {
+    name: string;
+    description: string | null;
+}, cloud: AppReadme): EditableRendering;
+export declare function marketplaceRendering(app: {
+    name: string;
+    publicationState: string;
+}, cloud: AppMarketplace): EditableRendering;
+/**
+ * Same model as the workspace settings sync: the stored hash is the last thing both sides agreed
+ * on. With none, a file that already matches the cloud is simply adopted; one that differs was
+ * written by hand before any sync (`unsynced`). A stub the cloud never held cannot conflict with
+ * a local edit — there is nothing in the cloud to lose.
+ */
+export declare function metadataSyncState(localText: string, storedHash: string | undefined, cloud: EditableRendering): MetadataSyncState;
+/** Writes the file as the cloud renders it and returns the hash to record for it. */
+export declare function writeEditable(appDir: string, rendering: EditableRendering): string;
+export interface AppMetadataSource {
+    getAppReadme(appId: string): Promise<AppReadme>;
+    getAppMarketplace(appId: string): Promise<AppMarketplace>;
+    listAppReleases(appId: string): Promise<AppRelease[]>;
+    getAppLogo(appId: string): Promise<AppLogo | null>;
+}
+export interface AppMetadataSyncResult {
+    warnings: string[];
+}
+/**
+ * Lays the metadata files out for one App. Never throws: a file the dashboard could not serve is
+ * left as it was and reported, so a metadata hiccup cannot fail the clone of the workspace.
+ */
+export declare function syncAppMetadata(source: AppMetadataSource, appDir: string, app: DevelopmentTeamApp, recorded: DevTeamApp): Promise<AppMetadataSyncResult>;
+export interface MetadataFileStatus {
+    file: string;
+    state: MetadataSyncState | 'missing';
+}
+/** What `team:status` and `app:push` report for the two editable files, given the cloud renderings. */
+export declare function metadataStatus(appDir: string, app: DevelopmentTeamApp, recorded: DevTeamApp, cloud: {
+    readme: AppReadme;
+    marketplace: AppMarketplace;
+}): MetadataFileStatus[];

package/dist/services/app-metadata-files.js

@@ -0,0 +1,363 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidMarketplaceFile = exports.APP_MARKETPLACE_DIR = exports.APP_CHANGELOG_FILENAME = exports.APP_MARKETPLACE_FILENAME = exports.APP_README_FILENAME = void 0;
+exports.hashText = hashText;
+exports.renderReadme = renderReadme;
+exports.readmeForPush = readmeForPush;
+exports.renderMarketplaceFile = renderMarketplaceFile;
+exports.parseMarketplaceFile = parseMarketplaceFile;
+exports.marketplaceForPush = marketplaceForPush;
+exports.renderChangelog = renderChangelog;
+exports.writeAppLogo = writeAppLogo;
+exports.editableContent = editableContent;
+exports.hashEditable = hashEditable;
+exports.readmeRendering = readmeRendering;
+exports.marketplaceRendering = marketplaceRendering;
+exports.metadataSyncState = metadataSyncState;
+exports.writeEditable = writeEditable;
+exports.syncAppMetadata = syncAppMetadata;
+exports.metadataStatus = metadataStatus;
+const crypto = require("node:crypto");
+const fs = require("fs-extra");
+const path = require("node:path");
+const yaml_1 = require("yaml");
+const errors_1 = require("../core/errors");
+const file_utils_1 = require("../utils/file-utils");
+/**
+ * The files an App folder carries next to `settings.json` and the `app/` checkout. README.md and
+ * MARKETPLACE.md are the developer's (pulled, kept when edited, uploaded with `fcode app:push`);
+ * CHANGELOG.md and the logo are mirrors of the dashboard, rewritten on every pull.
+ */
+exports.APP_README_FILENAME = 'README.md';
+exports.APP_MARKETPLACE_FILENAME = 'MARKETPLACE.md';
+exports.APP_CHANGELOG_FILENAME = 'CHANGELOG.md';
+exports.APP_MARKETPLACE_DIR = 'marketplace';
+const LOGO_BASENAME = 'logo';
+const LOGO_EXTENSIONS = {
+    'image/png': 'png',
+    'image/jpeg': 'jpg',
+    'image/webp': 'webp',
+};
+class InvalidMarketplaceFile extends errors_1.CLIError {
+    constructor(reason) {
+        super(`${exports.APP_MARKETPLACE_FILENAME} ${reason}`, { code: 'ERR_INVALID_MARKETPLACE_FILE', exit: 1 });
+    }
+}
+exports.InvalidMarketplaceFile = InvalidMarketplaceFile;
+function hashText(text) {
+    return crypto.createHash('md5').update(text).digest('hex');
+}
+/** A file as the developer's editor may have saved it — BOM and CRLF are not content. */
+function normalizeText(text) {
+    return text.replace(/^\uFEFF/, '').replace(/\r\n?/g, '\n');
+}
+function withTrailingNewline(text) {
+    const trimmed = text.trim();
+    return trimmed.length === 0 ? '' : `${trimmed}\n`;
+}
+// README.md
+function renderReadme(app, readme) {
+    if (readme !== null) {
+        return withTrailingNewline(normalizeText(readme));
+    }
+    const description = app.description?.trim();
+    return description ? `# ${app.name}\n\n${description}\n` : `# ${app.name}\n`;
+}
+/** What the file means for the cloud: a blank README clears it. */
+function readmeForPush(text) {
+    const normalized = normalizeText(text);
+    return normalized.trim().length === 0 ? null : normalized;
+}
+const FRONTMATTER_KEYS = [
+    ['tagline', 'tagline'],
+    ['datoCategoryId', 'category_id'],
+    ['supportLink', 'support_link'],
+    ['helpLink', 'help_link'],
+];
+function singleLine(text) {
+    return text.replace(/\s+/g, ' ').trim();
+}
+function renderMarketplaceFile(app, metadata) {
+    const lines = [
+        '---',
+        `# Marketplace listing of "${singleLine(app.name)}". Edit, then run \`fcode app:push\` from this folder.`,
+        '# Below the closing --- is the full description (markdown, 1-5000 chars).',
+        `# publication_state: ${app.publicationState}        (read-only, set in the dashboard)`,
+    ];
+    if (metadata?.datocmsId) {
+        lines.push(`# datocms_id: ${singleLine(metadata.datocmsId)}              (linked CMS record, managed by Factorial — read-only)`);
+    }
+    const fields = Object.fromEntries(FRONTMATTER_KEYS.map(([field, key]) => [key, metadata?.[field] ?? null]));
+    lines.push((0, yaml_1.stringify)(fields, { lineWidth: 0 }).trimEnd(), '---');
+    return `${lines.join('\n')}\n${withTrailingNewline(metadata?.fullDescription ?? '')}`;
+}
+function frontmatterValue(key, value) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    if (typeof value !== 'string' && typeof value !== 'number') {
+        throw new InvalidMarketplaceFile(`frontmatter key ${key} must be a single text value`);
+    }
+    const text = String(value);
+    return text.trim().length === 0 ? null : text;
+}
+function parseMarketplaceFile(rawText) {
+    const empty = { tagline: null, datoCategoryId: null, supportLink: null, helpLink: null };
+    const text = normalizeText(rawText);
+    if (!text.startsWith('---\n')) {
+        return { frontmatter: empty, body: withTrailingNewline(text) };
+    }
+    const rest = text.slice('---\n'.length);
+    const close = rest.match(/^---[ \t]*$/m);
+    if (!close || close.index === undefined) {
+        throw new InvalidMarketplaceFile('frontmatter is missing its closing ---');
+    }
+    const block = rest.slice(0, close.index);
+    const body = rest.slice(close.index + close[0].length);
+    let parsed;
+    try {
+        parsed = (0, yaml_1.parse)(block);
+    }
+    catch (error) {
+        throw new InvalidMarketplaceFile(`frontmatter is not valid YAML: ${error.message}`);
+    }
+    if (parsed !== null && parsed !== undefined && typeof parsed !== 'object') {
+        throw new InvalidMarketplaceFile('frontmatter must be a mapping of keys to values');
+    }
+    const values = (parsed ?? {});
+    const frontmatter = { ...empty };
+    for (const [field, key] of FRONTMATTER_KEYS) {
+        frontmatter[field] = frontmatterValue(key, values[key]);
+    }
+    return { frontmatter, body: withTrailingNewline(body) };
+}
+/** `'empty'` when nothing was ever written: no description and no field — not an error, just nothing to send. */
+function marketplaceForPush({ frontmatter, body }) {
+    const description = body.trim();
+    const anyField = Object.values(frontmatter).some((value) => value !== null);
+    if (description.length === 0 && !anyField) {
+        return 'empty';
+    }
+    return { fullDescription: description, ...frontmatter };
+}
+// CHANGELOG.md
+function isoDay(iso) {
+    return iso ? iso.slice(0, 10) : 'unknown date';
+}
+function byNewest(pick) {
+    return (a, b) => (pick(b) ?? b.createdAt).localeCompare(pick(a) ?? a.createdAt);
+}
+function renderDeployed(release, stable) {
+    return [
+        `## ${release.version} — ${isoDay(release.deployedAt)}${stable ? ' (stable)' : ''}`,
+        '',
+        release.comments?.trim() ? release.comments.trim() : '_No release notes._',
+        '',
+    ];
+}
+function renderInProgress(release) {
+    const error = release.status === 'failed' && release.error ? `: ${release.error}` : '';
+    return `- ${release.version} — ${release.status} (requested ${isoDay(release.createdAt)})${error}`;
+}
+/** Who requested a release stays in the dashboard: the file is meant to be committed. */
+function renderChangelog(app, releases) {
+    const lines = [
+        '<!-- Generated by `fcode team:pull` from the App\'s releases — edits are overwritten.',
+        '     Release notes are the comments entered when a release is requested. -->',
+        `# Changelog — ${singleLine(app.name)}`,
+        '',
+    ];
+    const deployed = releases.filter(({ status }) => status === 'deployed').sort(byNewest((r) => r.deployedAt));
+    const inProgress = releases.filter(({ status }) => status !== 'deployed').sort(byNewest(() => null));
+    const stable = deployed.filter((r) => r.stableAt !== null).sort(byNewest((r) => r.stableAt))[0];
+    if (releases.length === 0) {
+        lines.push('_No releases yet._', '');
+    }
+    for (const release of deployed) {
+        lines.push(...renderDeployed(release, release === stable));
+    }
+    if (inProgress.length > 0) {
+        lines.push('## In progress', ...inProgress.map(renderInProgress), '');
+    }
+    return `${lines.join('\n').trimEnd()}\n`;
+}
+// marketplace/logo.*
+function existingLogos(appDir) {
+    const dir = path.join(appDir, exports.APP_MARKETPLACE_DIR);
+    if (!fs.pathExistsSync(dir)) {
+        return [];
+    }
+    return fs
+        .readdirSync(dir)
+        .filter((file) => Object.values(LOGO_EXTENSIONS).includes(path.extname(file).slice(1)) && path.parse(file).name === LOGO_BASENAME)
+        .map((file) => path.join(dir, file));
+}
+function removeIfEmpty(dir) {
+    if (fs.pathExistsSync(dir) && fs.readdirSync(dir).length === 0) {
+        fs.removeSync(dir);
+    }
+}
+/** Mirrors the dashboard logo; returns a warning instead of writing when the type is not one we know. */
+function writeAppLogo(appDir, logo) {
+    const extension = logo ? LOGO_EXTENSIONS[logo.contentType.split(';')[0].trim()] : undefined;
+    if (logo && !extension) {
+        return `logo not written: unsupported content type ${logo.contentType}`;
+    }
+    for (const file of existingLogos(appDir)) {
+        fs.removeSync(file);
+    }
+    if (logo && extension) {
+        fs.outputFileSync(path.join(appDir, exports.APP_MARKETPLACE_DIR, `${LOGO_BASENAME}.${extension}`), logo.buffer);
+    }
+    removeIfEmpty(path.join(appDir, exports.APP_MARKETPLACE_DIR));
+    return undefined;
+}
+/**
+ * The part of an editable file the developer owns, in one canonical shape — what the sync hash
+ * covers. Comments, YAML quoting, line endings and a BOM are not content, so a listing published
+ * from the dashboard or a Windows checkout never reads as an edit. A MARKETPLACE.md whose
+ * frontmatter does not parse is compared as raw text: it differs from anything the cloud renders,
+ * and `app:push` reports the actual error.
+ */
+function editableContent(file, text) {
+    if (file === exports.APP_README_FILENAME) {
+        return withTrailingNewline(normalizeText(text));
+    }
+    try {
+        const { frontmatter, body } = parseMarketplaceFile(text);
+        return JSON.stringify([...FRONTMATTER_KEYS.map(([field]) => frontmatter[field]), body]);
+    }
+    catch (error) {
+        if (error instanceof InvalidMarketplaceFile) {
+            return normalizeText(text);
+        }
+        throw error;
+    }
+}
+function hashEditable(file, text) {
+    return hashText(editableContent(file, text));
+}
+function readmeRendering(app, cloud) {
+    return { file: exports.APP_README_FILENAME, text: renderReadme(app, cloud.readme), generated: cloud.readme === null };
+}
+function marketplaceRendering(app, cloud) {
+    return { file: exports.APP_MARKETPLACE_FILENAME, text: renderMarketplaceFile(app, cloud.metadata), generated: false };
+}
+/**
+ * Same model as the workspace settings sync: the stored hash is the last thing both sides agreed
+ * on. With none, a file that already matches the cloud is simply adopted; one that differs was
+ * written by hand before any sync (`unsynced`). A stub the cloud never held cannot conflict with
+ * a local edit — there is nothing in the cloud to lose.
+ */
+function metadataSyncState(localText, storedHash, cloud) {
+    const local = editableContent(cloud.file, localText);
+    const remote = editableContent(cloud.file, cloud.text);
+    if (storedHash === undefined) {
+        return local === remote ? 'up-to-date' : 'unsynced';
+    }
+    const localChanged = hashText(local) !== storedHash;
+    const cloudChanged = hashText(remote) !== storedHash;
+    if (localChanged && cloudChanged) {
+        return cloud.generated ? 'modified' : 'conflict';
+    }
+    if (localChanged) {
+        return 'modified';
+    }
+    return cloudChanged ? 'out-of-date' : 'up-to-date';
+}
+/** Writes the file as the cloud renders it and returns the hash to record for it. */
+function writeEditable(appDir, rendering) {
+    fs.outputFileSync(path.join(appDir, rendering.file), rendering.text);
+    return hashEditable(rendering.file, rendering.text);
+}
+function keptWarning(state, file, folder) {
+    switch (state) {
+        case 'unsynced':
+            return `${file} exists but was never synced — kept; run fcode app:push to upload it, or delete it to take the cloud version`;
+        case 'conflict':
+            return `${file} changed both locally and in the cloud — kept; fcode app:push --force in ${folder} to overwrite the cloud, or delete it and fcode team:pull to take the cloud version`;
+        default:
+            return `${file} edited locally — kept; run fcode app:push in ${folder} to upload it`;
+    }
+}
+function applyEditable(appDir, rendering, storedHash) {
+    const filePath = path.join(appDir, rendering.file);
+    if (!fs.pathExistsSync(filePath)) {
+        return { hash: writeEditable(appDir, rendering) };
+    }
+    const local = fs.readFileSync(filePath, 'utf8');
+    const state = metadataSyncState(local, storedHash, rendering);
+    switch (state) {
+        case 'up-to-date':
+            // Same content, possibly stale read-only comments: refresh those without touching the state.
+            if (normalizeText(local) !== rendering.text) {
+                fs.outputFileSync(filePath, rendering.text);
+            }
+            return { hash: hashEditable(rendering.file, rendering.text) };
+        case 'out-of-date':
+            return { hash: writeEditable(appDir, rendering) };
+        default:
+            return { warning: keptWarning(state, rendering.file, path.basename(appDir)) };
+    }
+}
+function settledOrWarn(result, file, warnings) {
+    if (result.status === 'fulfilled') {
+        return result.value;
+    }
+    warnings.push(`${file} not refreshed: ${result.reason.message}`);
+    return undefined;
+}
+/**
+ * Lays the metadata files out for one App. Never throws: a file the dashboard could not serve is
+ * left as it was and reported, so a metadata hiccup cannot fail the clone of the workspace.
+ */
+async function syncAppMetadata(source, appDir, app, recorded) {
+    const warnings = [];
+    const [readme, marketplace, releases, logo] = await Promise.allSettled([
+        source.getAppReadme(app.id),
+        source.getAppMarketplace(app.id),
+        source.listAppReleases(app.id),
+        app.logoContentType === null ? Promise.resolve(null) : source.getAppLogo(app.id),
+    ]);
+    const editable = (rendering, storedHash) => {
+        const outcome = applyEditable(appDir, rendering, storedHash);
+        if (outcome.warning) {
+            warnings.push(outcome.warning);
+        }
+        return outcome.hash ?? storedHash;
+    };
+    const cloudReadme = settledOrWarn(readme, exports.APP_README_FILENAME, warnings);
+    if (cloudReadme) {
+        recorded.readmeHash = editable(readmeRendering(app, cloudReadme), recorded.readmeHash);
+    }
+    const cloudMarketplace = settledOrWarn(marketplace, exports.APP_MARKETPLACE_FILENAME, warnings);
+    if (cloudMarketplace) {
+        recorded.marketplaceHash = editable(marketplaceRendering(app, cloudMarketplace), recorded.marketplaceHash);
+    }
+    const cloudReleases = settledOrWarn(releases, exports.APP_CHANGELOG_FILENAME, warnings);
+    if (cloudReleases) {
+        (0, file_utils_1.outputFileSyncIfChanged)(path.join(appDir, exports.APP_CHANGELOG_FILENAME), renderChangelog(app, cloudReleases));
+    }
+    const cloudLogo = settledOrWarn(logo, `${exports.APP_MARKETPLACE_DIR}/${LOGO_BASENAME}`, warnings);
+    if (cloudLogo !== undefined) {
+        const warning = writeAppLogo(appDir, cloudLogo);
+        if (warning) {
+            warnings.push(warning);
+        }
+    }
+    return { warnings };
+}
+/** What `team:status` and `app:push` report for the two editable files, given the cloud renderings. */
+function metadataStatus(appDir, app, recorded, cloud) {
+    const files = [
+        [readmeRendering(app, cloud.readme), recorded.readmeHash],
+        [marketplaceRendering(app, cloud.marketplace), recorded.marketplaceHash],
+    ];
+    return files.map(([rendering, storedHash]) => {
+        const filePath = path.join(appDir, rendering.file);
+        if (!fs.pathExistsSync(filePath)) {
+            return { file: rendering.file, state: 'missing' };
+        }
+        return { file: rendering.file, state: metadataSyncState(fs.readFileSync(filePath, 'utf8'), storedHash, rendering) };
+    });
+}

package/dist/services/dashboard-client.d.ts

@@ -3,10 +3,67 @@ export interface DevelopmentTeam {
     id: string;
     name: string;
 }
+export type AppPublicationState = 'draft' | 'private' | 'public';
 export interface DevelopmentTeamApp {
     id: string;
     name: string;
     description: string | null;
+    publicationState: AppPublicationState;
+    /** png/jpeg/webp when the App has a logo; null means there is none to fetch. */
+    logoContentType: string | null;
+}
+export interface AppReadme {
+    readme: string | null;
+}
+/** The developer-editable half of the marketplace listing, as the dashboard stores it. */
+export interface AppMarketplaceInput {
+    fullDescription: string;
+    tagline: string | null;
+    datoCategoryId: string | null;
+    supportLink: string | null;
+    helpLink: string | null;
+}
+export interface AppMarketplaceMetadata extends AppMarketplaceInput {
+    /** Linked CMS record, managed by Factorial; read-only. */
+    datocmsId: string | null;
+}
+export interface AppMarketplace {
+    /** Null until the listing is first saved. */
+    metadata: AppMarketplaceMetadata | null;
+}
+export type AppReleaseStatus = 'requested' | 'deploying' | 'deployed' | 'failed';
+export interface AppRelease {
+    id: string;
+    version: string;
+    comments: string | null;
+    status: AppReleaseStatus;
+    error: string | null;
+    requestedBy: string | null;
+    deployedAt: string | null;
+    stableAt: string | null;
+    createdAt: string;
+}
+export interface AppLogo {
+    buffer: Buffer;
+    contentType: string;
+}
+/** A non-2xx answer from the dashboard, carrying the RFC 9457 problem details it sent. */
+export declare class DashboardApiError extends Error {
+    readonly status: number;
+    readonly path: string;
+    readonly detail: string;
+    readonly code?: string | undefined;
+    constructor(status: number, path: string, detail: string, code?: string | undefined);
+}
+/**
+ * A base workspace the team owns (`base-app` and the like), as opposed to an App's `dev-` workspace.
+ * The slug is the platform team slug itself: fixed, filesystem-safe, and unique.
+ */
+export interface DevelopmentTeamGlobalWorkspace {
+    id: string;
+    name: string;
+    slug: string;
+    description: string;
 }
 /**
  * `https://code.factorialhr.com/platform` → `https://code.factorialhr.com/dashboard/api/v1`.
@@ -24,8 +81,22 @@ export default class DashboardClient {
     listDevelopmentTeams(): Promise<DevelopmentTeam[]>;
     /** The Apps owned by a development team, narrowed by the API to the ones the session can see. */
     listTeamApps(teamId: string): Promise<DevelopmentTeamApp[]>;
+    getApp(appId: string): Promise<DevelopmentTeamApp>;
+    getAppReadme(appId: string): Promise<AppReadme>;
+    putAppReadme(appId: string, readme: string | null): Promise<AppReadme>;
+    getAppMarketplace(appId: string): Promise<AppMarketplace>;
+    /** Full replace: every field travels, nulls included, since an absent key clears on the dashboard. */
+    putAppMarketplace(appId: string, input: AppMarketplaceInput): Promise<AppMarketplaceMetadata>;
+    listAppReleases(appId: string): Promise<AppRelease[]>;
+    /** The App's logo bytes, or null when it has none. */
+    getAppLogo(appId: string): Promise<AppLogo | null>;
+    /** The global workspaces owned by a development team. */
+    listTeamGlobalWorkspaces(teamId: string): Promise<DevelopmentTeamGlobalWorkspace[]>;
     private getAllPages;
     private get;
+    private request;
+    private getBinary;
+    private send;
     private headers;
     private errorDetail;
 }