@frontera-sdk/cli 1.52.38 → 1.52.40

package/src/commands/local/data.ts

@@ -3,7 +3,8 @@ import { join } from 'node:path'
 
 import { UsageError } from '../../errors'
 import { localProject } from '../../local/local-project'
-import { addMissingBackings, generateSyntheticData, loadScenario, SCENARIO_TEMPLATE } from '../../local/local-synthetic-data'
+import { isoDay, SAMPLE_OPTIONS_FILE, writeSampleOptions } from '../../local/local-sample-remake'
+import { addMissingBackings, generateSyntheticData, loadScenario, parseRegion, projectRegion, REGION_CODES, SCENARIO_CONTRACT, SCENARIO_TEMPLATE } from '../../local/local-synthetic-data'
 import { flagBool, flagString, type Command } from '../types'
 
 /**
@@ -17,11 +18,11 @@ export const localData: Command = {
     noun: 'local',
     verb: 'data',
     args: [],
-    flags: { synthetic: 'boolean', rows: 'string', seed: 'string' },
-    summary: "Generate sample data for the project's Blueprint (datasets/*.csv), with consistent links",
-    examples: ['frontera local data --synthetic', 'frontera local data --synthetic --rows 500 --seed 42'],
+    flags: { synthetic: 'boolean', rows: 'string', seed: 'string', region: 'string', today: 'string' },
+    summary: "Generate sample data for the project's Blueprint (datasets/*.csv; media-backed types get none), with consistent links",
+    details: SCENARIO_CONTRACT,
+    examples: ['frontera local data --synthetic', 'frontera local data --synthetic --rows 500 --seed 42', 'frontera local data --synthetic --region ID', 'frontera local data --synthetic --region 1.29,103.85,20', 'frontera local data --synthetic --today 2026-10-18'],
     offline: true,
-    internal: true,
   },
   async run(ctx) {
     if (!flagBool(ctx, 'synthetic')) throw new UsageError('say what to make', 'run `frontera local data --synthetic`')
@@ -29,7 +30,11 @@ export const localData: Command = {
     const seed = Number(flagString(ctx, 'seed') ?? 7)
     if (!Number.isInteger(rows) || rows < 1 || rows > 100_000) throw new UsageError('--rows takes a whole number from 1 to 100000', 'e.g. `frontera local data --synthetic --rows 500`')
     if (!Number.isInteger(seed)) throw new UsageError('--seed takes a whole number', 'e.g. `frontera local data --synthetic --seed 42`')
+    const regionFlag = flagString(ctx, 'region')
+    const parsed = regionFlag === undefined ? null : parseRegion(regionFlag)
+    if (regionFlag !== undefined && !parsed) throw new UsageError(`\`${regionFlag}\` is not a region`, `pass a country code (${REGION_CODES.join(', ')}), a locale such as id-ID, or <lat>,<lon>[,<radius km>]`)
     const project = localProject(ctx.cwd)
+    const region = parsed ?? projectRegion(project.root)
     if (!existsSync(join(project.root, 'blueprint', 'object-types'))) {
       throw new UsageError('this project has no Blueprint object types', 'pull them with `frontera local sync pull --kinds blueprint`, or add blueprint/object-types/<Name>.yaml')
     }
@@ -42,18 +47,34 @@ export const localData: Command = {
       wroteScenario = true
     }
     const backed = addMissingBackings(project.root)
+    // The day due dates are spread around; today (UTC) unless pinned, so a seed writes the same rows on any day.
+    const todayFlag = flagString(ctx, 'today')
+    const today = todayFlag === undefined ? undefined : new Date(`${todayFlag}T00:00:00Z`)
+    if (today && (!/^\d{4}-\d{2}-\d{2}$/.test(todayFlag!) || Number.isNaN(today.getTime()))) throw new UsageError('--today takes a date, YYYY-MM-DD', 'e.g. `frontera local data --synthetic --today 2026-10-18`')
     const scenario = await loadScenario(project.root, seed)
-    const made = generateSyntheticData(project.root, { rows, seed, scenario: scenario ?? undefined })
-    const total = made.reduce((n, m) => n + m.rows, 0)
+    // The day it ran on, unless pinned: kept with the seed and rows, so a remake after a pull writes the same rows.
+    const day = today ?? new Date(`${isoDay(new Date())}T00:00:00Z`)
+    const made = generateSyntheticData(project.root, { rows, seed, region, scenario: scenario ?? undefined, today: day })
+    writeSampleOptions(project.root, { seed, rows, today: isoDay(day), ...(regionFlag !== undefined ? { region: regionFlag } : {}), madeBy: 'local' })
+    // Datasets that aren't sample data (written, edited or loaded by someone) are left as they are.
+    const kept = made.filter((m) => m.kept)
+    const wrote = made.filter((m) => !m.kept)
+    const total = wrote.reduce((n, m) => n + m.rows, 0)
+    // A conditional field whose condition names nothing its record has: left empty, said with what to change.
+    const unresolved = wrote.flatMap((m) => (m.unresolved ?? []).map((u) => ({ objectType: m.objectType, ...u })))
     return {
-      data: { datasets: made, backings: backed, scenario: 'data/generate.ts', wroteScenario, rows: total, seed },
+      data: { datasets: wrote, ...(kept.length ? { kept: kept.map((m) => ({ objectType: m.objectType, dataset: m.dataset, rows: m.rows, csvPath: m.csvPath })) } : {}), backings: backed, ...(unresolved.length ? { unresolved } : {}), scenario: 'data/generate.ts', wroteScenario, rows: total, seed, region: { code: region.code, lat: region.lat, lon: region.lon, radiusKm: region.radiusKm } },
       text: [
-        `Wrote ${total} sample rows for ${made.length} object types (seed ${seed}):`,
-        ...made.map((m) => `  ${m.objectType.padEnd(24)} ${String(m.rows).padStart(6)}  ${m.csvPath}`),
+        `Wrote ${total} sample rows for ${wrote.length} object types (seed ${seed}; places within ${region.radiusKm} km of ${region.lat}, ${region.lon}${region.code === 'custom' ? '' : `, ${region.code}`}):`,
+        ...wrote.map((m) => `  ${m.objectType.padEnd(24)} ${String(m.rows).padStart(6)}  ${m.csvPath}`),
+        ...(kept.length
+          ? ['', `Kept ${kept.length} dataset${kept.length === 1 ? '' : 's'} that aren't sample data as they are (the sample rows link to their records):`, ...kept.map((m) => `  ${m.objectType.padEnd(24)} ${String(m.rows).padStart(6)}  ${m.csvPath}`)]
+          : []),
         ...(backed.length ? ['', `Gave ${backed.length} object type${backed.length === 1 ? '' : 's'} a dataset to read: ${backed.join(', ')}`] : []),
+        ...unresolved.map((u) => `  warning: ${u.objectType}.${u.property} is empty on every row: its description makes it depend on "${u.condition}", which names no property or value of ${u.objectType}. Name one in the description (a yes/no property, or a value such as a state), or set it with a field function in data/generate.ts`),
         '',
-        wroteScenario ? 'Adjust them in data/generate.ts (rows per type, values per property).' : 'Adjusted by data/generate.ts.',
-        '`frontera local dev` loads them into the runtime.',
+        wroteScenario ? 'Adjust them in data/generate.ts (rows per type, a `(row, index, ctx) => value` function per property; `frontera local data --help`).' : 'Adjusted by data/generate.ts (`frontera local data --help` describes it).',
+        `\`frontera local dev\` loads them into the runtime. Their options are kept in ${SAMPLE_OPTIONS_FILE}: a pull that brings Blueprint items makes them again the same way.`,
       ].join('\n'),
     }
   },