fimo 0.17.0 → 0.19.0

package/assets/skills/fimo-migration/scripts/apply-decision.mjs

@@ -0,0 +1,534 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+
+const MANIFEST_REL = '.fimo/migration/manifest.json';
+const DECISION_REL = '.fimo/migration/decision.json';
+const RUN_REL = '.fimo/migration/apply-run.json';
+// Entry lookup pages rather than filtering server-side because `slug` is entry
+// metadata, not a queryable schema field. The cap makes the script fail closed:
+// creating a second entry for a slug we could not prove absent would duplicate.
+const ENTRY_PAGE = 100;
+const MAX_ENTRY_SCAN = 2_000;
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const projectRoot = path.resolve(args.projectRoot ?? process.cwd());
+  const manifestPath = path.resolve(projectRoot, args.manifest ?? MANIFEST_REL);
+  const decisionPath = path.resolve(projectRoot, args.decision ?? DECISION_REL);
+  const runPath = path.resolve(projectRoot, RUN_REL);
+
+  const manifest = readJson(manifestPath);
+  const decision = readDecision(readJson(decisionPath), decisionPath);
+  const fimo = new Fimo(projectRoot, args.fimo ?? 'npx fimo@latest');
+  const uploads = new Map();
+  const phases = [];
+
+  const contentTypes = phase(phases, 'schemas', () => applySchemas(projectRoot, fimo, decision));
+  const media = phase(phases, 'media', () => applyAssets(fimo, decision, uploads, asArray(manifest.media)));
+  const collectionBatches = phase(phases, 'entries/references', () => applyEntries(fimo, decision, uploads));
+  const singleBatches = phase(phases, 'singles', () => applySingles(fimo, decision, uploads));
+  const labels = phase(phases, 'labels', () => applyLabels(fimo, decision));
+
+  const updated = {
+    ...manifest,
+    routes: decision.routes.map(routeItem),
+    contentTypes,
+    entries: [...collectionBatches, ...singleBatches],
+    labels,
+    media,
+    locales: decision.locales.map((locale) => ({
+      id: locale,
+      locale,
+      status: 'imported',
+      isDefault: locale === decision.defaultLocale,
+    })),
+    unresolved: decision.unresolved,
+  };
+
+  writeJsonFile(manifestPath, updated);
+  writeJsonFile(runPath, { version: 1, phases });
+
+  console.log(`Applied migration decision from ${path.relative(projectRoot, decisionPath)}`);
+  for (const item of phases) {
+    console.log(`  ${item.phase}: ${item.durationMs}ms`);
+  }
+}
+
+// ── CLI invocation ────────────────────────────────────────────────────────
+
+class Fimo {
+  constructor(projectRoot, invocation) {
+    const parts = invocation.trim().split(/\s+/).filter(Boolean);
+    if (parts.length === 0) {
+      fail('--fimo needs a CLI invocation, for example "npx fimo@latest".');
+    }
+    this.binary = parts[0];
+    this.prefix = parts.slice(1);
+    this.cwd = projectRoot;
+  }
+
+  run(args) {
+    const result = spawnSync(this.binary, [...this.prefix, '--json', ...args], {
+      cwd: this.cwd,
+      encoding: 'utf8',
+      maxBuffer: 64_000_000,
+    });
+    if (result.error) {
+      fail(`Could not run ${this.binary}: ${result.error.message}`);
+    }
+    const envelope = parseEnvelope(result.stdout);
+    if (result.status !== 0 || envelope?.status !== 'ok') {
+      const reason = envelope?.error?.message || result.stderr.trim() || result.stdout.trim() || 'no output';
+      fail(`fimo ${args.join(' ')} failed (exit ${result.status}): ${reason}`);
+    }
+    return envelope.data;
+  }
+}
+
+/** The CLI writes one envelope per command; tolerate leading diagnostic lines. */
+function parseEnvelope(stdout) {
+  const lines = String(stdout)
+    .split('\n')
+    .filter((line) => line.trim() !== '');
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    try {
+      const parsed = JSON.parse(lines[index]);
+      if (isRecord(parsed) && typeof parsed.status === 'string') {
+        return parsed;
+      }
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+// ── Phases ────────────────────────────────────────────────────────────────
+
+function applySchemas(projectRoot, fimo, decision) {
+  const items = [];
+  for (const definition of [...decision.collections, ...decision.singles]) {
+    const schemaFile = path.resolve(projectRoot, definition.schemaFile);
+    writeJsonFile(schemaFile, definition.schema);
+    fimo.run(['schemas', 'push', definition.schema.uid]);
+    items.push({
+      id: definition.id,
+      uid: definition.schema.uid,
+      name: definition.schema.name ?? definition.schema.uid,
+      status: 'imported',
+      sourceFiles: asArray(definition.sourceFiles),
+      targetFiles: [toPosix(definition.schemaFile)],
+      fields: definition.schema.fields ?? {},
+    });
+  }
+  return items;
+}
+
+function applyAssets(fimo, decision, uploads, previousMedia) {
+  const alreadyUploaded = new Map(previousMedia.map((item) => [item.id, item.targetAssetId]));
+  const items = [];
+  for (const asset of decision.assets) {
+    const name = asset.name ?? path.posix.basename(toPosix(asset.sourcePath));
+    const existing = findAsset(fimo, name, alreadyUploaded.get(asset.id));
+    const stored = existing ?? unwrapData(fimo.run(['assets', 'upload', asset.sourcePath, '--name', name]));
+    if (!isRecord(stored) || typeof stored.id !== 'string' || typeof stored.url !== 'string') {
+      fail(`Asset upload did not return an id and url: ${asset.id}`);
+    }
+    uploads.set(asset.id, { url: stored.url, alt: asset.alt ?? null });
+    items.push({
+      id: asset.id,
+      status: 'imported',
+      sourcePath: toPosix(asset.sourcePath),
+      targetAssetId: stored.id,
+      targetUrl: stored.url,
+      alt: asset.alt ?? null,
+      referencedBy: asArray(asset.referencedBy),
+      uploadError: null,
+    });
+  }
+  return items;
+}
+
+function applyEntries(fimo, decision, uploads) {
+  return decision.collections.map((collection) => {
+    const uid = collection.schema.uid;
+    const localized = collection.schema.i18n?.enabled !== false;
+    const sourceFiles = new Set(asArray(collection.sourceFiles));
+    let imported = 0;
+
+    for (const document of collection.documents) {
+      const locales = orderedLocales(document.locales, decision);
+      assertLocalePayloads(uid, document.slug, locales, decision.defaultLocale, localized);
+      const existingByLocale = new Map(
+        locales.map((locale) => [locale, findEntry(fimo, uid, localized ? locale : null, document.slug)])
+      );
+      let documentId = localized ? entryDocumentId(existingByLocale.get(locales[0])) : null;
+
+      if (localized) {
+        for (const locale of locales.slice(1)) {
+          const existing = existingByLocale.get(locale);
+          if (!existing) {
+            continue;
+          }
+          const localizedDocumentId = entryDocumentId(existing);
+          if (!documentId || localizedDocumentId !== documentId) {
+            fail(
+              `Existing localized entry ${uid}/${document.slug} (${locale}) has documentId ` +
+                `${localizedDocumentId ?? '(missing)'}, expected ${documentId ?? '(missing default-locale documentId)'}.`
+            );
+          }
+        }
+      }
+
+      for (const locale of locales) {
+        // Without the default locale's document id every later locale becomes a
+        // separate document, which is a silent duplicate rather than an error.
+        if (locale !== locales[0] && !documentId) {
+          fail(`Could not resolve the ${locales[0]} document id for ${uid}/${document.slug}.`);
+        }
+        const payload = document.locales[locale];
+        if (payload.sourceFile) {
+          sourceFiles.add(toPosix(payload.sourceFile));
+        }
+        const body = JSON.stringify({
+          data: { slug: document.slug, ...resolveAssets(payload.data, uploads) },
+        });
+        const existing = existingByLocale.get(locale);
+        const localeArgs = localized ? ['--locale', locale] : [];
+        const entry = existing
+          ? fimo.run(['entries', 'update', uid, existing.id, ...localeArgs, '--body', body])
+          : fimo.run([
+              'entries',
+              'create',
+              uid,
+              ...localeArgs,
+              ...(localized && documentId ? ['--document-id', documentId] : []),
+              '--body',
+              body,
+            ]);
+        documentId ??= entryDocumentId(entry);
+        imported += 1;
+      }
+    }
+
+    const sourceCount = collection.documents.reduce(
+      (total, document) => total + Object.keys(document.locales).length,
+      0
+    );
+    return {
+      id: `${collection.id}-entries`,
+      contentType: uid,
+      status: 'imported',
+      sourceFiles: [...sourceFiles].sort(compareStrings),
+      sourceCount,
+      generatedCount: sourceCount,
+      importedCount: imported,
+      skipped: [],
+    };
+  });
+}
+
+function applySingles(fimo, decision, uploads) {
+  return decision.singles.map((single) => {
+    const uid = single.schema.uid;
+    const localized = single.schema.i18n?.enabled !== false;
+    const sourceFiles = new Set(asArray(single.sourceFiles));
+    let imported = 0;
+
+    const locales = orderedLocales(single.locales, decision);
+    assertLocalePayloads(uid, single.id, locales, decision.defaultLocale, localized);
+    for (const locale of locales) {
+      const payload = single.locales[locale];
+      if (payload.sourceFile) {
+        sourceFiles.add(toPosix(payload.sourceFile));
+      }
+      fimo.run([
+        'singles',
+        'update',
+        uid,
+        ...(localized ? ['--locale', locale] : []),
+        '--body',
+        JSON.stringify({ data: resolveAssets(payload.data, uploads) }),
+      ]);
+      imported += 1;
+    }
+
+    const sourceCount = Object.keys(single.locales).length;
+    return {
+      id: `${single.id}-content`,
+      contentType: uid,
+      status: 'imported',
+      sourceFiles: [...sourceFiles].sort(compareStrings),
+      sourceCount,
+      generatedCount: sourceCount,
+      importedCount: imported,
+      skipped: [],
+    };
+  });
+}
+
+function applyLabels(fimo, decision) {
+  const byLocale = new Map();
+  for (const label of decision.labels) {
+    for (const [locale, value] of Object.entries(label.values)) {
+      byLocale.set(locale, { ...(byLocale.get(locale) ?? {}), [label.key]: value });
+    }
+  }
+  for (const [locale, values] of [...byLocale.entries()].sort(([left], [right]) => compareStrings(left, right))) {
+    fimo.run(['labels', 'set-many', '--locale', locale, '--data', JSON.stringify(values)]);
+  }
+  return decision.labels.map((label) => ({
+    id: label.id,
+    key: label.key,
+    status: 'imported',
+    locales: Object.keys(label.values).sort(compareStrings),
+    sourceFiles: asArray(label.sourceFiles),
+  }));
+}
+
+// ── Create-or-update lookups ──────────────────────────────────────────────
+
+/**
+ * The previously recorded target id is the primary key, so a rerun stays
+ * idempotent even if the media library normalized the display name on upload.
+ * The name match only has to catch a first run against an already-seeded
+ * library.
+ */
+function findAsset(fimo, name, previousAssetId) {
+  const listed = pluckArray(fimo.run(['assets', 'list', '--type', 'file', '--search', name, '--limit', '100']))
+    .filter(isRecord)
+    .filter((item) => typeof item.id === 'string' && typeof item.url === 'string');
+  return (
+    listed.find((item) => previousAssetId && item.id === previousAssetId) ??
+    listed.find((item) => item.name === name || item.filename === name) ??
+    null
+  );
+}
+
+function findEntry(fimo, uid, locale, slug) {
+  for (let offset = 0; offset < MAX_ENTRY_SCAN; offset += ENTRY_PAGE) {
+    const page = pluckArray(
+      fimo.run([
+        'entries',
+        'list',
+        uid,
+        ...(locale ? ['--locale', locale] : []),
+        '--limit',
+        String(ENTRY_PAGE),
+        '--offset',
+        String(offset),
+      ])
+    );
+    const match = page.find((item) => isRecord(item) && item.slug === slug && typeof item.id === 'string');
+    if (match) {
+      return match;
+    }
+    if (page.length < ENTRY_PAGE) {
+      return null;
+    }
+  }
+  fail(`${uid} has more than ${MAX_ENTRY_SCAN} entries; cannot prove ${slug} (${locale}) is absent.`);
+}
+
+function entryDocumentId(entry) {
+  return isRecord(entry) && typeof entry.documentId === 'string' ? entry.documentId : null;
+}
+
+// ── Decision reading ──────────────────────────────────────────────────────
+
+function readDecision(input, decisionPath) {
+  if (!isRecord(input) || input.version !== 1) {
+    fail(`Invalid migration decision (expected version 1): ${decisionPath}`);
+  }
+  const decision = {
+    defaultLocale: typeof input.defaultLocale === 'string' ? input.defaultLocale : 'en',
+    locales: asArray(input.locales).filter((locale) => typeof locale === 'string'),
+    labels: asArray(input.labels),
+    assets: asArray(input.assets),
+    collections: asArray(input.collections),
+    singles: asArray(input.singles),
+    routes: asArray(input.routes),
+    unresolved: asArray(input.unresolved),
+  };
+  if (decision.locales.length === 0) {
+    decision.locales = [decision.defaultLocale];
+  }
+
+  for (const definition of [...decision.collections, ...decision.singles]) {
+    if (!isRecord(definition.schema) || typeof definition.schema.uid !== 'string') {
+      fail(`Every collection and single needs a schema with a uid: ${definition.id ?? '(missing id)'}`);
+    }
+    if (typeof definition.schemaFile !== 'string') {
+      fail(`Every collection and single needs a schemaFile: ${definition.schema.uid}`);
+    }
+  }
+  for (const label of decision.labels) {
+    if (typeof label.key !== 'string' || !isRecord(label.values)) {
+      fail(`Every label needs a key and per-locale values: ${label.id ?? '(missing id)'}`);
+    }
+  }
+  for (const item of decision.unresolved) {
+    if (!item.message || !item.suggestedAction) {
+      fail(`Every unresolved item needs a message and a suggestedAction: ${item.id ?? '(missing id)'}`);
+    }
+  }
+  return decision;
+}
+
+/**
+ * The default locale is applied first so the localized variants can reuse its
+ * `documentId`; without that they become separate documents.
+ */
+function orderedLocales(locales, decision) {
+  const present = Object.keys(locales);
+  const unknown = present.filter((locale) => !decision.locales.includes(locale));
+  if (unknown.length > 0) {
+    fail(`Decision uses locales that are not declared: ${unknown.sort(compareStrings).join(', ')}`);
+  }
+  return present.sort((left, right) => {
+    if (left === decision.defaultLocale) return -1;
+    if (right === decision.defaultLocale) return 1;
+    return compareStrings(left, right);
+  });
+}
+
+function assertLocalePayloads(uid, itemId, locales, defaultLocale, localized) {
+  if (locales.length === 0) {
+    fail(`${uid}/${itemId} needs at least one locale payload.`);
+  }
+  if (!locales.includes(defaultLocale)) {
+    fail(`${uid}/${itemId} needs a ${defaultLocale} default-locale payload.`);
+  }
+  if (!localized && (locales.length !== 1 || locales[0] !== defaultLocale)) {
+    fail(`${uid}/${itemId} is shared and needs exactly one ${defaultLocale} payload.`);
+  }
+}
+
+function resolveAssets(value, uploads) {
+  if (Array.isArray(value)) {
+    return value.map((item) => resolveAssets(item, uploads));
+  }
+  if (!isRecord(value)) {
+    return value;
+  }
+  if (typeof value.$asset === 'string') {
+    const uploaded = uploads.get(value.$asset);
+    if (!uploaded) {
+      fail(`Decision references an asset that is not declared: ${value.$asset}`);
+    }
+    const alt = value.alt ?? uploaded.alt;
+    return { source: 'local', url: uploaded.url, ...(alt ? { alt } : {}) };
+  }
+  return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, resolveAssets(item, uploads)]));
+}
+
+function routeItem(route) {
+  return {
+    id: route.id,
+    route: route.route,
+    // A route lands in the target as application code, so writing its module is
+    // the import. `generated` is reserved for artifacts still outside Fimo.
+    status: route.status ?? 'imported',
+    sourceFiles: asArray(route.sourceFiles),
+    targetFiles: asArray(route.targetFiles),
+  };
+}
+
+// ── Utilities ─────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const args = {};
+  const named = { '--manifest': 'manifest', '--decision': 'decision', '--fimo': 'fimo' };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--help' || arg === '-h') {
+      console.log(
+        'Usage: node apply-decision.mjs [project-root] [--decision .fimo/migration/decision.json] ' +
+          '[--manifest .fimo/migration/manifest.json] [--fimo "npx fimo@latest"]'
+      );
+      process.exit(0);
+    }
+    const inlined = Object.keys(named).find((flag) => arg.startsWith(`${flag}=`));
+    if (inlined) {
+      args[named[inlined]] = arg.slice(inlined.length + 1);
+      continue;
+    }
+    if (named[arg]) {
+      args[named[arg]] = argv[++index];
+      continue;
+    }
+    if (!args.projectRoot) {
+      args.projectRoot = arg;
+      continue;
+    }
+    fail(`Unknown argument: ${arg}`);
+  }
+  return args;
+}
+
+function phase(phases, name, run) {
+  const started = Date.now();
+  const value = run();
+  phases.push({ phase: name, durationMs: Date.now() - started });
+  return value;
+}
+
+function unwrapData(value) {
+  return isRecord(value) && isRecord(value.data) ? value.data : value;
+}
+
+function pluckArray(value) {
+  if (Array.isArray(value)) {
+    return value;
+  }
+  if (isRecord(value)) {
+    for (const key of ['data', 'items', 'results']) {
+      if (Array.isArray(value[key])) {
+        return value[key];
+      }
+    }
+  }
+  return [];
+}
+
+function readJson(filePath) {
+  if (!fs.existsSync(filePath)) {
+    fail(`File not found: ${filePath}`);
+  }
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    fail(`Could not parse ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function writeJsonFile(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function compareStrings(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function toPosix(value) {
+  return String(value).split(path.sep).join('/');
+}
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+main();

package/assets/skills/fimo-migration/scripts/build-canonical-manifest.mjs

@@ -29,7 +29,8 @@ function main() {
 
   if (!urlLedger && !sourceLedger) {
     fail(
-      `No migration ledgers found in ${projectRoot}. Expected .fimo/migrations/current/manifest.json or .fimo/source-migration/manifest.json.`
+      `No migration ledgers found in ${projectRoot}. Expected .fimo/migrations/current/manifest.json or .fimo/source-migration/manifest.json. ` +
+        'This script only merges existing draft ledgers; for a fresh source-backed migration write .fimo/migration/manifest.json directly following references/manifest.md.'
     );
   }
 
@@ -83,7 +84,7 @@ function parseArgs(argv) {
 }
 
 function buildCanonicalManifest({ projectRoot, urlLedger, urlLedgerPath, sourceLedger, sourceLedgerPath, previous }) {
-  const source = buildSource({ urlLedger, urlLedgerPath, sourceLedger, sourceLedgerPath, projectRoot });
+  const source = buildSource({ urlLedger, urlLedgerPath, sourceLedger, sourceLedgerPath, projectRoot, previous });
   const routes = applyGeneratedRouteArtifacts(
     projectRoot,
     mergeItems([...normalizeSourceRoutes(sourceLedger?.routes), ...normalizeUrlRoutes(urlLedger?.pages)])
@@ -123,19 +124,21 @@ function buildCanonicalManifest({ projectRoot, urlLedger, urlLedgerPath, sourceL
   return preservePreviousProgress(manifest, previous);
 }
 
-function buildSource({ urlLedger, urlLedgerPath, sourceLedger, sourceLedgerPath, projectRoot }) {
+function buildSource({ urlLedger, urlLedgerPath, sourceLedger, sourceLedgerPath, projectRoot, previous }) {
   const hasUrl = Boolean(urlLedger);
   const hasSource = Boolean(sourceLedger);
   const sourceLedgers = [];
   if (hasUrl) sourceLedgers.push(toPosix(path.relative(projectRoot, urlLedgerPath)));
   if (hasSource) sourceLedgers.push(toPosix(path.relative(projectRoot, sourceLedgerPath)));
 
+  const cli = sourceLedger?.source?.cli ?? urlLedger?.source?.cli ?? previous?.source?.cli;
+
   return {
     mode: hasUrl && hasSource ? 'hybrid' : hasSource ? 'source-backed' : 'url-only',
     platform: sourceLedger?.source?.platform ?? urlLedger?.source?.platform ?? 'unknown',
     publicUrl: sourceLedger?.source?.publicUrl ?? urlLedger?.source?.url ?? null,
     rootPath: sourceLedger?.source?.rootPath ?? null,
-    inventoryPath: sourceLedger?.source?.inventoryPath ?? null,
+    ...(cli ? { cli } : {}),
     sourceLedgers,
   };
 }