hikoutei 0.10.23-dev → 0.10.25-dev

package/dist/cli/inferMain.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Production wiring for `hikoutei infer`.
+ *
+ * Owns the real-world dependencies the pure core avoids: resolving the
+ * spreadsheet id and credentials, reading one tab range through the Sheets
+ * API (read-only — no writes, no provisioning), and mapping outcomes to
+ * exit codes. Tests drive `runInferCli` with a fake reader and never touch
+ * the network or credentials.
+ *
+ * Exit codes: 0 success, 1 runtime failure (tab not found, empty tab,
+ * missing credentials, read failure), 2 argument errors.
+ */
+import { type InferOptions } from "./inferArgs.js";
+import { type InferTabGrid, type InferTabReader } from "./infer.js";
+export interface RunInferCliInput {
+    readonly options: InferOptions;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly reader: InferTabReader;
+    readonly output: {
+        readonly write: (text: string) => void;
+    };
+    readonly error: {
+        readonly write: (text: string) => void;
+    };
+}
+/**
+ * Runs the infer flow. Never throws: every failure becomes a non-zero exit
+ * code with a machine-readable `hikoutei-infer:<code>:` line on stderr.
+ */
+export declare function runInferCli(input: RunInferCliInput): Promise<number>;
+/**
+ * Writes the descriptor-file JSON text to `path`.
+ *
+ * Parent directories are never created: a missing parent fails with
+ * `emit_parent_missing`. An existing file is left untouched unless `force`
+ * is set (`emit_exists` otherwise). Throws `InferError` with a stable code
+ * so the flow maps it to the machine-readable stderr line; the path itself
+ * is never echoed (it may embed user directory layout).
+ */
+export declare function emitDescriptorFile(path: string, json: string, options: {
+    readonly force: boolean;
+}): Promise<void>;
+/**
+ * Extracts the spreadsheet ID from a Google Sheets URL.
+ *
+ * Accepts `/spreadsheets/d/<ID>` and a top-level `/d/<ID>` right after the
+ * host (with query/fragment/trailing suffixes tolerated); anything deeper
+ * (e.g. `/document/d/<ID>`) is rejected. Mirrors the sync engine's
+ * `parseSpreadsheetIdFromUrl` without importing its module graph.
+ */
+export declare function parseInferSpreadsheetId(url: string): string | undefined;
+/**
+ * Validates the raw `spreadsheets.get` grid payload for one tab.
+ *
+ * Untrusted SDK data: the response must list the requested tab and carry
+ * grid rows; a tab without a header row is `empty_tab`. Throws `InferError`
+ * (`tab_not_found`, `empty_tab`, `malformed_grid`); never echoes payloads.
+ */
+export declare function extractInferGrid(data: unknown, tabName: string, limit: number): InferTabGrid;
+/**
+ * Runs the `hikoutei infer` CLI with the given argument vector (without the
+ * leading "infer" subcommand). Exported so the bin router can delegate and
+ * tests can drive it with injected argv.
+ */
+export declare function runInferMain(argv: readonly string[]): Promise<number>;
+//# sourceMappingURL=inferMain.d.ts.map

package/dist/cli/inferMain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inferMain.d.ts","sourceRoot":"","sources":["../../../../../../src/inferMain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAKL,KAAK,YAAY,EACjB,KAAK,cAAc,EACpB,MAAM,YAAY,CAAC;AASpB,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC3D,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC;IAC5D,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC;CAC5D;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAkD1E;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACnC,OAAO,CAAC,IAAI,CAAC,CAmBf;AA2BD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAYvE;AAmDD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAmC5F;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA6B3E"}

package/dist/cli/inferMain.js

