@omnifyjp/omnify 3.12.5 → 3.13.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnifyjp/omnify",
-  "version": "3.12.5",
+  "version": "3.13.1",
   "description": "Schema-driven code generation for Laravel, TypeScript, and SQL",
   "license": "MIT",
   "repository": {
@@ -36,10 +36,10 @@
     "zod": "^3.24.0"
   },
   "optionalDependencies": {
-    "@omnifyjp/omnify-darwin-arm64": "3.12.5",
-    "@omnifyjp/omnify-darwin-x64": "3.12.5",
-    "@omnifyjp/omnify-linux-x64": "3.12.5",
-    "@omnifyjp/omnify-linux-arm64": "3.12.5",
-    "@omnifyjp/omnify-win32-x64": "3.12.5"
+    "@omnifyjp/omnify-darwin-arm64": "3.13.1",
+    "@omnifyjp/omnify-darwin-x64": "3.13.1",
+    "@omnifyjp/omnify-linux-x64": "3.13.1",
+    "@omnifyjp/omnify-linux-arm64": "3.13.1",
+    "@omnifyjp/omnify-win32-x64": "3.13.1"
   }
 }

package/ts-dist/cli.d.ts

@@ -5,9 +5,22 @@
  * Reads omnify.yaml to resolve schemas.json input and TypeScript output paths.
  * Falls back to explicit --input / --output flags.
  *
+ * Two omnify.yaml shapes are accepted:
+ *
+ *   1. Backend shape (legacy / source-of-truth): the schemas.json path is
+ *      resolved indirectly via `connections.<default>.migrations[type=laravel].schemasPath`.
+ *      The same file the omnify-go CLI reads.
+ *
+ *   2. Consumer shape (frontend): a top-level `input` field that accepts
+ *      a local path, an http(s) URL, or an npm package specifier (e.g.
+ *      `@org/pkg/schemas.json`). No connections / migrations needed —
+ *      consumers don't have a database.
+ *
  * Usage:
  *   omnify-ts                              # reads omnify.yaml in cwd
  *   omnify-ts --config path/to/omnify.yaml
  *   omnify-ts --input schemas.json --output ./types  # explicit override
+ *   omnify-ts --frozen-lockfile             # CI mode: fail if upstream drift
+ *   omnify-ts --update                      # force re-fetch remote input
  */
 export {};

package/ts-dist/cli.js

@@ -5,10 +5,23 @@
  * Reads omnify.yaml to resolve schemas.json input and TypeScript output paths.
  * Falls back to explicit --input / --output flags.
  *
+ * Two omnify.yaml shapes are accepted:
+ *
+ *   1. Backend shape (legacy / source-of-truth): the schemas.json path is
+ *      resolved indirectly via `connections.<default>.migrations[type=laravel].schemasPath`.
+ *      The same file the omnify-go CLI reads.
+ *
+ *   2. Consumer shape (frontend): a top-level `input` field that accepts
+ *      a local path, an http(s) URL, or an npm package specifier (e.g.
+ *      `@org/pkg/schemas.json`). No connections / migrations needed —
+ *      consumers don't have a database.
+ *
  * Usage:
  *   omnify-ts                              # reads omnify.yaml in cwd
  *   omnify-ts --config path/to/omnify.yaml
  *   omnify-ts --input schemas.json --output ./types  # explicit override
+ *   omnify-ts --frozen-lockfile             # CI mode: fail if upstream drift
+ *   omnify-ts --update                      # force re-fetch remote input
  */
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
 import { resolve, dirname, join } from 'node:path';
@@ -16,33 +29,57 @@ import { Command } from 'commander';
 import { parse as parseYaml } from 'yaml';
 import { generateTypeScript } from './generator.js';
 import { generatePhp } from './php/index.js';
