@omnifyjp/ts 3.12.5 → 3.13.1

package/README.md

@@ -0,0 +1,175 @@
+# @omnifyjp/ts
+
+TypeScript / Zod / form-metadata / payload-builder generator for Omnify
+schemas. Reads a `schemas.json` produced by `omnify generate` and emits a
+single, type-safe data layer that frontend / consumer projects import
+directly.
+
+## What it generates
+
+Per model (in `<output>/base/<Model>.ts`):
+
+- TypeScript **interface** for the row shape
+- **Zod schemas** for create / update with validation rules
+- **Per-locale Zod sub-objects** for `translatable: true` fields (issue #53)
+- **`<modelName>Metadata`** constant — single source of truth for form
+  runners (field type taxonomy, validation, label dictionary, enum values,
+  relation pointers, aggregations) — issue #54
+- **`<Model>CreateFormState` / `<Model>UpdateFormState`** interfaces and
+  **`empty<Model>CreateForm()` / `build<Model>CreatePayload()` /
+  `build<Model>UpdatePayload()`** helpers (issue #55)
+
+Plus shared infrastructure at the codegen output root:
+
+- `common.ts` — `LocaleMap`, `Locale`, `DateTimeString`, `OmnifyFile`
+- `payload-helpers.ts` — `buildI18nPayload`, `emptyLocaleMap`,
+  `SUPPORTED_LOCALES`, `DEFAULT_LOCALE`
+- `i18n.ts` — validation messages + locale helpers
+- `enum/<Enum>.ts` — every enum + helpers
+- `index.ts` — barrel re-exports
+- `<Model>.ts` — editable wrapper (created once, never overwritten)
+
+## Two ways to invoke
+
+### Backend mode (auto)
+
+When the backend's `omnify.yaml` sets `codegen.typescript.enable: true`,
+the Go binary `omnify generate` shells out to `omnify-ts` automatically.
+You don't run anything yourself.
+
+### Consumer mode (frontend repo, no Go binary)
+
+Install:
+
+```bash
+npm install --save-dev @omnifyjp/ts
+```
+
+Create `omnify.yaml` at the consumer project root:
+
+```yaml
+# yaml-language-server: $schema=https://cdn.jsdelivr.net/npm/@omnifyjp/omnify@latest/omnify-config-schema.json
+
+# Top-level `input` is the consumer-mode shortcut. Three forms accepted:
+#   1. Local path           → ../backend/.omnify/schemas.json
+#   2. http(s):// URL       → https://raw.githubusercontent.com/org/repo/v1.2.3/.omnify/schemas.json
+#   3. @org/pkg/file path   → @famgia/dxs-product-schemas/schemas.json
+input: ../backend/.omnify/schemas.json
+
+codegen:
+  typescript:
+    enable: true
+    output: src/types/models      # `output` is preferred; `modelsPath` still accepted
+```
+
+Add to `package.json` scripts:
+
+```json
+{
+  "scripts": {
+    "codegen": "omnify-ts",
+    "codegen:check": "omnify-ts && git diff --exit-code src/types/models/base src/types/models/enum"
+  }
+}
+```
+
+Run:
+
+```bash
+npm run codegen
+```
+
+## CLI flags
+
+```
+omnify-ts                                  read omnify.yaml in cwd
+omnify-ts -c, --config <path>              specify a different config file
+omnify-ts -i, --input <spec>               override input (path / URL / npm spec)
+omnify-ts -o, --output <dir>               override output directory
+omnify-ts --force                          regenerate auto files
+omnify-ts --update                         force re-fetch remote, refresh lockfile
+omnify-ts --frozen-lockfile                CI mode: fail on upstream drift
+```
+
+`<spec>` (the value of `input:` or `--input`) is sniffed by prefix:
+
+| Prefix | Resolved as |
+|---|---|
+| `http://` / `https://` | HTTP fetch + cache + lockfile pin |
+| `@<scope>/<pkg>...` | Node module resolution from cwd |
+| anything else | Local file path (relative to `omnify.yaml`) |
+
+## Three input strategies
+
+| Strategy | Use when | Example |
+|---|---|---|
+| **Local path** | Monorepo, sibling repos, git submodules — frontend can read backend over the filesystem | `input: ../backend/.omnify/schemas.json` |
+| **HTTP(S) URL** | Backend and frontend are independent repos. Pin a tag/commit SHA in the URL for reproducible builds | `input: https://raw.githubusercontent.com/famgia/dxs-product/v3.13.0/.omnify/schemas.json` |
+| **NPM package** | Backend publishes a tiny `@org/<project>-schemas` package containing only `schemas.json`. The frontend pins via `package-lock.json` | `input: "@famgia/dxs-product-schemas/schemas.json"` |
+
+Same `omnify.yaml` shape for all three. Switching strategies is a one-line
+change to the `input:` field — never a config restructure.
+
+## Reproducibility & lockfile (HTTP only)
+
+For HTTP-sourced inputs, omnify-ts maintains:
+
+- `.omnify/cache/schemas.json` — most recently fetched copy
+- `.omnify/input.lock.json` — pins the input URL + sha256
+
+**Commit `.omnify/input.lock.json`** so CI runs `omnify-ts --frozen-lockfile`
+and refuses to silently fetch a different hash. Local dev runs without the
+flag and gets a warning when upstream changes; the lockfile is auto-updated
+and the dev commits it alongside the regenerated types.
+
+| Mode | Behavior on upstream drift |
+|---|---|
+| Default (local dev) | Re-fetch + warn + auto-update lockfile |
+| `--frozen-lockfile` (CI) | Fail loudly; refuse to overwrite the lockfile |
+| `--update` | Force re-fetch even if cache + lockfile match |
+
+Local files and npm packages don't need a separate omnify lockfile —
+local files are read every run with no fetch step, and npm packages are
+already version-pinned by `package-lock.json` / `pnpm-lock.yaml`.
+
+## Idiomatic CRUD form (with the generated builders)
+
+```tsx
+import { useState } from 'react';
+import {
+  emptyProductCreateForm,
+  buildProductCreatePayload,
+  type ProductCreateFormState,
+} from '@/types/models/Product';
+
+export function ProductCreateForm() {
+  const [form, setForm] = useState<ProductCreateFormState>(emptyProductCreateForm());
+
+  async function submit() {
+    await api.create(buildProductCreatePayload(form));
+  }
+
+  return (
+    <form onSubmit={submit}>
+      <Input translatable value={form.name} onChange={(v) => setForm({ ...form, name: v })} />
+      <Input value={form.slug} onChange={(e) => setForm({ ...form, slug: e.target.value })} />
+      {/* … */}
+    </form>
+  );
+}
+```
+
+The builder handles trimming, locale-mirroring (top-level field set to
+default-locale value), nested per-locale sub-object construction, and
+dropping empty optional fields. None of that boilerplate lives in the
+form anymore.
+
+## Versioning
+
+`@omnifyjp/ts` ships in lockstep with the `omnify` Go binary in the
+`@omnifyjp/omnify` npm package. Bump both together; the version is the
+single source of truth for the `schemas.json` shape they exchange.
+
+In a sibling-repo / submodule layout the lockfiles take care of this
+automatically. In the published-package layout (HTTP URL or `@org/pkg`),
+pin the upstream version explicitly in the `input:` URL or npm dep.

package/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/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/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/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>;