@@ -0,0 +1,281 @@
+/**
+ * Production wiring for `hikoutei infer`.
+ *
+ * Owns the real-world dependencies the pure core avoids: resolving the
+ * spreadsheet id and credentials, reading one tab range through the Sheets
+ * API (read-only — no writes, no provisioning), and mapping outcomes to
+ * exit codes. Tests drive `runInferCli` with a fake reader and never touch
+ * the network or credentials.
+ *
+ * Exit codes: 0 success, 1 runtime failure (tab not found, empty tab,
+ * missing credentials, read failure), 2 argument errors.
+ */
+import { access, writeFile } from "node:fs/promises";
+import { GoogleAuth } from "google-auth-library";
+import { sheets } from "@googleapis/sheets";
+import { parseInferArgs } from "./inferArgs.js";
+import { INFER_ERROR_PREFIX, inferFromGrid, InferError, serializeInferDescriptorFile, } from "./infer.js";
+import { SETUP_ARG_ERROR_EXIT_CODE, SETUP_RUNTIME_ERROR_EXIT_CODE, } from "./errors.js";
+import { httpStatusOf } from "./sdkError.js";
+import { SPREADSHEETS_SCOPE } from "./sheetsFactory.js";
+import { isModuleMainEntry } from "./setup.js";
+/**
+ * Runs the infer flow. Never throws: every failure becomes a non-zero exit
+ * code with a machine-readable `hikoutei-infer:<code>:` line on stderr.
+ */
+export async function runInferCli(input) {
+    const spreadsheetUrl = input.options.spreadsheetUrl ?? input.env.HIKOUTEI_SYNC_SPREADSHEET_URL;
+    if (spreadsheetUrl === undefined || spreadsheetUrl.trim() === "") {
+        input.error.write(`${INFER_ERROR_PREFIX}:invalid_args: missing spreadsheet URL — pass --spreadsheet <url> or set HIKOUTEI_SYNC_SPREADSHEET_URL.\n`);
+        return SETUP_ARG_ERROR_EXIT_CODE;
+    }
+    const spreadsheetId = parseInferSpreadsheetId(spreadsheetUrl);
+    if (spreadsheetId === undefined) {
+        input.error.write(`${INFER_ERROR_PREFIX}:spreadsheet_url_invalid: could not extract a spreadsheet ID — expected a URL of the form https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/edit.\n`);
+        return SETUP_RUNTIME_ERROR_EXIT_CODE;
+    }
+    const credentialsPath = input.options.credentialsPath ?? input.env.GOOGLE_APPLICATION_CREDENTIALS;
+    if (credentialsPath === undefined || credentialsPath.trim() === "") {
+        input.error.write(`${INFER_ERROR_PREFIX}:missing_credentials: no service-account credentials found — pass --credentials <path> or set GOOGLE_APPLICATION_CREDENTIALS (run \`npx hikoutei setup\` to provision them).\n`);
+        return SETUP_RUNTIME_ERROR_EXIT_CODE;
+    }
+    let grid;
+    try {
+        grid = await input.reader({ spreadsheetId, tabName: input.options.tabName, limit: input.options.limit });
+    }
+    catch (error) {
+        return reportInferError(input, error);
+    }
+    try {
+        const result = inferFromGrid(grid, { ...(input.options.pkHeader === undefined ? {} : { pkHeader: input.options.pkHeader }) });
+        // Stdout contract is unchanged (block + summary); `--emit` only adds
+        // the descriptor-file side effect below.
+        input.output.write(`${result.tsBlock}\n\n${result.summary}\n`);
+        if (input.options.emitPath !== undefined) {
+            try {
+                await emitDescriptorFile(input.options.emitPath, serializeInferDescriptorFile(result), { force: input.options.force });
+            }
+            catch (error) {
+                return reportInferError(input, error);
+            }
+        }
+        return 0;
+    }
+    catch (error) {
+        return reportInferError(input, error);
+    }
+}
+/**
+ * Writes the descriptor-file JSON text to `path`.
+ *
+ * Parent directories are never created: a missing parent fails with
+ * `emit_parent_missing`. An existing file is left untouched unless `force`
+ * is set (`emit_exists` otherwise). Throws `InferError` with a stable code
+ * so the flow maps it to the machine-readable stderr line; the path itself
+ * is never echoed (it may embed user directory layout).
+ */
+export async function emitDescriptorFile(path, json, options) {
+    try {
+        await writeFile(path, json, options.force ? {} : { flag: "wx" });
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code === "ENOENT") {
+            throw new InferError("emit_parent_missing", "could not write the descriptor file — the parent directory does not exist.");
+        }
+        if (code === "EEXIST") {
+            throw new InferError("emit_exists", "the descriptor file already exists — pass --force to overwrite it.");
+        }
+        throw new InferError("emit_write_failed", "could not write the descriptor file.");
+    }
+}
+/** Maps an infer failure to the machine-readable CLI error line. */
+function reportInferError(input, error) {
+    const code = error instanceof InferError
+        ? error.code
+        : typeof error?.code === "string"
+            ? error.code
+            : "unexpected";
+    if (code === "invalid_args" || code === "pk_not_found") {
+        const message = error instanceof Error ? error.message : String(error);
+        input.error.write(`${INFER_ERROR_PREFIX}:${code === "pk_not_found" ? "invalid_args" : code}: ${message}\n`);
+        return SETUP_ARG_ERROR_EXIT_CODE;
+    }
+    if (error instanceof InferError) {
+        input.error.write(`${INFER_ERROR_PREFIX}:${error.code}: ${error.message}\n`);
+        return SETUP_RUNTIME_ERROR_EXIT_CODE;
+    }
+    // Uncoded reader/SDK failures carry no safe detail (messages may embed
+    // URLs or key material), so report the bare HTTP status when one exists.
+    const status = httpStatusOf(error);
+    input.error.write(`${INFER_ERROR_PREFIX}:${code}: ${status === undefined ? "could not sample the tab" : `sheet read failed with HTTP ${status}`}.\n`);
+    return SETUP_RUNTIME_ERROR_EXIT_CODE;
+}
+/**
+ * Extracts the spreadsheet ID from a Google Sheets URL.
+ *
+ * Accepts `/spreadsheets/d/<ID>` and a top-level `/d/<ID>` right after the
+ * host (with query/fragment/trailing suffixes tolerated); anything deeper
+ * (e.g. `/document/d/<ID>`) is rejected. Mirrors the sync engine's
+ * `parseSpreadsheetIdFromUrl` without importing its module graph.
+ */
+export function parseInferSpreadsheetId(url) {
+    if (typeof url !== "string" || url.trim() === "")
+        return undefined;
+    const withoutScheme = url.replace(/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//, "");
+    const path = withoutScheme.split(/[?#]/, 1)[0] ?? "";
+    const segments = path.split("/");
+    const dIndex = segments.findIndex((segment) => segment === "d");
+    if (dIndex < 0)
+        return undefined;
+    const previous = segments[dIndex - 1];
+    if (previous !== "spreadsheets" && dIndex !== 1)
+        return undefined;
+    const id = segments[dIndex + 1];
+    if (id === undefined || id.length === 0 || /[\s?#]/.test(id))
+        return undefined;
+    return id;
+}
+/** Quotes a tab name for A1-notation ranges (single quotes doubled). */
+function quoteA1TabName(tabName) {
+    return `'${tabName.replace(/'/g, "''")}'`;
+}
+/** Production reader: one read-only tab-range fetch through the Sheets API. */
+async function createSheetsTabReader(credentialsPath) {
+    try {
+        await access(credentialsPath);
+    }
+    catch {
+        throw new InferError("missing_credentials", `cannot read the credentials file — check the path or run \`npx hikoutei setup\`.`);
+    }
+    // The boundary cast keeps any google-auth-library version mismatch between
+    // the top-level package and googleapis-common contained in this module.
+    const auth = new GoogleAuth({
+        keyFile: credentialsPath,
+        scopes: [SPREADSHEETS_SCOPE],
+    });
+    const client = sheets({ version: "v4", auth });
+    return async (input) => {
+        let data;
+        try {
+            const response = await client.spreadsheets.get({
+                spreadsheetId: input.spreadsheetId,
+                includeGridData: true,
+                ranges: [`${quoteA1TabName(input.tabName)}!A1:ZZ${input.limit + 1}`],
+                fields: "sheets(properties.title,data.rowData.values(userEnteredValue,effectiveValue,formattedValue,userEnteredFormat.numberFormat,effectiveFormat.numberFormat))",
+            });
+            data = response.data;
+        }
+        catch (error) {
+            // A bad range is how the API reports an unknown tab (400); a missing
+            // spreadsheet surfaces as 404. Anything else is a read failure whose
+            // raw detail is never echoed (it may embed URLs or key material).
+            const status = httpStatusOf(error);
+            if (status === 400 || status === 404) {
+                throw new InferError("tab_not_found", `Tab "${input.tabName}" was not found in the spreadsheet.`);
+            }
+            throw new InferError("read_failed", status === undefined ? "could not sample the tab" : `sheet read failed with HTTP ${status}`);
+        }
+        return extractInferGrid(data, input.tabName, input.limit);
+    };
+}
+/**
+ * Validates the raw `spreadsheets.get` grid payload for one tab.
+ *
+ * Untrusted SDK data: the response must list the requested tab and carry
+ * grid rows; a tab without a header row is `empty_tab`. Throws `InferError`
+ * (`tab_not_found`, `empty_tab`, `malformed_grid`); never echoes payloads.
+ */
+export function extractInferGrid(data, tabName, limit) {
+    if (!isRecord(data))
+        throw new InferError("malformed_grid", "the sheet read returned a non-object payload");
+    const sheetsValue = data.sheets;
+    if (!Array.isArray(sheetsValue) || sheetsValue.length === 0) {
+        throw new InferError("tab_not_found", `Tab "${tabName}" was not found in the spreadsheet.`);
+    }
+    const sheet = sheetsValue.find((entry) => isRecord(entry) && isRecord(entry.properties) && entry.properties.title === tabName);
+    if (sheet === undefined || !isRecord(sheet)) {
+        throw new InferError("tab_not_found", `Tab "${tabName}" was not found in the spreadsheet.`);
+    }
+    const gridData = sheet.data;
+    if (!Array.isArray(gridData) || gridData.length === 0) {
+        throw new InferError("empty_tab", `Tab "${tabName}" has no header row.`);
+    }
+    const rowData = [];
+    for (const grid of gridData) {
+        if (!isRecord(grid) || grid.rowData === undefined)
+            continue;
+        if (!Array.isArray(grid.rowData))
+            throw new InferError("malformed_grid", "the sheet read returned a malformed grid");
+        rowData.push(...grid.rowData);
+    }
+    if (rowData.length === 0) {
+        throw new InferError("empty_tab", `Tab "${tabName}" has no header row.`);
+    }
+    const first = rowData[0];
+    if (!isRecord(first) || !Array.isArray(first.values)) {
+        throw new InferError("empty_tab", `Tab "${tabName}" has no header row.`);
+    }
+    return {
+        tabName,
+        headerCells: first.values,
+        dataCells: rowData.slice(1, limit + 1).map((row) => {
+            if (!isRecord(row))
+                return [];
+            return Array.isArray(row.values) ? row.values : [];
+        }),
+    };
+}
+/**
+ * Runs the `hikoutei infer` CLI with the given argument vector (without the
+ * leading "infer" subcommand). Exported so the bin router can delegate and
+ * tests can drive it with injected argv.
+ */
+export async function runInferMain(argv) {
+    const parsed = parseInferArgs(argv);
+    if (parsed.status === "help") {
+        process.stdout.write(`${parsed.helpText}\n`);
+        return 0;
+    }
+    if (parsed.status === "invalid") {
+        process.stderr.write(`${INFER_ERROR_PREFIX}:${parsed.failure.code}: ${parsed.failure.message}\n`);
+        process.stderr.write("Run `hikoutei infer --help` for usage.\n");
+        return SETUP_ARG_ERROR_EXIT_CODE;
+    }
+    const options = parsed.options;
+    try {
+        const credentialsPath = options.credentialsPath ?? process.env.GOOGLE_APPLICATION_CREDENTIALS;
+        if (credentialsPath === undefined || credentialsPath.trim() === "") {
+            process.stderr.write(`${INFER_ERROR_PREFIX}:missing_credentials: no service-account credentials found — pass --credentials <path> or set GOOGLE_APPLICATION_CREDENTIALS (run \`npx hikoutei setup\` to provision them).\n`);
+            return SETUP_RUNTIME_ERROR_EXIT_CODE;
+        }
+        const reader = await createSheetsTabReader(credentialsPath);
+        return await runInferCli({ options, env: process.env, reader, output: process.stdout, error: process.stderr });
+    }
+    catch (error) {
+        const code = error instanceof InferError ? error.code : "unexpected";
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`${INFER_ERROR_PREFIX}:${code}: ${message}\n`);
+        return SETUP_RUNTIME_ERROR_EXIT_CODE;
+    }
+}
+// ESM entrypoint guard: run main() only when this file is the process entry,
+// never when merely imported (see setup.ts for the same pattern).
+if (isModuleMainEntry(process.argv[1], import.meta.url)) {
+    runInferMain(process.argv.slice(2))
+        .then((code) => {
+        process.exitCode = code;
+    })
+        .catch((error) => {
+        process.stderr.write(`${INFER_ERROR_PREFIX}:unexpected: ${safeReason(error)}\n`);
+        process.exitCode = SETUP_RUNTIME_ERROR_EXIT_CODE;
+    });
+}
+/** Strict sanitizer: only Error-shaped reasons are ever printed. */
+function safeReason(error) {
+    return error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=inferMain.js.map

package/dist/cli/inferMain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inferMain.js","sourceRoot":"","sources":["../../../../../../src/inferMain.ts"],"names":[],"mappings":"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"}

package/dist/composition/localRuntime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"localRuntime.d.ts","sourceRoot":"","sources":["../../../../../../src/localRuntime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAEL,KAAK,qCAAqC,EAC3C,MAAM,yFAAyF,CAAC;AAUjG,OAAO,KAAK,EACV,+BAA+B,EAChC,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,EAGL,KAAK,wBAAwB,EAC7B,KAAK,QAAQ,EACd,MAAM,2CAA2C,CAAC;AAuBnD,mEAAmE;AACnE,MAAM,WAAW,wBAAwB;IACvC,sEAAsE;IACtE,QAAQ,CAAC,SAAS,EAAE,qCAAqC,CAAC;IAC1D,uEAAuE;IACvE,QAAQ,CAAC,iBAAiB,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACjE,mEAAmE;IACnE,QAAQ,CAAC,yBAAyB,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,+BAA+B,CAAC;CAC3F;AAED;;;GAGG;AACH,wBAAsB,8BAA8B,CAClD,QAAQ,EAAE,SAAS,cAAc,EAAE,GAClC,OAAO,CAAC,wBAAwB,CAAC,CAYnC;AAED;;;;;;;;GAQG;AACH,wBAAsB,6BAA6B,CACjD,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,QAAQ,CAAC,CAkCnB"}
+{"version":3,"file":"localRuntime.d.ts","sourceRoot":"","sources":["../../../../../../src/localRuntime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAEL,KAAK,qCAAqC,EAC3C,MAAM,yFAAyF,CAAC;AAUjG,OAAO,KAAK,EACV,+BAA+B,EAChC,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,EAGL,KAAK,wBAAwB,EAC7B,KAAK,QAAQ,EACd,MAAM,2CAA2C,CAAC;AAwBnD,mEAAmE;AACnE,MAAM,WAAW,wBAAwB;IACvC,sEAAsE;IACtE,QAAQ,CAAC,SAAS,EAAE,qCAAqC,CAAC;IAC1D,uEAAuE;IACvE,QAAQ,CAAC,iBAAiB,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACjE,mEAAmE;IACnE,QAAQ,CAAC,yBAAyB,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,+BAA+B,CAAC;CAC3F;AAED;;;GAGG;AACH,wBAAsB,8BAA8B,CAClD,QAAQ,EAAE,SAAS,cAAc,EAAE,GAClC,OAAO,CAAC,wBAAwB,CAAC,CAYnC;AAED;;;;;;;;GAQG;AACH,wBAAsB,6BAA6B,CACjD,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,QAAQ,CAAC,CAsCnB"}

package/dist/composition/localRuntime.js

@@ -15,6 +15,7 @@ import { initializeMikroOrmScalarStorage, } from "../persistence/providers/mikro
 import { MikroOrmScalarPersistenceProvider, } from "../persistence/providers/mikro-orm/api/MikroOrmScalarPersistenceProvider.js";
 import { createInternalHikoutei, resolveDefaultDbPath, } from "../sync-engine/api/hikouteiCore.js";
 import { getRegisteredEntityTokens, } from "../sync-engine/api/entity.js";
+import { mergeEntitiesAndDescriptors } from "../sync-engine/api/hikouteiCore.js";
 import { resolveEntityDescriptors, } from "../sync-engine/api/internalEntityRegistry.js";
 import { HIKOUTEI_ERROR_CODES, HikouteiError, } from "../sync-engine/api/errors.js";
 import { describeErrorForInternalLog, HIKOUTEI_LOG_LEVELS, logHikouteiInternalEvent, } from "../contracts/shared/observability/internalLog.js";
@@ -44,7 +45,8 @@ export async function createLocalTypedSheetsRuntime(options) {
     const startedAt = Date.now();
     try {
         const dbName = options.dbName ?? resolveDefaultDbPath();
-        const entities = options.entities ?? getRegisteredEntityTokens();
+        // File-form descriptors ride the same builder path as the public factory.
+        const entities = mergeEntitiesAndDescriptors(options.entities ?? getRegisteredEntityTokens(), options.descriptors);
         const descriptors = resolveEntityDescriptors(entities, throwHikouteiResolutionError);
         // Load the current provider only when a runtime is opened. Importing the
         // root package alone must not require MikroORM or expose its module graph.

package/dist/composition/localRuntime.js.map

@@ -1 +1 @@
-{"version":3,"file":"localRuntime.js","sourceRoot":"","sources":["../../../../../../src/localRuntime.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"localRuntime.js","sourceRoot":"","sources":["../../../../../../src/localRuntime.ts"],"names":[],"mappings":"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"}

package/dist/contracts/api/descriptorFile.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Versioned file form of an entity descriptor (`infer --emit`, startup
+ * `descriptors`, `adopt --descriptor`).
+ *
+ * The sheet→DB loop closes to two steps: `infer --emit desc.json` writes
+ * this file once, then `createTypedSheets({ descriptors })` and
+ * `adopt --descriptor desc.json` consume it. The file is DATA, never code:
+ * it is parsed as JSON, validated with the same rules
+ * `defineTypedSheetsEntity` enforces, and registered through the same
+ * builder — no codegen, no eval, no lifecycle bypass.
+ *
+ * Schema (v1):
+ * ```json
+ * {
+ *   "hikouteiDescriptor": 1,
+ *   "name": "Invoice",
+ *   "tableName": "invoices",
+ *   "properties": {
+ *     "invoiceNo": { "header": "Invoice No", "type": "string", "primary": true },
+ *     "total": { "header": "Total", "type": "number", "nullable": true }
+ *   }
+ * }
+ * ```
+ * Property keys are the camelCase entity property names; `header` preserves
+ * the original sheet header so adopt can derive its header→property
+ * columnMap without manual `--map` flags. `type`/`primary`/`nullable` carry
+ * the exact `defineTypedSheetsEntity` property options (minus the `header`).
+ */
+import { type HikouteiEntity, type HikouteiEntityDescriptorInput, type HikouteiScalarType } from "./entity.js";
+/** The only descriptor file version accepted by this build. */
+export declare const HIKOUTEI_DESCRIPTOR_FILE_VERSION: 1;
+/** One property entry in a descriptor file: sheet header + scalar options. */
+export interface HikouteiDescriptorFileProperty {
+    /** Original sheet header; adopt derives its columnMap from these. */
+    readonly header: string;
+    /** Scalar value type stored in the entity table. */
+    readonly type: HikouteiScalarType;
+    /** Marks this field as the single primary-key/business-key column. */
+    readonly primary?: boolean;
+    /** Allows `null` values for this field. */
+    readonly nullable?: boolean;
+}
+/** Versioned descriptor file shape: entity identity + headed properties. */
+export interface HikouteiDescriptorFile {
+    /** Schema version tag; must equal `HIKOUTEI_DESCRIPTOR_FILE_VERSION`. */
+    readonly hikouteiDescriptor: typeof HIKOUTEI_DESCRIPTOR_FILE_VERSION;
+    /** Stable entity name used by the manager and internal service mappings. */
+    readonly name: string;
+    /** SQLite table name that stores this entity's rows. */
+    readonly tableName: string;
+    /** Headed property declarations keyed by property name. */
+    readonly properties: Readonly<Record<string, HikouteiDescriptorFileProperty>>;
+}
+/** One headed column used to build a descriptor file (e.g. from inference). */
+export interface HikouteiDescriptorColumn {
+    /** camelCase entity property name. */
+    readonly property: string;
+    /** Original sheet header preserved for adopt's column mapping. */
+    readonly header: string;
+    /** Inferred scalar type. */
+    readonly type: HikouteiScalarType;
+    /** True for the single primary-key/business-key column. */
+    readonly primary: boolean;
+}
+/**
+ * Builds a versioned descriptor file from headed columns.
+ *
+ * Pure constructor shared by `infer --emit`: the caller supplies the entity
+ * identity plus one entry per sampled column, and the file preserves every
+ * original header for the later `adopt --descriptor` columnMap.
+ */
+export declare function buildDescriptorFile(input: {
+    readonly name: string;
+    readonly tableName: string;
+    readonly columns: readonly HikouteiDescriptorColumn[];
+}): HikouteiDescriptorFile;
+/** Serializes a descriptor file to stable JSON (2-space, trailing newline). */
+export declare function serializeDescriptorFile(file: HikouteiDescriptorFile): string;
+/**
+ * Validates an unknown JSON value as a descriptor file.
+ *
+ * Checks the version tag and the header/type envelope here, then runs the
+ * scalar core through `defineTypedSheetsEntity`'s own rules by promoting the
+ * stripped input with `resolveEntityDescriptor` semantics: the returned file
+ * is guaranteed to satisfy the builder, so a later
+ * `defineTypedSheetsEntityFromDescriptorFile()` cannot fail on shape.
+ * Throws a typed `HikouteiError` (`INVALID_ENTITY_DESCRIPTOR`) on a version
+ * mismatch or any malformed field.
+ */
+export declare function parseDescriptorFile(value: unknown): HikouteiDescriptorFile;
+/**
+ * Strips the file envelope (`hikouteiDescriptor`, `header`) down to the
+ * plain builder input. The result flows through `defineTypedSheetsEntity`
+ * unchanged, so file-registered entities take the exact same path as
+ * code-registered ones (the token needs no TS types at runtime — only this
+ * resolved descriptor object).
+ */
+export declare function descriptorFileToEntityInput(file: HikouteiDescriptorFile): HikouteiEntityDescriptorInput;
+/**
+ * Registers a descriptor file through the same builder code entities use.
+ *
+ * The JSON object is never evaluated: it is validated by
+ * `parseDescriptorFile` (or structurally by the caller) and promoted to a
+ * plain `HikouteiEntityDescriptorInput` before `defineTypedSheetsEntity`
+ * validates and resolves it. The returned token is indistinguishable from a
+ * code-registered one (CRUD, sync projection, adoption).
+ */
+export declare function defineTypedSheetsEntityFromDescriptorFile(file: HikouteiDescriptorFile): HikouteiEntity;
+/**
+ * Derives adopt's header→property columnMap from the file's `header` fields.
+ *
+ * Replaces manual `--map Header=property` for the infer case: every headed
+ * property contributes one `header → property` binding.
+ */
+export declare function descriptorFileColumnMap(file: HikouteiDescriptorFile): Record<string, string>;
+//# sourceMappingURL=descriptorFile.d.ts.map

package/dist/contracts/api/descriptorFile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptorFile.d.ts","sourceRoot":"","sources":["../../src/api/descriptorFile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,6BAA6B,EAClC,KAAK,kBAAkB,EACxB,MAAM,aAAa,CAAC;AAGrB,+DAA+D;AAC/D,eAAO,MAAM,gCAAgC,EAAG,CAAU,CAAC;AAE3D,8EAA8E;AAC9E,MAAM,WAAW,8BAA8B;IAC7C,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,sEAAsE;IACtE,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,2CAA2C;IAC3C,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,4EAA4E;AAC5E,MAAM,WAAW,sBAAsB;IACrC,yEAAyE;IACzE,QAAQ,CAAC,kBAAkB,EAAE,OAAO,gCAAgC,CAAC;IACrE,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wDAAwD;IACxD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,8BAA8B,CAAC,CAAC,CAAC;CAC/E;AAED,+EAA+E;AAC/E,MAAM,WAAW,wBAAwB;IACvC,sCAAsC;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4BAA4B;IAC5B,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,SAAS,wBAAwB,EAAE,CAAC;CACvD,GAAG,sBAAsB,CAazB;AAED,+EAA+E;AAC/E,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,sBAAsB,GAAG,MAAM,CAE5E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,sBAAsB,CA4D1E;AAED;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,sBAAsB,GAC3B,6BAA6B,CAU/B;AAED;;;;;;;;GAQG;AACH,wBAAgB,yCAAyC,CACvD,IAAI,EAAE,sBAAsB,GAC3B,cAAc,CAEhB;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,sBAAsB,GAC3B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMxB"}