+import { resolveInput, sniffInputKind } from './input-resolver.js';
 function resolveFromConfig(configPath) {
     const raw = readFileSync(configPath, 'utf-8');
     const config = parseYaml(raw);
     const configDir = dirname(configPath);
-    // Find default connection
-    const defaultName = config.default ?? 'default';
-    const connections = config.connections ?? {};
-    const conn = connections[defaultName];
-    if (!conn) {
-        throw new Error(`Connection "${defaultName}" not found in ${configPath}`);
-    }
-    // Resolve schemas.json input path from migrations[type=laravel].schemasPath
-    let schemasPath;
-    for (const m of conn.migrations ?? []) {
-        if (m.type === 'laravel' && m.schemasPath) {
-            schemasPath = m.schemasPath;
-            break;
+    // Determine the input spec. Two shapes are accepted; consumer shape wins
+    // when both are present (top-level `input` is the explicit signal that
+    // this is a consumer project).
+    let inputSpec;
+    if (config.input) {
+        // Consumer shape — accept the spec as-is. The input resolver will
+        // sniff it (path / URL / npm) and translate it to a local file later.
+        // For local relative paths we still need to anchor them to configDir
+        // before handing off, so the resolver doesn't see a cwd-relative path.
+        if (sniffInputKind(config.input) === 'local' && !config.input.startsWith('/')) {
+            inputSpec = resolve(configDir, config.input);
+        }
+        else {
+            inputSpec = config.input;
         }
     }
-    if (!schemasPath) {
-        throw new Error(`No schemasPath found in laravel migration for connection "${defaultName}" in ${configPath}.\n` +
-            `Either add schemasPath to your laravel migration config, or use --input explicitly.`);
+    else {
+        // Backend / legacy shape — walk connections.<default>.migrations to
+        // find the laravel target's schemasPath.
+        const defaultName = config.default ?? 'default';
+        const connections = config.connections ?? {};
+        const conn = connections[defaultName];
+        if (!conn) {
+            throw new Error(`Connection "${defaultName}" not found in ${configPath}.\n` +
+                `For consumer projects (frontend), add a top-level "input:" field instead.`);
+        }
+        let schemasPath;
+        for (const m of conn.migrations ?? []) {
+            if (m.type === 'laravel' && m.schemasPath) {
+                schemasPath = m.schemasPath;
+                break;
+            }
+        }
+        if (!schemasPath) {
+            throw new Error(`No schemasPath found in laravel migration for connection "${defaultName}" in ${configPath}.\n` +
+                `Either add schemasPath to your laravel migration config, set top-level "input:", ` +
+                `or use --input explicitly.`);
+        }
+        inputSpec = resolve(configDir, schemasPath);
     }
-    // TypeScript config (enable defaults to false)
+    // TypeScript config (enable defaults to false). Accept both `output`
+    // (new) and `modelsPath` (legacy) — `output` wins if both are set.
     const tsConfig = config.codegen?.typescript;
-    const tsEnabled = tsConfig?.enable === true && !!tsConfig?.modelsPath;
-    const tsOutput = tsEnabled ? resolve(configDir, tsConfig.modelsPath) : undefined;
+    const tsOutputRaw = tsConfig?.output ?? tsConfig?.modelsPath;
+    const tsEnabled = tsConfig?.enable === true && !!tsOutputRaw;
+    const tsOutput = tsEnabled ? resolve(configDir, tsOutputRaw) : undefined;
     // Laravel config (enable defaults to false)
     const laravelConfig = config.codegen?.laravel;
     const laravelEnabled = laravelConfig?.enable === true;
@@ -62,34 +99,34 @@ function resolveFromConfig(configPath) {
         nestedset: laravelConfig?.nestedset,
     } : undefined;
     return {
-        input: resolve(configDir, schemasPath),
+        inputSpec,
         tsEnabled,
         tsOutput,
         laravelEnabled,
         laravelOverrides,
     };
 }
-// ============================================================================
-// CLI
-// ============================================================================
 const program = new Command();
 program
     .name('omnify-ts')
     .description('Generate TypeScript types and Laravel PHP code from Omnify schemas.json')
     .option('-c, --config <path>', 'Path to omnify.yaml (default: ./omnify.yaml)')
-    .option('-i, --input <path>', 'Path to schemas.json (overrides config)')
+    .option('-i, --input <spec>', 'schemas.json source: local path, http(s) URL, or npm package spec (overrides config)')
     .option('-o, --output <path>', 'Output directory for TypeScript (overrides config)')
     .option('--force', 'Force regeneration of auto-generated files', false)
-    .action((opts) => {
-    let inputPath;
+    .option('--frozen-lockfile', 'Fail if remote input differs from .omnify/input.lock.json (CI mode)', false)
+    .option('--update', 'Force re-fetch of remote input and refresh the lockfile', false)
+    .action(async (opts) => {
+    let inputSpec;
     let tsEnabled = true;
     let tsOutput;
     let laravelEnabled = false;
     let laravelOverrides;
     let configDir = process.cwd();
     if (opts.input && opts.output) {
-        // Explicit flags — skip config, only TS generation
-        inputPath = resolve(opts.input);
+        // Explicit flags — skip config, only TS generation. The flag is
+        // passed through unchanged so URLs/npm specs work too.
+        inputSpec = opts.input;
         tsOutput = resolve(opts.output);
     }
     else {
@@ -102,17 +139,27 @@ program
             process.exit(1);
         }
         const resolved = resolveFromConfig(configPath);
-        inputPath = opts.input ? resolve(opts.input) : resolved.input;
+        inputSpec = opts.input ?? resolved.inputSpec;
         tsEnabled = resolved.tsEnabled;
         tsOutput = opts.output ? resolve(opts.output) : resolved.tsOutput;
         laravelEnabled = resolved.laravelEnabled;
         laravelOverrides = resolved.laravelOverrides;
     }
-    // Read schemas.json
-    if (!existsSync(inputPath)) {
-        console.error(`Error: schemas.json not found: ${inputPath}\nRun "omnify generate" first.`);
+    // Resolve the input spec to a local file path. This is where http
+    // fetch + lockfile + cache happen for remote sources.
+    let resolvedInput;
+    try {
+        resolvedInput = await resolveInput(inputSpec, {
+            configDir,
+            frozen: opts.frozenLockfile,
+            forceUpdate: opts.update,
+        });
+    }
+    catch (err) {
+        console.error(err.message);
         process.exit(1);
     }
+    const inputPath = resolvedInput.localPath;
     const raw = readFileSync(inputPath, 'utf-8');
     const input = JSON.parse(raw);
     console.log(`Reading schemas from ${inputPath}`);
@@ -185,4 +232,7 @@ program
     }
     console.log(`\nGeneration complete.`);
 });
-program.parse();
+program.parseAsync().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/ts-dist/generator.js

@@ -16,6 +16,8 @@ import { schemaToInterface, formatInterface, needsDateTimeImports, } from './int
 import { generateEnums, generatePluginEnums, formatEnum, formatTypeAlias, extractInlineEnums, } from './enum-generator.js';
 import { generateZodSchemas, generateDisplayNames, getExcludedFields, formatZodSchemasSection, formatZodModelFile, } from './zod-generator.js';
 import { generateI18nFileContent } from './i18n-generator.js';
+import { buildSchemaMetadata, formatMetadataConst, } from './metadata-generator.js';
+import { buildFormShape, formatPayloadBuilderSection, } from './payload-builder-generator.js';
 /** Auto-generated file header. */
 function generateBaseHeader() {
     return `/**
@@ -90,7 +92,21 @@ function generateBaseInterfaceFile(schemaName, schemas, options) {
     const displayNames = generateDisplayNames(schema, options);
     const excludedFields = getExcludedFields(schema);
     parts.push('\n');
-    parts.push(formatZodSchemasSection(schemaName, zodSchemas, displayNames, excludedFields));
+    parts.push(formatZodSchemasSection(schemaName, zodSchemas, displayNames, excludedFields, schema, options));
+    // Form field metadata constant (issue #54)
+    const metadata = buildSchemaMetadata(schema, schemas, options, displayNames);
+    parts.push(formatMetadataConst(metadata));
+    // Form-state interfaces + payload builders (issue #55). Only emit when
+    // the schema has at least one form-relevant field; otherwise the helpers
+    // would be empty noise.
+    const formShape = buildFormShape(schema, schemas, options);
+    if (formShape.fields.length > 0) {
+        // The builders depend on `Locale` (from common.ts) and the shared
+        // `buildI18nPayload` / `emptyLocaleMap` helpers (from payload-helpers.ts).
+        // Inject the imports near the top of the file.
+        insertPayloadImports(parts);
+        parts.push(formatPayloadBuilderSection(formShape, options.defaultLocale));
+    }
     return {
         filePath: `base/${schemaName}.ts`,
         content: parts.join(''),
@@ -99,6 +115,24 @@ function generateBaseInterfaceFile(schemaName, schemas, options) {
         category: 'base',
     };
 }
+/**
+ * Inject the imports the payload builder section needs into the parts
+ * array. Has to run BEFORE rendering the builder section but AFTER the
+ * existing import block. We rely on the fact that the file content is
+ * still string fragments in `parts` and we can splice in the imports near
+ * the top.
+ */
+function insertPayloadImports(parts) {
+    // The first part is the header; subsequent parts include `import { z }`
+    // and other imports. Find the index of the first non-import / non-header
+    // part (where the interface or `\n` block begins) and inject before it.
+    // For simplicity, we just append the imports immediately after the
+    // header (index 1) since the existing imports below it don't conflict
+    // and the TS compiler is happy with imports interleaved at the top.
+    const importBlock = `import type { Locale } from '../common';\n` +
+        `import { buildI18nPayload, emptyLocaleMap } from '../payload-helpers';\n`;
+    parts.splice(1, 0, importBlock);
+}
 /** Generate an enum file. */
 function generateEnumFile(enumDef, isPlugin) {
     const parts = [generateBaseHeader()];
@@ -212,6 +246,70 @@ ${fileSection}`;
         overwrite: true,
     };
 }
+/** Generate the shared payload-helpers.ts file (used by per-model builders). */
+function generatePayloadHelpersFile(options) {
+    const localesArrayLiteral = `[${options.locales.map((l) => `'${l}'`).join(', ')}]`;
+    const content = `${generateBaseHeader()}/**
+ * Shared utilities used by every model's payload builder. The per-model
+ * \`build<Model>CreatePayload\` / \`build<Model>UpdatePayload\` helpers
+ * import from this file rather than re-emitting the same code per model.
+ *
+ * Issue omnify-jp/omnify-go#55.
+ */
+
+import type { Locale } from './common';
+
+/** Locales the project supports — kept in sync with omnify.yaml's locale.locales. */
+export const SUPPORTED_LOCALES: readonly Locale[] = ${localesArrayLiteral};
+
+/** Default locale (mirrors omnify.yaml's locale.defaultLocale). */
+export const DEFAULT_LOCALE: Locale = '${options.defaultLocale}';
+
+/** Build a fresh locale map with every supported locale present and empty. */
+export function emptyLocaleMap(): Record<Locale, string> {
+  const map = {} as Record<Locale, string>;
+  for (const locale of SUPPORTED_LOCALES) {
+    map[locale] = '';
+  }
+  return map;
+}
+
+/**
+ * Convert a flat \`{ fieldName: { ja: 'x', en: 'y', vi: 'z' } }\` form-state
+ * map into the nested locale-keyed wire shape that the create / update zod
+ * schemas accept (issue #53). Empty per-locale strings are preserved (the
+ * server treats them as "no translation"); fields where the entire dict is
+ * undefined are skipped so update payloads only include touched fields.
+ */
+export function buildI18nPayload(
+  fields: Record<string, Record<string, string> | undefined>,
+): Record<Locale, Record<string, string>> {
+  const out = {} as Record<Locale, Record<string, string>>;
+  for (const locale of SUPPORTED_LOCALES) {
+    const sub: Record<string, string> = {};
+    let hasAny = false;
+    for (const [fieldName, dict] of Object.entries(fields)) {
+      if (!dict) continue;
+      const value = dict[locale];
+      if (value !== undefined) {
+        sub[fieldName] = value.trim();
+        hasAny = true;
+      }
+    }
+    if (hasAny) {
+      out[locale] = sub;
+    }
+  }
+  return out;
+}
+`;
+    return {
+        filePath: 'payload-helpers.ts',
+        content,
+        types: ['SUPPORTED_LOCALES', 'DEFAULT_LOCALE', 'emptyLocaleMap', 'buildI18nPayload'],
+        overwrite: true,
+    };
+}
 /** Generate i18n.ts with validation messages. */
 function generateI18nFile(options) {
     return {
@@ -391,6 +489,8 @@ export function generateTypeScript(input) {
     });
     // Common types
     files.push(generateCommonFile(options, hasFiles));
+    // Shared payload-builder helpers (issue #55)
+    files.push(generatePayloadHelpersFile(options));
     // I18n
     files.push(generateI18nFile(options));
     // Index re-exports

package/ts-dist/input-resolver.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Input resolver for omnify-ts.
+ *
+ * Accepts a `schemas.json` source spec and returns a local file path the
+ * caller can read directly. Three source types are supported:
+ *
+ *   - **Local** (path/relative path) — read directly from disk.
+ *   - **HTTP/HTTPS** (URL) — fetch, cache under `.omnify/cache/`, and pin
+ *     the SHA-256 hash in `.omnify/input.lock.json` for reproducible builds.
+ *   - **NPM** (package specifier like `@org/pkg/schemas.json`) — resolve via
+ *     Node module resolution from the consumer project's node_modules.
+ *
+ * Lockfile semantics (HTTP only):
+ *   - Default mode: re-fetch when the cache is stale, auto-update the
+ *     lockfile, and warn the user when the upstream hash changes so they
+ *     can review and commit the lockfile change.
+ *   - `--frozen-lockfile` mode: fail loudly if the lockfile is missing,
+ *     points at a different URL, or its hash differs from upstream. Use
+ *     this in CI to guarantee build reproducibility.
+ *
+ * Local and NPM specs do not need an omnify lockfile because:
+ *   - Local files are read every run; there is no fetch step that could
+ *     introduce drift.
+ *   - NPM packages are already version-pinned by `package-lock.json` /
+ *     `pnpm-lock.yaml` / `yarn.lock`.
+ */
+export type InputKind = 'local' | 'http' | 'npm';
+export interface ResolveOptions {
+    /**
+     * Directory containing the omnify.yaml that declared the input. Used as
+     * the base for resolving relative paths and as the root for the
+     * `.omnify/cache/` and `.omnify/input.lock.json` files.
+     */
+    configDir: string;
+    /**
+     * CI mode. When true, refuse to fetch if the lockfile is missing or its
+     * hash doesn't match upstream. Caller should set this from
+     * `--frozen-lockfile`.
+     */
+    frozen?: boolean;
+    /**
+     * Force re-fetch even when the cache is valid and the lockfile matches.
+     * Use this when the user explicitly asked for an update (e.g.
+     * `omnify-ts --update`).
+     */
+    forceUpdate?: boolean;
+}
+export interface ResolveResult {
+    /** Absolute path to a local file the caller can read with fs APIs. */
+    localPath: string;
+    kind: InputKind;
+    /** SHA-256 of the resolved file. Always set for http/npm; set for local
+     *  too as a courtesy for diagnostics. */
+    sha256: string;
+}
+/**
+ * Subset of the WHATWG fetch API used by the resolver. Injectable so tests
+ * can stub it without monkey-patching globalThis.
+ */
+export interface HttpFetcher {
+    (url: string): Promise<{
+        ok: boolean;
+        status: number;
+        statusText: string;
+        text(): Promise<string>;
+    }>;
+}
+/**
+ * Decide which kind of source a spec string is. Heuristic — explicit
+ * prefixes win, ambiguous bare names default to local. Unscoped npm
+ * packages are intentionally NOT supported because they collide with
+ * relative path semantics; users should publish under a scope.
+ */
+export declare function sniffInputKind(spec: string): InputKind;
+/**
+ * Resolve an input spec to a concrete local file path. Dispatches by kind:
+ * local files are read directly, npm packages are resolved through Node
+ * module resolution, and HTTP URLs are fetched, cached, and pinned in the
+ * lockfile.
+ *
+ * The `fetcher` parameter is exposed only for tests; production callers
+ * should leave it at the default (`globalThis.fetch`).
+ */
+export declare function resolveInput(spec: string, opts: ResolveOptions, fetcher?: HttpFetcher): Promise<ResolveResult>;