@syncular/typegen 0.1.3 → 0.2.0

package/dist/cli.js

@@ -1,88 +1,174 @@
 #!/usr/bin/env bun
-import { readFile } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { loadSyncularClientContract, toSyncularCodegenJson, writeSyncularCodegenJsonFromModule, } from './app-contract.js';
-async function main(argv) {
-    const command = argv[0];
-    if (command !== 'codegen-config') {
-        printUsageAndExit(command ? `Unknown command ${command}` : undefined);
-    }
-    const options = parseCodegenConfigArgs(argv.slice(1));
-    if (options.check) {
-        const contract = await loadSyncularClientContract({
-            modulePath: options.app,
-            exportName: options.exportName,
-        });
-        const expected = toSyncularCodegenJson(contract);
-        const actual = await readFile(options.out, 'utf8').catch((error) => {
-            throw new Error(`Cannot read ${options.out}; run without --check to generate it first: ${error.message}`);
-        });
-        if (actual !== expected) {
-            throw new Error(`${options.out} does not match ${options.app}; run syncular generate --app ${options.app}`);
-        }
-        return;
-    }
-    await writeSyncularCodegenJsonFromModule({
-        modulePath: options.app,
-        exportName: options.exportName,
-        outputPath: options.out,
-    });
+/**
+ * The `syncular` CLI. Subcommands:
+ *
+ *   generate [--manifest-dir <dir>] [--check] [--watch]
+ *     Reads `syncular.json` + `migrations/` under the manifest dir and writes
+ *     the neutral IR JSON and generated TS module (paths from the manifest's
+ *     `output`). `--check` regenerates in memory and fails (exit 1) unless the
+ *     files on disk match byte-exactly. `--watch` regenerates on change.
+ *
+ *   init [--manifest-dir <dir>]
+ *     Drops a starter `syncular.json` + `migrations/0001_initial` into an
+ *     existing project (the "add syncular to my app" path).
+ *
+ * The generate CONTRACT (inputs, outputs, byte-exact `--check`) is unchanged;
+ * this file only adds `init`, `--watch`, and friendlier errors.
+ */
+import { watch } from 'node:fs';
+import { resolve } from 'node:path';
+import { checkOutputs, generate, writeOutputs } from './generate.js';
+import { InitError, initProject } from './init.js';
+import { MANIFEST_FILENAME } from './manifest.js';
+const DOCS_HINT = 'See the schema guide: https://github.com/bkniffler/syncular (guide-schema), ' +
+    'or run `syncular init` to scaffold a starter manifest + migration.';
+const USAGE = `usage: syncular <command> [options]
+
+commands:
+  generate   build the IR + typed module from syncular.json + migrations/
+  init       scaffold a starter syncular.json + migrations/0001_initial
+
+generate options:
+  --manifest-dir <dir>   directory holding syncular.json (default: .)
+  --check                fail unless generated files are byte-exactly fresh
+  --watch                regenerate on file change (Ctrl-C to stop)
+
+init options:
+  --manifest-dir <dir>   directory to scaffold into (default: .)`;
+function fail(message) {
+    console.error(message);
+    process.exit(1);
 }
-function parseCodegenConfigArgs(args) {
-    let app;
-    let out;
-    let exportName;
-    let check = false;
-    for (let index = 0; index < args.length; index += 1) {
-        const arg = args[index];
-        if (arg === '--app') {
-            app = requireValue(args, (index += 1), '--app');
+function parseGenerateArgs(argv) {
+    const args = { manifestDir: '.', check: false, watch: false };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--check') {
+            args.check = true;
         }
-        else if (arg === '--out') {
-            out = requireValue(args, (index += 1), '--out');
+        else if (arg === '--watch') {
+            args.watch = true;
         }
-        else if (arg === '--export') {
-            exportName = requireValue(args, (index += 1), '--export');
+        else if (arg === '--manifest-dir') {
+            const value = argv[i + 1];
+            if (value === undefined)
+                fail('--manifest-dir requires a value');
+            args.manifestDir = value;
+            i += 1;
         }
-        else if (arg === '--check') {
-            check = true;
+        else {
+            fail(`unknown argument ${JSON.stringify(arg)}\n${USAGE}`);
         }
-        else if (arg === '--help' || arg === '-h') {
-            printUsageAndExit();
+    }
+    if (args.check && args.watch) {
+        fail('--check and --watch cannot be combined');
+    }
+    return args;
+}
+function parseManifestDir(argv) {
+    let manifestDir = '.';
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--manifest-dir') {
+            const value = argv[i + 1];
+            if (value === undefined)
+                fail('--manifest-dir requires a value');
+            manifestDir = value;
+            i += 1;
         }
         else {
-            printUsageAndExit(`Unknown option ${arg}`);
+            fail(`unknown argument ${JSON.stringify(arg)}\n${USAGE}`);
         }
     }
-    if (!app)
-        printUsageAndExit('Missing --app');
-    return {
-        app,
-        out: out ?? defaultCodegenConfigPath(app),
-        exportName,
-        check,
-    };
+    return manifestDir;
 }
-function defaultCodegenConfigPath(app) {
-    const appPath = app.startsWith('file:') ? fileURLToPath(app) : app;
-    return join(dirname(appPath), 'generated', 'syncular.codegen.json');
+/** Add a docs pointer to the fail-loud missing-input errors. */
+function friendlyGenerateError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.includes('manifest not found') ||
+        message.includes('migrations directory does not exist') ||
+        message.includes('no migrations found')) {
+        return `${message}\n${DOCS_HINT}`;
+    }
+    return message;
 }
-function requireValue(args, index, option) {
-    const value = args[index];
-    if (!value || value.startsWith('--')) {
-        printUsageAndExit(`${option} requires a value`);
+function runGenerateOnce(args) {
+    let result;
+    try {
+        result = generate(args.manifestDir);
+    }
+    catch (error) {
+        fail(friendlyGenerateError(error));
+    }
+    if (args.check) {
+        const drift = checkOutputs(result);
+        if (drift.length > 0) {
+            fail(`generated output is out of date:\n${drift.join('\n')}`);
+        }
+        console.log('generated output is up to date');
+        return;
+    }
+    writeOutputs(result);
+    for (const output of result.outputs) {
+        console.log(`wrote ${output.path}`);
+    }
+}
+/** `--watch`: regenerate on any change under the manifest dir. Uses Bun's
+ * `fs.watch` recursively; debounced so a burst of writes triggers one run. */
+function runGenerateWatch(args) {
+    const dir = resolve(args.manifestDir);
+    const safeRun = () => {
+        try {
+            const result = generate(args.manifestDir);
+            // Skip the write when the outputs are already fresh — otherwise writing
+            // them (they live under the watched dir) would re-trigger the watcher in
+            // a loop.
+            if (checkOutputs(result).length === 0)
+                return;
+            writeOutputs(result);
+            console.log(`regenerated ${result.modulePath}`);
+        }
+        catch (error) {
+            // In watch mode a bad intermediate state is expected — report, don't die.
+            console.error(friendlyGenerateError(error));
+        }
+    };
+    safeRun();
+    console.log(`watching ${dir} for changes (Ctrl-C to stop)…`);
+    let timer;
+    watch(dir, { recursive: true }, () => {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = setTimeout(safeRun, 50);
+    });
+}
+export function runCli(argv) {
+    const command = argv[0];
+    if (command === 'generate') {
+        const args = parseGenerateArgs(argv.slice(1));
+        if (args.watch) {
+            runGenerateWatch(args);
+            return;
+        }
+        runGenerateOnce(args);
+        return;
+    }
+    if (command === 'init') {
+        const dir = parseManifestDir(argv.slice(1));
+        try {
+            const result = initProject(dir);
+            for (const path of result.written)
+                console.log(`wrote ${path}`);
+            console.log('\nNext: `syncular generate` to build the typed schema, then wire ' +
+                `${MANIFEST_FILENAME}'s "output.module" into your server + client.`);
+        }
+        catch (error) {
+            fail(error instanceof InitError ? error.message : String(error));
+        }
+        return;
     }
-    return value;
+    fail(USAGE);
 }
-function printUsageAndExit(message) {
-    if (message)
-        console.error(message);
-    console.error([
-        'Usage:',
-        '  syncular-typegen codegen-config --app ./syncular.app.ts [--out ./generated/syncular.codegen.json] [--export app] [--check]',
-    ].join('\n'));
-    process.exit(message ? 1 : 0);
+if (import.meta.main) {
+    runCli(process.argv.slice(2));
 }
-await main(process.argv.slice(2));
-//# sourceMappingURL=cli.js.map

package/dist/emit-dart.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Dart emitter: neutral IR → one standalone `.dart` file exporting
+ *
+ * - `const syncularSchema` — the ServerSchema-compatible `Map<String,
+ *   Object?>` built from the IR (fed straight into `SyncularClient.create(
+ *   schema: …)`),
+ * - one class per table with typed fields (per the six §2.4 column types +
+ *   blob_ref/crdt) and a `fromRow(Map<String, Object?>)` factory,
+ * - a `syncular<Name>Subscription` helper per subscription with a typed
+ *   `scopes(...)` builder.
+ *
+ * The row shape is `Map<String, Object?>` — the exact type the Dart wrapper's
+ * `query`/`readRows` return. The header carries the IR hash so `--check`
+ * verifies freshness byte-exactly.
+ */
+import type { IrDocument } from './ir.js';
+export declare function emitDartModule(ir: IrDocument, hash: string): string;

package/dist/emit-dart.js

@@ -0,0 +1,201 @@
+/** §2.4 column type → honest Dart type. `json`/`blob_ref` are the raw
+ * canonical JSON string; `bytes`/`crdt` are opaque `List<int>`. */
+const DART_TYPE = {
+    string: 'String',
+    integer: 'int',
+    float: 'double',
+    boolean: 'bool',
+    json: 'String',
+    bytes: 'List<int>',
+    blob_ref: 'String',
+    crdt: 'List<int>',
+};
+/** §5.11: app-side Dart type — declaredType for an encrypted column. */
+function appDartType(column) {
+    const type = column.encrypted === true && column.declaredType !== undefined
+        ? column.declaredType
+        : column.type;
+    return DART_TYPE[type];
+}
+function pascalCase(name) {
+    return name
+        .split(/[_-]+/)
+        .filter((part) => part.length > 0)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join('');
+}
+function camelCase(name) {
+    const pascal = pascalCase(name);
+    return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+}
+function quote(value) {
+    return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\$/g, '\\$')}'`;
+}
+function emitSchemaValue(ir, indent) {
+    const lines = [];
+    const i = indent;
+    lines.push(`${i}<String, Object?>{`);
+    lines.push(`${i}  'version': ${ir.schemaVersion},`);
+    lines.push(`${i}  'tables': [`);
+    for (const table of ir.tables) {
+        lines.push(`${i}    {`);
+        lines.push(`${i}      'name': ${quote(table.name)},`);
+        lines.push(`${i}      'primaryKey': ${quote(table.primaryKey)},`);
+        lines.push(`${i}      'columns': [`);
+        for (const column of table.columns) {
+            const parts = [
+                `'name': ${quote(column.name)}`,
+                `'type': ${quote(column.type)}`,
+                `'nullable': ${column.nullable}`,
+            ];
+            if (column.crdtType !== undefined) {
+                parts.push(`'crdtType': ${quote(column.crdtType)}`);
+            }
+            if (column.encrypted === true) {
+                parts.push("'encrypted': true");
+                parts.push(`'declaredType': ${quote(column.declaredType ?? column.type)}`);
+            }
+            lines.push(`${i}        {${parts.join(', ')}},`);
+        }
+        lines.push(`${i}      ],`);
+        lines.push(`${i}      'scopes': [`);
+        for (const scope of table.scopes) {
+            lines.push(`${i}        {'pattern': ${quote(scope.pattern)}, 'column': ${quote(scope.column)}},`);
+        }
+        lines.push(`${i}      ],`);
+        lines.push(`${i}    },`);
+    }
+    lines.push(`${i}  ],`);
+    lines.push(`${i}}`);
+    return lines;
+}
+/** The accessor lifting a §2.4 value out of a `Map<String, Object?>` row. */
+function rowAccessor(column) {
+    const key = `row[${quote(column.name)}]`;
+    switch (column.type) {
+        case 'string':
+        case 'json':
+        case 'blob_ref':
+            return `${key} as String?`;
+        case 'integer':
+            return `(${key} as num?)?.toInt()`;
+        case 'float':
+            return `(${key} as num?)?.toDouble()`;
+        case 'boolean':
+            return `_rowBool(${key})`;
+        case 'bytes':
+        case 'crdt':
+            return `_rowBytes(${key})`;
+    }
+}
+function emitClass(table) {
+    const type = pascalCase(table.name);
+    const lines = [];
+    lines.push(`/// One ${table.name} row (§2.4 column order).`);
+    lines.push(`class ${type} {`);
+    for (const column of table.columns) {
+        const dart = appDartType(column);
+        const opt = column.nullable ? '?' : '';
+        lines.push(`  final ${dart}${opt} ${camelCase(column.name)};`);
+    }
+    lines.push('');
+    const ctorParams = table.columns
+        .map((c) => `${c.nullable ? '' : 'required '}this.${camelCase(c.name)}`)
+        .join(', ');
+    lines.push(`  const ${type}({${ctorParams}});`);
+    lines.push('');
+    lines.push(`  /// Build from a \`query\`/\`readRows\` row. Returns null when a`);
+    lines.push(`  /// non-nullable column is missing or mistyped.`);
+    lines.push(`  static ${type}? fromRow(Map<String, Object?> row) {`);
+    for (const column of table.columns) {
+        if (!column.nullable) {
+            const name = camelCase(column.name);
+            lines.push(`    final ${name} = ${rowAccessor(column)};`);
+            lines.push(`    if (${name} == null) return null;`);
+        }
+    }
+    const args = table.columns
+        .map((c) => {
+        const name = camelCase(c.name);
+        return c.nullable ? `${name}: ${rowAccessor(c)}` : `${name}: ${name}`;
+    })
+        .join(', ');
+    lines.push(`    return ${type}(${args});`);
+    lines.push('  }');
+    lines.push('}');
+    return lines;
+}
+function emitSubscription(sub) {
+    const params = [];
+    for (const scope of sub.scopes) {
+        for (const value of scope.values) {
+            if (value.kind === 'parameter' && !params.includes(value.name)) {
+                params.push(value.name);
+            }
+        }
+    }
+    const lines = [];
+    lines.push(`/// Requested-scope template for the ${quote(sub.name)} subscription.`);
+    lines.push(`class Syncular${pascalCase(sub.name)}Subscription {`);
+    lines.push(`  static const String name = ${quote(sub.name)};`);
+    lines.push(`  static const String table = ${quote(sub.table)};`);
+    const args = params.map((p) => `required String ${camelCase(p)}`).join(', ');
+    const argsClause = args.length > 0 ? `{${args}}` : '';
+    lines.push(`  static Map<String, List<String>> scopes(${argsClause}) => {`);
+    for (const scope of sub.scopes) {
+        const values = scope.values
+            .map((value) => value.kind === 'literal' ? quote(value.value) : camelCase(value.name))
+            .join(', ');
+        lines.push(`        ${quote(scope.variable)}: [${values}],`);
+    }
+    lines.push('      };');
+    lines.push('}');
+    return lines;
+}
+export function emitDartModule(ir, hash) {
+    const parts = [];
+    parts.push([
+        '// Generated by @syncular/typegen — DO NOT EDIT.',
+        `// irVersion: ${ir.irVersion}`,
+        `// irHash: ${hash}`,
+        '// ignore_for_file: type=lint',
+    ].join('\n'));
+    // The schema constant.
+    const schemaLines = [];
+    schemaLines.push('/// ServerSchema-compatible schema (SPEC §2.4, §3.1) —');
+    schemaLines.push('/// pass to `SyncularClient.create(schema: …)`.');
+    const schemaValue = emitSchemaValue(ir, '');
+    schemaValue[0] = `const Map<String, Object?> syncularSchema = ${schemaValue[0]}`;
+    schemaValue[schemaValue.length - 1] =
+        `${schemaValue[schemaValue.length - 1]};`;
+    for (const line of schemaValue)
+        schemaLines.push(line);
+    parts.push(schemaLines.join('\n'));
+    // Shared row-decode helpers.
+    parts.push([
+        '/// Lift a SQLite boolean: a real bool, or 0/1 as a number.',
+        'bool? _rowBool(Object? value) {',
+        '  if (value is bool) return value;',
+        '  if (value is num) return value != 0;',
+        '  return null;',
+        '}',
+        '',
+        "/// Decode the core's {'\\$bytes': '<hex>'} marshaling (bytes as hex).",
+        'List<int>? _rowBytes(Object? value) {',
+        '  if (value is! Map) return null;',
+        "  final hex = value[r'$bytes'];",
+        '  if (hex is! String || hex.length % 2 != 0) return null;',
+        '  return [',
+        '    for (var i = 0; i < hex.length; i += 2)',
+        '      int.parse(hex.substring(i, i + 2), radix: 16),',
+        '  ];',
+        '}',
+    ].join('\n'));
+    for (const table of ir.tables) {
+        parts.push(emitClass(table).join('\n'));
+    }
+    for (const sub of ir.subscriptions) {
+        parts.push(emitSubscription(sub).join('\n'));
+    }
+    return `${parts.join('\n\n')}\n`;
+}

package/dist/emit-kotlin.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Kotlin emitter: neutral IR → one standalone `.kt` file exporting
+ *
+ * - `object <ObjectName> { val schema: JsonValue }` — the ServerSchema
+ *   object built from the IR (fed straight into `SyncularClient.create(
+ *   schema = …)`),
+ * - one `data class` per table with typed properties (per the six §2.4 column
+ *   types + blob_ref/crdt) and a `fromRow(row: JsonValue)` companion factory,
+ * - a `Subscriptions` object of typed requested-scope builders.
+ *
+ * The row shape is `JsonValue` — the exact type the Kotlin wrapper's
+ * `query`/`readRows` return (each row a `JsonValue.Obj`). The header carries
+ * the IR hash so `--check` verifies freshness byte-exactly.
+ */
+import type { IrDocument } from './ir.js';
+export declare function emitKotlinModule(ir: IrDocument, hash: string, packageName: string, objectName: string): string;