fundus 0.0.2 → 0.0.4

package/dist/server/cli-commands.js

@@ -0,0 +1,1178 @@
+/**
+ * The state/asset/folder/manifest command groups of the fundus CLI (M7): thin
+ * terminal adapters over the one operations layer (operations.ts) — the same
+ * class the REST server exposes to the editor, so every mutation runs the
+ * editor's autosave chain (write library → process affected assets →
+ * regenerate manifest modules). Every command supports `--json` (a single
+ * JSON document on stdout, nothing else there) and `--help`; expected
+ * failures throw and cli.ts maps them to exit code 1.
+ */
+import { readFile } from 'node:fs/promises';
+import { basename, resolve } from 'node:path';
+import { compareCodeUnits, folderNameOf, parentFolderPath, manifestEmojiError, MANIFEST_COLORS, MANIFEST_EMOJIS, proposeAssetId, resolveManifestColor, typesForFileName } from '../core/index.js';
+import { runBuild } from './build.js';
+import { formatCheckFinding, runCheck } from './check.js';
+import { loadConfig } from './config-loader.js';
+import { FundusOperations } from './operations.js';
+import { pluginsByType, serverPluginForType } from './plugins.js';
+import { CliUsageError, formatBytes, parseArguments, parseJsonFlag, parseManifestList, printJsonDocument, requirePositionals } from './cli-io.js';
+const COMMON_FLAGS = {
+    json: { takesValue: false },
+    help: { takesValue: false }
+};
+function hasHelpFlag(argumentList) {
+    return argumentList.includes('--help');
+}
+async function createOperations() {
+    return new FundusOperations(await loadConfig(process.cwd()));
+}
+function manifestRows(state) {
+    return Object.keys(state.library.manifests)
+        .sort(compareCodeUnits)
+        .map((name) => ({
+        name,
+        color: state.library.manifests[name]?.color ?? null,
+        emoji: state.library.manifests[name]?.emoji ?? null,
+        explicitMemberIds: state.manifestMemberships[name]?.explicitMemberIds ?? [],
+        passiveMembers: state.manifestMemberships[name]?.passiveMembers ?? [],
+        deliveredBytes: state.manifestDeliveredBytes[name] ?? 0
+    }));
+}
+/** A manifest's `emoji name` prefix for human output (emoji only when set). */
+function manifestLabel(row) {
+    return row.emoji ? `${row.emoji} ${row.name}` : row.name;
+}
+function assetById(state, id) {
+    const asset = state.assets.find((candidate) => candidate.id === id);
+    if (!asset) {
+        throw new Error(`Unknown asset "${id}".`);
+    }
+    return asset;
+}
+// ---------------------------------------------------------------------------
+// Human output
+// ---------------------------------------------------------------------------
+function membershipSummary(asset) {
+    const parts = [];
+    if (asset.manifests.length > 0)
+        parts.push(asset.manifests.join(','));
+    if (asset.passiveManifests.length > 0) {
+        parts.push(`passive: ${asset.passiveManifests.map((membership) => membership.manifest).join(',')}`);
+    }
+    return parts.length > 0 ? parts.join(' + ') : '(no manifest)';
+}
+function printAssetLines(assets, indent = '') {
+    const idWidth = Math.max(0, ...assets.map((asset) => asset.id.length));
+    const typeWidth = Math.max(0, ...assets.map((asset) => asset.type.length));
+    for (const asset of assets) {
+        const warningSuffix = asset.warnings.length > 0 ? `  ⚠ ${asset.warnings.length} warning(s)` : '';
+        console.log(`${indent}${asset.id.padEnd(idWidth)}  ${asset.type.padEnd(typeWidth)}  ` +
+            `${membershipSummary(asset)}${warningSuffix}`);
+    }
+}
+function printIssues(issues) {
+    if (issues.length === 0)
+        return;
+    console.log('Issues:');
+    for (const issue of issues) {
+        console.log(`  - ${issue.assetId ? `[${issue.assetId}] ` : ''}${issue.message}`);
+    }
+}
+function printHumanState(state) {
+    const rows = manifestRows(state);
+    console.log(`${state.assets.length} asset(s), ${state.library.folders.length} folder(s), ${rows.length} manifest(s)`);
+    if (rows.length > 0) {
+        console.log('');
+        console.log('Manifests:');
+        const labels = rows.map(manifestLabel);
+        const nameWidth = Math.max(0, ...labels.map((label) => label.length));
+        rows.forEach((row, index) => {
+            console.log(`  ${labels[index].padEnd(nameWidth)}  ${row.explicitMemberIds.length} explicit + ` +
+                `${row.passiveMembers.length} passive member(s), ${formatBytes(row.deliveredBytes)} delivered`);
+        });
+    }
+    if (state.assets.length > 0) {
+        console.log('');
+        console.log('Assets:');
+        printAssetLines(state.assets, '  ');
+    }
+    const warningTotal = state.assets.reduce((sum, asset) => sum + asset.warnings.length, 0);
+    if (warningTotal > 0) {
+        console.log('');
+        console.log(`⚠ ${warningTotal} warning(s) — see \`fundus asset list --warnings-only\`.`);
+    }
+    if (state.issues.length > 0) {
+        console.log('');
+        printIssues(state.issues);
+    }
+}
+function printHumanAssetDetail(asset) {
+    console.log(`${asset.id} (${asset.type})`);
+    console.log(`  raw:        ${asset.raw}`);
+    console.log(`  folder:     ${asset.folder || 'root'}`);
+    console.log(`  rawHash:    ${asset.rawHash}`);
+    console.log(`  manifests:  ${asset.manifests.length > 0 ? asset.manifests.join(', ') : '(none)'}`);
+    for (const membership of asset.passiveManifests) {
+        console.log(`  passive:    ${membership.manifest} (via ${membership.via.join(', ')})`);
+    }
+    if (asset.proxy) {
+        const dimensions = asset.proxy.width !== undefined && asset.proxy.height !== undefined
+            ? `, ${asset.proxy.width}×${asset.proxy.height}`
+            : '';
+        const duration = asset.proxy.durationMs !== undefined ? `, ${asset.proxy.durationMs} ms` : '';
+        console.log(`  proxy:      ${asset.proxy.relativePath} (${formatBytes(asset.proxy.fileSize)}${dimensions}${duration})`);
+    }
+    else {
+        console.log('  proxy:      (none — not delivered or not processed yet)');
+    }
+    for (const reference of asset.references.outgoing) {
+        console.log(`  reference:  ${reference.field} → ${reference.assetId}`);
+    }
+    for (const reference of asset.references.incoming) {
+        console.log(`  referenced: ← ${reference.assetId} (${reference.field})`);
+    }
+    console.log('  parameters:');
+    const parametersJson = JSON.stringify(asset.parameters, null, '\t');
+    for (const line of parametersJson.split('\n')) {
+        console.log(`    ${line}`);
+    }
+    for (const warning of asset.warnings) {
+        console.log(`  ⚠ ${warning}`);
+    }
+}
+/** Human output of a successful mutation: headline, asset warnings, issues. */
+function printMutationResult(headline, asset, state) {
+    console.log(headline);
+    if (asset) {
+        for (const warning of asset.warnings) {
+            console.log(`  ⚠ ${warning}`);
+        }
+    }
+    printIssues(state.issues);
+}
+// ---------------------------------------------------------------------------
+// fundus state
+// ---------------------------------------------------------------------------
+export const STATE_HELP = `fundus state — the full project state in one document
+
+Usage: fundus state [--json]
+
+The agent's one-stop overview: every asset (type, raw file, parameters,
+explicit + passive manifest memberships, proxy status, reference edges,
+warnings), every manifest (members, delivered bytes), library-level
+validation issues, and the available preset names per asset type.
+
+Flags:
+  --json   print {"ok": true, "state": <FundusStateDto>} on stdout
+  --help   this help
+
+Read-only: nothing is processed or written.
+
+Example:
+  fundus state --json | jq '.state.assets[].id'
+`;
+export async function runStateCommand(argumentList) {
+    if (hasHelpFlag(argumentList)) {
+        console.log(STATE_HELP);
+        return;
+    }
+    const parsed = parseArguments(argumentList, COMMON_FLAGS, 'fundus state');
+    requirePositionals(parsed, [], 'fundus state');
+    const operations = await createOperations();
+    const state = await operations.state();
+    if (parsed.flags.json) {
+        printJsonDocument({ ok: true, state });
+        return;
+    }
+    printHumanState(state);
+}
+// ---------------------------------------------------------------------------
+// fundus asset …
+// ---------------------------------------------------------------------------
+export const ASSET_HELP = `fundus asset — inspect and mutate assets
+
+Usage: fundus asset <subcommand> …
+
+Every mutation runs the full editor autosave chain: write library →
+process affected assets → regenerate manifest modules. There is no
+separate apply/sync step. All subcommands accept --json (a single JSON
+document on stdout) and --help.
+
+Subcommands:
+  list      list assets (--manifest, --type, --warnings-only)
+  show      one asset in detail
+  ingest    copy a file into the raw dir as a typed asset
+  set       merge parameters and/or replace manifest membership
+  rename    rename an asset id
+  move      move an asset to a folder or root
+  delete    delete an asset (record, raw file, proxies)
+
+Run \`fundus asset <subcommand> --help\` for the focused page (flags,
+semantics, an example) — e.g. \`fundus asset set --help\` documents the
+--parameters merge rules.
+`;
+export const ASSET_LIST_HELP = `fundus asset list — list assets, optionally filtered
+
+Usage: fundus asset list [--manifest <name>] [--type <type>] [--warnings-only] [--json]
+
+One line per asset: id, type, manifest memberships (explicit +
+passive), warning count.
+
+Flags:
+  --manifest <name>   only members of this manifest (explicit or passive)
+  --type <type>       only this asset type (${Object.keys(pluginsByType).sort().join(', ')})
+  --warnings-only     only assets with at least one warning
+  --json              print {"ok": true, "assets": [<AssetStateDto>, …]}
+  --help              this help
+
+Read-only: nothing is processed or written.
+
+Example:
+  fundus asset list --manifest mainCatalog --json
+`;
+export const ASSET_SHOW_HELP = `fundus asset show — one asset in detail
+
+Usage: fundus asset show <id> [--json]
+
+Prints the asset's raw file, content hash, parameters, explicit +
+passive manifest memberships, proxy status, reference edges (outgoing
+and incoming), and warnings.
+
+Flags:
+  --json   print {"ok": true, "asset": <AssetStateDto>}
+  --help   this help
+
+Read-only: nothing is processed or written.
+
+Example:
+  fundus asset show navigationPanel --json
+`;
+export const ASSET_INGEST_HELP = `fundus asset ingest — copy a file into the raw dir as a typed asset
+
+Usage: fundus asset ingest <file> [--type <type>] [--id <id>] [--folder <path|root>]
+                           [--manifests <a,b>] [--parameters <json>] [--json]
+
+Behaves like an editor upload: the file is copied into the raw
+directory (sanitized, non-colliding name) and content-hashed, and the
+record starts with the owning plugin's default parameters — a slice
+additionally seeds insets from the image dimensions and a pixel ratio
+from a @2x-style file-name suffix. Runs the full autosave chain
+(write library → process → regenerate manifest modules).
+
+Flags:
+  --type <type>        required when the file extension is ambiguous
+                       (.png could be image or slice, .mp4 video or
+                       chroma-key-video); optional when exactly one
+                       type accepts it (.wav → audio); known types:
+                       ${Object.keys(pluginsByType).sort().join(', ')}
+  --id <id>            asset id (camelCase identifier); default:
+                       proposed from the file name
+                       (panel_button@2x.png → sidebarPanel)
+  --folder <path|root> destination folder; default: root
+  --manifests <a,b>    explicit manifest membership, applied in the
+                       same operation (comma-separated; every name
+                       must exist)
+  --parameters <json>  parameter patch merged onto the plugin defaults
+                       — same shallow-merge semantics as \`asset set\`
+                       (see \`fundus asset set --help\`)
+  --json               print {"ok": true, "asset": <AssetStateDto>, "issues": […]}
+  --help               this help
+
+A failed ingest (invalid patch, unknown manifest, …) leaves nothing
+behind: the raw file and record are rolled back.
+
+Example:
+  fundus asset ingest ./exports/navigation_panel@2x.png --type slice \\
+    --manifests mainCatalog --json
+`;
+export const ASSET_SET_HELP = `fundus asset set — update an asset's parameters and/or memberships
+
+Usage: fundus asset set <id> [--parameters <json>] [--manifests <a,b>] [--json]
+
+At least one of --parameters/--manifests is required. Runs the full
+autosave chain (write library → process → regenerate manifest modules).
+
+Flags:
+  --parameters <json>  SHALLOW MERGE at the top level onto the current
+                       parameters, then plugin validation:
+                         {"preset": "webp-hq"}        sets one field,
+                                                      keeps the others
+                         {"chromaKey": {…}}           replaces the whole
+                                                      chromaKey object
+                         {"mask": null}               clears an optional
+                                                      field
+                         {"mask": {"$asset": "someImage"}}
+                                                      sets an asset
+                                                      reference
+  --manifests <a,b>    REPLACES the explicit membership set (declarative,
+                       idempotent); --manifests "" clears it
+  --json               print {"ok": true, "asset": <AssetStateDto>, "issues": […]}
+  --help               this help
+
+The mutation is validated first and rejected (exit 1, nothing written)
+if it would leave the library invalid — e.g. a reference to a missing
+asset, a reference cycle, or an unknown manifest name. Ingest reference
+targets before pointing at them.
+
+Example:
+  fundus asset set characterIdle \\
+    --parameters '{"mask": {"$asset": "characterIdleMask"}}' --json
+`;
+export const ASSET_RENAME_HELP = `fundus asset rename — rename an asset id
+
+Usage: fundus asset rename <id> <newId> [--json]
+
+Renames the asset's id (the raw file keeps its name — ids are the
+stable key) and re-hashes its proxy under the new id via the autosave
+chain. Fails if another asset references <id> — update the referrers
+first — or if <newId> is taken or invalid.
+
+Flags:
+  --json   print {"ok": true, "asset": <AssetStateDto>, "issues": […]}
+  --help   this help
+
+Example:
+  fundus asset rename sidebarPanel navigationPanel --json
+`;
+export const ASSET_DELETE_HELP = `fundus asset delete — delete an asset
+
+Usage: fundus asset delete <id> [--json]
+
+Deletes the library record, its raw file, and its proxies, then
+regenerates the affected manifest modules. Fails if another asset
+references it — remove the references first.
+
+Flags:
+  --json   print {"ok": true, "deletedAssetId": "<id>", "issues": […]}
+  --help   this help
+
+Example:
+  fundus asset delete obsoleteBanner --json
+`;
+export const ASSET_MOVE_HELP = `fundus asset move — move an asset between folders
+
+Usage: fundus asset move <id> <folder|root> [--json]
+
+Moves the raw file and its current proxy without changing the stable asset id,
+then runs the autosave chain. The destination folder must already exist; use
+the literal "root" for the implicit root.
+
+Flags:
+  --json   print {"ok": true, "asset": <AssetStateDto>, "issues": […]}
+  --help   this help
+
+Example:
+  fundus asset move navigationPanel "UI/Buttons" --json
+`;
+const ASSET_SUBCOMMAND_HELP = {
+    list: ASSET_LIST_HELP,
+    show: ASSET_SHOW_HELP,
+    ingest: ASSET_INGEST_HELP,
+    set: ASSET_SET_HELP,
+    rename: ASSET_RENAME_HELP,
+    move: ASSET_MOVE_HELP,
+    delete: ASSET_DELETE_HELP
+};
+async function runAssetList(argumentList) {
+    const parsed = parseArguments(argumentList, {
+        ...COMMON_FLAGS,
+        manifest: { takesValue: true },
+        type: { takesValue: true },
+        'warnings-only': { takesValue: false }
+    }, 'fundus asset list');
+    requirePositionals(parsed, [], 'fundus asset list');
+    const typeFilter = parsed.flags.type;
+    if (typeof typeFilter === 'string')
+        serverPluginForType(typeFilter);
+    const operations = await createOperations();
+    const state = await operations.state();
+    const manifestFilter = parsed.flags.manifest;
+    if (typeof manifestFilter === 'string' &&
+        !Object.hasOwn(state.library.manifests, manifestFilter)) {
+        throw new Error(`Unknown manifest "${manifestFilter}".`);
+    }
+    const assets = state.assets.filter((asset) => {
+        if (typeof typeFilter === 'string' && asset.type !== typeFilter)
+            return false;
+        if (typeof manifestFilter === 'string' &&
+            !asset.manifests.includes(manifestFilter) &&
+            !asset.passiveManifests.some((membership) => membership.manifest === manifestFilter)) {
+            return false;
+        }
+        if (parsed.flags['warnings-only'] && asset.warnings.length === 0)
+            return false;
+        return true;
+    });
+    if (parsed.flags.json) {
+        printJsonDocument({ ok: true, assets });
+        return;
+    }
+    if (assets.length === 0) {
+        console.log('No matching assets.');
+        return;
+    }
+    printAssetLines(assets);
+}
+async function runAssetShow(argumentList) {
+    const parsed = parseArguments(argumentList, COMMON_FLAGS, 'fundus asset show');
+    const [id] = requirePositionals(parsed, ['<id>'], 'fundus asset show');
+    const operations = await createOperations();
+    const state = await operations.state();
+    const asset = assetById(state, id);
+    if (parsed.flags.json) {
+        printJsonDocument({ ok: true, asset });
+        return;
+    }
+    printHumanAssetDetail(asset);
+}
+/**
+ * Infer the asset type from the file extension: unambiguous → that type;
+ * ambiguous (png: image/slice, mp4: video/chroma-key-video) → `--type` is
+ * required; unknown → list what the plugins accept.
+ */
+function inferTypeForFileName(fileName) {
+    const candidates = typesForFileName(fileName);
+    if (candidates.length === 1)
+        return candidates[0];
+    const extension = fileName.slice(fileName.lastIndexOf('.') + 1).toLowerCase();
+    if (candidates.length === 0) {
+        const knownExtensions = [
+            ...new Set(Object.values(pluginsByType).flatMap((plugin) => plugin.accepts))
+        ]
+            .sort()
+            .join(', ');
+        throw new Error(`No asset type accepts ".${extension}" files (accepted extensions: ${knownExtensions}).`);
+    }
+    throw new Error(`The ".${extension}" extension is ambiguous — pass --type <${candidates.join('|')}>.`);
+}
+async function runAssetIngest(argumentList) {
+    const parsed = parseArguments(argumentList, {
+        ...COMMON_FLAGS,
+        type: { takesValue: true },
+        id: { takesValue: true },
+        manifests: { takesValue: true },
+        parameters: { takesValue: true },
+        folder: { takesValue: true }
+    }, 'fundus asset ingest');
+    const [filePath] = requirePositionals(parsed, ['<file>'], 'fundus asset ingest');
+    const absolutePath = resolve(process.cwd(), filePath);
+    let bytes;
+    try {
+        bytes = new Uint8Array(await readFile(absolutePath));
+    }
+    catch {
+        throw new Error(`Cannot read file "${filePath}".`);
+    }
+    const fileName = basename(absolutePath);
+    const type = typeof parsed.flags.type === 'string' ? parsed.flags.type : inferTypeForFileName(fileName);
+    const id = typeof parsed.flags.id === 'string' ? parsed.flags.id : proposeAssetId(fileName);
+    const parametersPatch = typeof parsed.flags.parameters === 'string'
+        ? parseJsonFlag('parameters', parsed.flags.parameters)
+        : undefined;
+    const manifests = typeof parsed.flags.manifests === 'string'
+        ? parseManifestList(parsed.flags.manifests)
+        : undefined;
+    const folder = typeof parsed.flags.folder === 'string' ? parseFolderToken(parsed.flags.folder) : '';
+    const operations = await createOperations();
+    const state = await operations.ingest({
+        fileName,
+        bytes,
+        type,
+        id,
+        folder,
+        parametersPatch,
+        manifests
+    });
+    const asset = assetById(state, id);
+    if (parsed.flags.json) {
+        printJsonDocument({ ok: true, asset, issues: state.issues });
+        return;
+    }
+    printMutationResult(`Ingested "${fileName}" as ${type} asset "${id}".`, asset, state);
+}
+async function runAssetSet(argumentList) {
+    const parsed = parseArguments(argumentList, { ...COMMON_FLAGS, parameters: { takesValue: true }, manifests: { takesValue: true } }, 'fundus asset set');
+    const [id] = requirePositionals(parsed, ['<id>'], 'fundus asset set');
+    if (parsed.flags.parameters === undefined && parsed.flags.manifests === undefined) {
+        throw new CliUsageError('`fundus asset set` needs --parameters and/or --manifests — run `fundus asset set --help`.');
+    }
+    const parametersPatch = typeof parsed.flags.parameters === 'string'
+        ? parseJsonFlag('parameters', parsed.flags.parameters)
+        : undefined;
+    const manifests = typeof parsed.flags.manifests === 'string'
+        ? parseManifestList(parsed.flags.manifests)
+        : undefined;
+    const operations = await createOperations();
+    const state = await operations.setAsset(id, { parametersPatch, manifests });
+    const asset = assetById(state, id);
+    if (parsed.flags.json) {
+        printJsonDocument({ ok: true, asset, issues: state.issues });
+        return;
+    }
+    printMutationResult(`Updated asset "${id}".`, asset, state);
+}
+async function runAssetRename(argumentList) {
+    const parsed = parseArguments(argumentList, COMMON_FLAGS, 'fundus asset rename');
+    const [id, newId] = requirePositionals(parsed, ['<id>', '<newId>'], 'fundus asset rename');
+    const operations = await createOperations();
+    const state = await operations.renameAsset(id, newId);
+    const asset = assetById(state, newId);
+    if (parsed.flags.json) {
+        printJsonDocument({ ok: true, asset, issues: state.issues });
+        return;
+    }
+    printMutationResult(`Renamed asset "${id}" to "${newId}".`, asset, state);
+}
+function parseFolderToken(token) {
+    return token.toLocaleLowerCase('en-US') === 'root' ? '' : token;
+}
+async function runAssetMove(argumentList) {
+    const parsed = parseArguments(argumentList, COMMON_FLAGS, 'fundus asset move');
+    const [id, folderToken] = requirePositionals(parsed, ['<id>', '<folder|root>'], 'fundus asset move');
+    const operations = await createOperations();
+    const state = await operations.moveAsset(id, parseFolderToken(folderToken));
+    const asset = assetById(state, id);
+    if (parsed.flags.json) {
+        printJsonDocument({ ok: true, asset, issues: state.issues });
+        return;
+    }
+    printMutationResult(`Moved asset "${id}" to "${asset.folder || 'root'}".`, asset, state);
+}
+async function runAssetDelete(argumentList) {
+    const parsed = parseArguments(argumentList, COMMON_FLAGS, 'fundus asset delete');
+    const [id] = requirePositionals(parsed, ['<id>'], 'fundus asset delete');
+    const operations = await createOperations();
+    const state = await operations.deleteAsset(id, { failOnIntroducedIssues: true });
+    if (parsed.flags.json) {
+        printJsonDocument({ ok: true, deletedAssetId: id, issues: state.issues });
+        return;
+    }
+    printMutationResult(`Deleted asset "${id}" (record, raw file, proxies).`, null, state);
+}
+export async function runAssetCommand(argumentList) {
+    const [subcommand, ...rest] = argumentList;
+    if (subcommand === undefined || subcommand === '--help') {
+        console.log(ASSET_HELP);
+        if (subcommand === undefined) {
+            throw new CliUsageError('`fundus asset` needs a subcommand: list, show, ingest, set, rename, move, delete.');
+        }
+        return;
+    }
+    if (hasHelpFlag(rest)) {
+        // The focused per-subcommand page; the group overview for unknown ones.
+        console.log(ASSET_SUBCOMMAND_HELP[subcommand] ?? ASSET_HELP);
+        return;
+    }
+    switch (subcommand) {
+        case 'list':
+            return runAssetList(rest);
+        case 'show':
+            return runAssetShow(rest);
+        case 'ingest':
+            return runAssetIngest(rest);
+        case 'set':
+            return runAssetSet(rest);
+        case 'rename':
+            return runAssetRename(rest);
+        case 'move':
+            return runAssetMove(rest);
+        case 'delete':
+            return runAssetDelete(rest);
+        default:
+            throw new CliUsageError(`Unknown subcommand "asset ${subcommand}" — run \`fundus asset --help\`.`);
+    }
+}
+function folderRows(state) {
+    return [...state.library.folders].sort(compareCodeUnits).map((path) => ({
+        path,
+        name: folderNameOf(path),
+        parent: parentFolderPath(path),
+        directAssetIds: state.assets
+            .filter((asset) => asset.folder === path)
+            .map((asset) => asset.id)
+            .sort(compareCodeUnits)
+    }));
+}
+export const FOLDER_HELP = `fundus folder — manage the mirrored raw/proxy folder tree
+
+Usage: fundus folder <subcommand> …
+
+Subcommands:
+  list      list registered folders and their direct assets
+  create    create a persisted folder (fundus folder create <path>)
+  rename    rename one folder segment and its subtree
+  move      move a complete folder subtree below another folder
+  delete    recursively delete a folder subtree and its assets
+
+All mutations update rawDir and proxyDir together, maintain .gitkeep files,
+and run the full autosave chain. All subcommands accept --json and --help.
+`;
+const FOLDER_LIST_HELP = `fundus folder list — list registered folders
+
+Usage: fundus folder list [--json]
+
+Prints each folder path, parent, and direct assets. Root is implicit and is not
+included. Read-only: nothing is processed or written.
+
+Flags:
+  --json   print {"ok": true, "folders": […]}
+  --help   this help
+
+Example:
+  fundus folder list --json
+`;
+const FOLDER_CREATE_HELP = `fundus folder create — create a persisted folder
+
+Usage: fundus folder create <path> [--json]
+
+The parent must already exist (or be the implicit root). Creates matching raw
+and proxy directories with managed .gitkeep files.
+
+Flags:
+  --json   print the created folder row and issues
+  --help   this help
+
+Example:
+  fundus folder create "UI/Buttons" --json
+`;
+const FOLDER_RENAME_HELP = `fundus folder rename — rename a folder
+
+Usage: fundus folder rename <path> <newName> [--json]
+
+Renames only the final path segment, preserving the parent. Descendant folders,
+raw paths, proxy paths, and generated URLs move with it.
+
+Flags:
+  --json   print the renamed folder row and issues
+  --help   this help
+
+Example:
+  fundus folder rename "UI/Buttons" Controls --json
+`;
+const FOLDER_DELETE_HELP = `fundus folder delete — recursively delete a folder
+
+Usage: fundus folder delete <path> --recursive [--json]
+
+Deletes the complete subtree and all assets in it. --recursive is required to
+make this destructive operation explicit. External references to deleted assets
+are reported as validation issues after deletion.
+
+Flags:
+  --recursive   required destructive-operation acknowledgement
+  --json        print the deleted path and resulting issues
+  --help        this help
+
+Example:
+  fundus folder delete "UI/Obsolete" --recursive --json
+`;
+const FOLDER_MOVE_HELP = `fundus folder move — move a folder subtree
+
+Usage: fundus folder move <path> <parent|root> [--json]
+
+Moves the folder, every descendant folder, and all contained raw/proxy files
+below an existing parent. The folder keeps its name and cannot move into its
+own subtree. Use the literal "root" for the implicit root.
+
+Flags:
+  --json   print the moved folder row and issues
+  --help   this help
+
+Example:
+  fundus folder move "UI/Buttons" Shared --json
+`;
+const FOLDER_SUBCOMMAND_HELP = {
+    list: FOLDER_LIST_HELP,
+    create: FOLDER_CREATE_HELP,
+    rename: FOLDER_RENAME_HELP,
+    move: FOLDER_MOVE_HELP,
+    delete: FOLDER_DELETE_HELP
+};
+async function runFolderList(argumentList) {
+    const parsed = parseArguments(argumentList, COMMON_FLAGS, 'fundus folder list');
+    requirePositionals(parsed, [], 'fundus folder list');
+    const folders = folderRows(await (await createOperations()).state());
+    if (parsed.flags.json) {
+        printJsonDocument({ ok: true, folders });
+        return;
+    }
+    if (folders.length === 0) {
+        console.log('No folders.');
+        return;
+    }
+    for (const folder of folders) {
+        console.log(`${folder.path}  ${folder.directAssetIds.join(', ') || '(empty)'}`);
+    }
+}
+async function runFolderCreate(argumentList) {
+    const parsed = parseArguments(argumentList, COMMON_FLAGS, 'fundus folder create');
+    const [path] = requirePositionals(parsed, ['<path>'], 'fundus folder create');
+    const state = await (await createOperations()).createFolder(path);
+    const folder = folderRows(state).find((row) => row.path === path.normalize('NFC'));
+    if (parsed.flags.json) {
+        printJsonDocument({ ok: true, folder, issues: state.issues });
+        return;
+    }
+    printMutationResult(`Created folder "${folder?.path ?? path}".`, null, state);
+}
+async function runFolderRename(argumentList) {
+    const parsed = parseArguments(argumentList, COMMON_FLAGS, 'fundus folder rename');
+    const [path, newName] = requirePositionals(parsed, ['<path>', '<newName>'], 'fundus folder rename');
+    const state = await (await createOperations()).renameFolder(path, newName);
+    const nextPath = parentFolderPath(path) === '' ? newName : `${parentFolderPath(path)}/${newName}`;
+    const folder = folderRows(state).find((row) => row.path === nextPath.normalize('NFC'));
+    if (parsed.flags.json) {
+        printJsonDocument({ ok: true, folder, issues: state.issues });
+        return;
+    }
+    printMutationResult(`Renamed folder "${path}" to "${folder?.path ?? nextPath}".`, null, state);
+}
+async function runFolderMove(argumentList) {
+    const parsed = parseArguments(argumentList, COMMON_FLAGS, 'fundus folder move');
+    const [path, parentToken] = requirePositionals(parsed, ['<path>', '<parent|root>'], 'fundus folder move');
+    const parent = parseFolderToken(parentToken);
+    const state = await (await createOperations()).moveFolder(path, parent);
+    const nextPath = parent === '' ? folderNameOf(path) : `${parent}/${folderNameOf(path)}`;
+    const folder = folderRows(state).find((row) => row.path === nextPath.normalize('NFC'));
+    if (parsed.flags.json) {
+        printJsonDocument({ ok: true, folder, issues: state.issues });
+        return;
+    }
+    printMutationResult(`Moved folder "${path}" to "${folder?.path ?? nextPath}".`, null, state);
+}
+async function runFolderDelete(argumentList) {
+    const parsed = parseArguments(argumentList, { ...COMMON_FLAGS, recursive: { takesValue: false } }, 'fundus folder delete');
+    const [path] = requirePositionals(parsed, ['<path>'], 'fundus folder delete');
+    if (!parsed.flags.recursive) {
+        throw new CliUsageError('`fundus folder delete` requires --recursive because it deletes the subtree and its assets.');
+    }
+    const state = await (await createOperations()).deleteFolder(path);
+    if (parsed.flags.json) {
+        printJsonDocument({ ok: true, deletedFolderPath: path, issues: state.issues });
+        return;
+    }
+    printMutationResult(`Deleted folder "${path}" recursively.`, null, state);
+}
+export async function runFolderCommand(argumentList) {
+    const [subcommand, ...rest] = argumentList;
+    if (subcommand === undefined || subcommand === '--help') {
+        console.log(FOLDER_HELP);
+        if (subcommand === undefined) {
+            throw new CliUsageError('`fundus folder` needs a subcommand: list, create, rename, move, delete.');
+        }
+        return;
+    }
+    if (hasHelpFlag(rest)) {
+        console.log(FOLDER_SUBCOMMAND_HELP[subcommand] ?? FOLDER_HELP);
+        return;
+    }
+    switch (subcommand) {
+        case 'list':
+            return runFolderList(rest);
+        case 'create':
+            return runFolderCreate(rest);
+        case 'rename':
+            return runFolderRename(rest);
+        case 'move':
+            return runFolderMove(rest);
+        case 'delete':
+            return runFolderDelete(rest);
+        default:
+            throw new CliUsageError(`Unknown subcommand "folder ${subcommand}" — run \`fundus folder --help\`.`);
+    }
+}
+// ---------------------------------------------------------------------------
+// fundus manifest …
+// ---------------------------------------------------------------------------
+export const MANIFEST_HELP = `fundus manifest — manage manifests (delivery units & preload groups)
+
+Usage: fundus manifest <subcommand> …
+
+A manifest is a delivery unit and a preload group: only assets in at
+least one manifest (explicitly, or passively via the reference closure)
+are processed into proxies and reachable from host code. Assets join and
+leave manifests via \`fundus asset set <id> --manifests <a,b>\`. All
+subcommands accept --json and --help.
+
+Subcommands:
+  list      list manifests with members and delivered bytes
+  create    create an empty manifest (fundus manifest create <name>)
+  set       set a manifest's editor color / emoji appearance
+  palette   list the selectable appearance colors and emojis
+  rename    rename a manifest (fundus manifest rename <name> <newName>)
+  delete    delete a manifest and strip its memberships
+
+Run \`fundus manifest <subcommand> --help\` for the focused page.
+`;
+export const MANIFEST_LIST_HELP = `fundus manifest list — list manifests
+
+Usage: fundus manifest list [--json]
+
+One line per manifest: name, delivered bytes (the preload-budget
+number, over the full delivery set), explicit members, and passive
+members (assets pulled in via the reference closure, with via-
+attribution in the JSON output).
+
+Flags:
+  --json   print {"ok": true, "manifests": [{"name", "color", "emoji",
+           "explicitMemberIds", "passiveMembers", "deliveredBytes"}, …]}
+  --help   this help
+
+Read-only: nothing is processed or written.
+
+Example:
+  fundus manifest list --json
+`;
+export const MANIFEST_CREATE_HELP = `fundus manifest create — create an empty manifest
+
+Usage: fundus manifest create <name> [--json]
+
+<name> must be a camelCase identifier; its kebab-case form names the
+generated module (mainCatalog → main-catalog.generated.ts). Mutations run
+the autosave chain, so the module is generated immediately.
+
+Flags:
+  --json   print {"ok": true, "manifest": {…}, "issues": […]}
+  --help   this help
+
+Example:
+  fundus manifest create mainCatalog --json
+`;
+export const MANIFEST_RENAME_HELP = `fundus manifest rename — rename a manifest
+
+Usage: fundus manifest rename <name> <newName> [--json]
+
+<newName> must be a camelCase identifier whose kebab-case form is
+distinct from every other manifest's. The rename keeps the manifest's
+appearance, rewrites every asset's membership, and replaces the
+generated module (the old file is removed, the new one written). Host
+code importing the module must be updated by hand — both the module
+file name and the exported const change with the manifest name
+(mainCatalog → main-catalog.generated.ts / \`mainCatalog\`).
+
+Flags:
+  --json   print {"ok": true, "manifest": {…}, "issues": […]}
+  --help   this help
+
+Example:
+  fundus manifest rename mainCatalog primaryCatalog --json
+`;
+export const MANIFEST_DELETE_HELP = `fundus manifest delete — delete a manifest
+
+Usage: fundus manifest delete <name> [--json]
+
+Deletes the manifest, strips it from every asset's membership, and
+removes its generated module. Assets left in no manifest stop being
+delivered (they warn as unreachable).
+
+Flags:
+  --json   print {"ok": true, "deletedManifestName": "<name>", "issues": […]}
+  --help   this help
+
+Example:
+  fundus manifest delete obsoleteShelf --json
+`;
+export const MANIFEST_SET_HELP = `fundus manifest set — set a manifest's editor appearance
+
+Usage: fundus manifest set <name> [--color <name|hex|none>] [--emoji <emoji|none>] [--json]
+
+Tags the manifest with a color and/or an emoji, shown on its label
+throughout the editor UI. Both are chosen from the fixed sets below;
+pass "none" (or an empty string) to clear either. At least one of
+--color/--emoji is required. Runs the autosave chain.
+
+Colors (name or #hex):
+  ${MANIFEST_COLORS.map((color) => `${color.name} (${color.value})`).join(', ')}
+
+Emojis:
+  ${MANIFEST_EMOJIS.join(' ')}
+
+Flags:
+  --color <name|hex|none>  palette name ("blue"), hex value ("#3b82f6"),
+                           or "none"/"" to clear
+  --emoji <emoji|none>     one of the emojis above, or "none"/"" to clear
+  --json                   print the created/updated manifest row + issues
+  --help                   this help
+
+Example:
+  fundus manifest set mainCatalog --color blue --emoji 🗂️ --json
+`;
+export const MANIFEST_PALETTE_HELP = `fundus manifest palette — list the selectable appearance colors and emojis
+
+Usage: fundus manifest palette [--json]
+
+The closed sets \`fundus manifest set\` validates against. Read this first
+to discover valid --color / --emoji values programmatically instead of
+guessing.
+
+Flags:
+  --json   print {"ok": true, "colors": [{"name", "value"}, …], "emojis": […]}
+  --help   this help
+
+Read-only: nothing is processed or written.
+
+Example:
+  fundus manifest palette --json | jq '.emojis'
+`;
+const MANIFEST_SUBCOMMAND_HELP = {
+    list: MANIFEST_LIST_HELP,
+    create: MANIFEST_CREATE_HELP,
+    set: MANIFEST_SET_HELP,
+    palette: MANIFEST_PALETTE_HELP,
+    rename: MANIFEST_RENAME_HELP,
+    delete: MANIFEST_DELETE_HELP
+};
+async function runManifestList(argumentList) {
+    const parsed = parseArguments(argumentList, COMMON_FLAGS, 'fundus manifest list');
+    requirePositionals(parsed, [], 'fundus manifest list');
+    const operations = await createOperations();
+    const state = await operations.state();
+    const manifests = manifestRows(state);
+    if (parsed.flags.json) {
+        printJsonDocument({ ok: true, manifests });
+        return;
+    }
+    if (manifests.length === 0) {
+        console.log('No manifests.');
+        return;
+    }
+    const labels = manifests.map(manifestLabel);
+    const nameWidth = Math.max(0, ...labels.map((label) => label.length));
+    manifests.forEach((row, index) => {
+        const passiveSuffix = row.passiveMembers.length > 0
+            ? ` + passive: ${row.passiveMembers.map((member) => member.assetId).join(', ')}`
+            : '';
+        const colorSuffix = row.color ? `  ${row.color}` : '';
+        console.log(`${labels[index].padEnd(nameWidth)}  ${formatBytes(row.deliveredBytes).padStart(9)}  ` +
+            `${row.explicitMemberIds.join(', ') || '(empty)'}${passiveSuffix}${colorSuffix}`);
+    });
+}
+async function runManifestCreate(argumentList) {
+    const parsed = parseArguments(argumentList, COMMON_FLAGS, 'fundus manifest create');
+    const [name] = requirePositionals(parsed, ['<name>'], 'fundus manifest create');
+    const operations = await createOperations();
+    const state = await operations.createManifest(name);
+    const manifest = manifestRows(state).find((row) => row.name === name);
+    if (parsed.flags.json) {
+        printJsonDocument({ ok: true, manifest, issues: state.issues });
+        return;
+    }
+    printMutationResult(`Created manifest "${name}".`, null, state);
+}
+/** Resolve a `--color`/`--emoji` flag value to a set/clear/omit intent. */
+function resolveAppearanceFlag(value, resolve, describe) {
+    if (typeof value !== 'string')
+        return undefined;
+    const token = value.trim();
+    if (token === '' || token.toLowerCase() === 'none')
+        return null;
+    const resolved = resolve(token);
+    if (resolved === null)
+        throw new Error(describe(token));
+    return resolved;
+}
+async function runManifestSet(argumentList) {
+    const parsed = parseArguments(argumentList, { ...COMMON_FLAGS, color: { takesValue: true }, emoji: { takesValue: true } }, 'fundus manifest set');
+    const [name] = requirePositionals(parsed, ['<name>'], 'fundus manifest set');
+    if (parsed.flags.color === undefined && parsed.flags.emoji === undefined) {
+        throw new CliUsageError('`fundus manifest set` needs --color and/or --emoji — run `fundus manifest set --help`.');
+    }
+    const color = resolveAppearanceFlag(parsed.flags.color, resolveManifestColor, (token) => `"${token}" is not a selectable manifest color — choose one of: ` +
+        `${MANIFEST_COLORS.map((entry) => `${entry.name} (${entry.value})`).join(', ')}, or "none".`);
+    const emoji = resolveAppearanceFlag(parsed.flags.emoji, (token) => (manifestEmojiError(token) === null ? token : null), (token) => manifestEmojiError(token) ?? `"${token}" is not a selectable manifest emoji.`);
+    const operations = await createOperations();
+    const state = await operations.setManifestAppearance(name, { color, emoji });
+    const manifest = manifestRows(state).find((row) => row.name === name);
+    if (parsed.flags.json) {
+        printJsonDocument({ ok: true, manifest, issues: state.issues });
+        return;
+    }
+    printMutationResult(`Updated manifest "${name}" appearance.`, null, state);
+}
+async function runManifestPalette(argumentList) {
+    const parsed = parseArguments(argumentList, COMMON_FLAGS, 'fundus manifest palette');
+    requirePositionals(parsed, [], 'fundus manifest palette');
+    if (parsed.flags.json) {
+        printJsonDocument({ ok: true, colors: MANIFEST_COLORS, emojis: MANIFEST_EMOJIS });
+        return;
+    }
+    console.log('Colors:');
+    const nameWidth = Math.max(0, ...MANIFEST_COLORS.map((color) => color.name.length));
+    for (const color of MANIFEST_COLORS) {
+        console.log(`  ${color.name.padEnd(nameWidth)}  ${color.value}`);
+    }
+    console.log('');
+    console.log(`Emojis (${MANIFEST_EMOJIS.length}):`);
+    console.log(`  ${MANIFEST_EMOJIS.join(' ')}`);
+}
+async function runManifestRename(argumentList) {
+    const parsed = parseArguments(argumentList, COMMON_FLAGS, 'fundus manifest rename');
+    const [name, newName] = requirePositionals(parsed, ['<name>', '<newName>'], 'fundus manifest rename');
+    const operations = await createOperations();
+    const state = await operations.renameManifest(name, newName);
+    const manifest = manifestRows(state).find((row) => row.name === newName);
+    if (parsed.flags.json) {
+        printJsonDocument({ ok: true, manifest, issues: state.issues });
+        return;
+    }
+    printMutationResult(`Renamed manifest "${name}" to "${newName}" — update host imports of the generated module.`, null, state);
+}
+async function runManifestDelete(argumentList) {
+    const parsed = parseArguments(argumentList, COMMON_FLAGS, 'fundus manifest delete');
+    const [name] = requirePositionals(parsed, ['<name>'], 'fundus manifest delete');
+    const operations = await createOperations();
+    const state = await operations.deleteManifest(name);
+    if (parsed.flags.json) {
+        printJsonDocument({ ok: true, deletedManifestName: name, issues: state.issues });
+        return;
+    }
+    printMutationResult(`Deleted manifest "${name}" and stripped it from every asset.`, null, state);
+}
+export async function runManifestCommand(argumentList) {
+    const [subcommand, ...rest] = argumentList;
+    if (subcommand === undefined || subcommand === '--help') {
+        console.log(MANIFEST_HELP);
+        if (subcommand === undefined) {
+            throw new CliUsageError('`fundus manifest` needs a subcommand: list, create, set, palette, rename, delete.');
+        }
+        return;
+    }
+    if (hasHelpFlag(rest)) {
+        // See `runAssetCommand` for the focused-help dispatch rule.
+        console.log(MANIFEST_SUBCOMMAND_HELP[subcommand] ?? MANIFEST_HELP);
+        return;
+    }
+    switch (subcommand) {
+        case 'list':
+            return runManifestList(rest);
+        case 'create':
+            return runManifestCreate(rest);
+        case 'set':
+            return runManifestSet(rest);
+        case 'palette':
+            return runManifestPalette(rest);
+        case 'rename':
+            return runManifestRename(rest);
+        case 'delete':
+            return runManifestDelete(rest);
+        default:
+            throw new CliUsageError(`Unknown subcommand "manifest ${subcommand}" — run \`fundus manifest --help\`.`);
+    }
+}
+// ---------------------------------------------------------------------------
+// fundus build / fundus check (pipeline commands)
+// ---------------------------------------------------------------------------
+export const BUILD_HELP = `fundus build — run the headless pipeline
+
+Usage: fundus build [--json]
+
+Validates the library, processes every stale or missing proxy, prunes
+orphaned proxies, and regenerates all manifest modules. Deterministic
+and idempotent: a second run on an unchanged project processes nothing
+and rewrites byte-identical modules. Run it in CI, postinstall, or
+before the host build; commit the result.
+
+Flags:
+  --json   print {"ok": true, "processed": […], "upToDate": […],
+           "prunedProxies": […], "modulesWritten": […],
+           "modulesRemoved": […]} — asset ids for processing,
+           file names for pruning/codegen
+  --help   this help
+
+A validation failure processes nothing and exits 1 (with --json:
+{"error": {"message": …}}).
+
+Example:
+  fundus build --json | jq '.processed'
+`;
+export async function runBuildCommand(argumentList) {
+    if (hasHelpFlag(argumentList)) {
+        console.log(BUILD_HELP);
+        return;
+    }
+    const parsed = parseArguments(argumentList, COMMON_FLAGS, 'fundus build');
+    requirePositionals(parsed, [], 'fundus build');
+    const { processing, codegen } = await runBuild(process.cwd());
+    if (parsed.flags.json) {
+        printJsonDocument({
+            ok: true,
+            processed: processing.processed,
+            upToDate: processing.reused,
+            prunedProxies: processing.pruned,
+            modulesWritten: codegen.written,
+            modulesRemoved: codegen.removed
+        });
+        return;
+    }
+    console.log(`fundus build: ${processing.processed.length} processed, ${processing.reused.length} up to date, ` +
+        `${processing.pruned.length} pruned; ${codegen.written.length} manifest module(s) written` +
+        (codegen.removed.length > 0 ? `, ${codegen.removed.length} removed` : '') +
+        '.');
+}
+export const CHECK_HELP = `fundus check — verify the committed state (the CI gate)
+
+Usage: fundus check [--allow-warnings] [--json]
+
+Verify-only, no writes: the library must validate, every delivered
+asset's committed proxy must exist under its expected name (staleness
+is a name check), the proxy directory must hold no orphans, and every
+generated manifest module must be byte-identical to an in-memory
+regeneration. Warnings (unreachable asset, raw-hash drift) fail the
+check too unless --allow-warnings downgrades them; errors never
+downgrade.
+
+Flags:
+  --allow-warnings   exit 0 despite warnings (errors still fail)
+  --json             print one report document:
+                     {"ok": <pass/fail>, "assetCount": …, "manifestCount": …,
+                      "errors": [<finding>, …], "warnings": [<finding>, …]}
+                     where a finding is {"kind", "message"} plus
+                     "assetId" / "manifest" / "fileName" where applicable
+  --help             this help
+
+Exit codes: 0 = clean (or warnings allowed), 1 = failed. A failure to
+even run the check (e.g. no fundus.config.ts) exits 1 with the usual
+{"error": {"message": …}} envelope under --json.
+
+Example:
+  fundus check --json | jq '.errors[].kind'
+`;
+export async function runCheckCommand(argumentList) {
+    if (hasHelpFlag(argumentList)) {
+        console.log(CHECK_HELP);
+        return;
+    }
+    const parsed = parseArguments(argumentList, { ...COMMON_FLAGS, 'allow-warnings': { takesValue: false } }, 'fundus check');
+    requirePositionals(parsed, [], 'fundus check');
+    const allowWarnings = parsed.flags['allow-warnings'] === true;
+    const report = await runCheck(process.cwd());
+    const warningsFatal = report.warnings.length > 0 && !allowWarnings;
+    const failed = report.errors.length > 0 || warningsFatal;
+    if (parsed.flags.json) {
+        printJsonDocument({
+            ok: !failed,
+            assetCount: report.assetCount,
+            manifestCount: report.manifestCount,
+            errors: report.errors,
+            warnings: report.warnings
+        });
+        if (failed)
+            process.exitCode = 1;
+        return;
+    }
+    for (const error of report.errors) {
+        console.error(`✗ ${formatCheckFinding(error)}`);
+    }
+    for (const warning of report.warnings) {
+        console.error(`⚠ ${formatCheckFinding(warning)}`);
+    }
+    if (failed) {
+        console.error(`fundus check failed: ${report.errors.length} error(s), ${report.warnings.length} warning(s)` +
+            (warningsFatal ? ' (warnings are errors — pass --allow-warnings to downgrade them)' : '') +
+            '.');
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`fundus check: ${report.assetCount} asset(s), ${report.manifestCount} manifest(s) — clean` +
+        (report.warnings.length > 0 ? ` (${report.warnings.length} allowed warning(s))` : '') +
+        '.');
+}