@ontologie/cli 0.1.0-preview.1

package/dist/commands/import.js

@@ -0,0 +1,330 @@
+/**
+ * ontologie import -- import data from CSV/JSON/JSONL files into ObjectType instances
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { resolveConfig } from '../config.js';
+import { createDfClient } from '../client.js';
+import { buildCliMeta, extractMetaFromHeaders } from '../output/meta.js';
+import { output } from '../output/formatter.js';
+import { withErrorHandler, getGlobalFlags, resolveTypeId } from './shared.js';
+import { resolveMutationMode } from './validators.js';
+import { getExitCode } from '../output/errors.js';
+export function detectFormat(filePath, explicit) {
+    if (explicit) {
+        const fmt = explicit.toLowerCase();
+        if (fmt === 'csv' || fmt === 'json' || fmt === 'jsonl')
+            return fmt;
+        throw Object.assign(new Error(`Unsupported input format "${explicit}". Use csv, json, or jsonl.`), { code: 'INVALID_USAGE', statusCode: 400 });
+    }
+    const ext = path.extname(filePath).toLowerCase();
+    switch (ext) {
+        case '.csv':
+            return 'csv';
+        case '.json':
+            return 'json';
+        case '.jsonl':
+        case '.ndjson':
+            return 'jsonl';
+        default:
+            throw Object.assign(new Error(`Cannot detect format from extension "${ext}". Use --format-input csv|json|jsonl.`), { code: 'INVALID_USAGE', statusCode: 400 });
+    }
+}
+/**
+ * Parse a CSV field, handling quoted values with embedded commas and escaped quotes.
+ */
+export function parseCsvLine(line) {
+    const fields = [];
+    let current = '';
+    let inQuotes = false;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (inQuotes) {
+            if (ch === '"') {
+                // Check for escaped quote ""
+                if (i + 1 < line.length && line[i + 1] === '"') {
+                    current += '"';
+                    i++; // skip next quote
+                }
+                else {
+                    inQuotes = false;
+                }
+            }
+            else {
+                current += ch;
+            }
+        }
+        else {
+            if (ch === '"') {
+                inQuotes = true;
+            }
+            else if (ch === ',') {
+                fields.push(current.trim());
+                current = '';
+            }
+            else {
+                current += ch;
+            }
+        }
+    }
+    fields.push(current.trim());
+    return fields;
+}
+export function parseCsv(content) {
+    // IM2: Strip UTF-8 BOM if present
+    const cleaned = content.startsWith('\uFEFF') ? content.slice(1) : content;
+    const lines = cleaned.split(/\r?\n/).filter((l) => l.trim().length > 0);
+    if (lines.length < 2)
+        return [];
+    const headers = parseCsvLine(lines[0]);
+    const rows = [];
+    for (let i = 1; i < lines.length; i++) {
+        const values = parseCsvLine(lines[i]);
+        const row = {};
+        for (let j = 0; j < headers.length; j++) {
+            row[headers[j]] = values[j] ?? '';
+        }
+        rows.push(row);
+    }
+    return rows;
+}
+export function parseJson(content) {
+    const parsed = JSON.parse(content);
+    if (Array.isArray(parsed))
+        return parsed;
+    throw Object.assign(new Error('JSON file must contain an array of objects.'), { code: 'VALIDATION_ERROR', statusCode: 422 });
+}
+export function parseJsonl(content) {
+    return content
+        .split(/\r?\n/)
+        .filter((l) => l.trim().length > 0)
+        .map((line, idx) => {
+        try {
+            return JSON.parse(line);
+        }
+        catch {
+            throw Object.assign(new Error(`Invalid JSON on line ${idx + 1}.`), { code: 'VALIDATION_ERROR', statusCode: 422 });
+        }
+    });
+}
+export function parseFile(filePath, format, encoding) {
+    const content = fs.readFileSync(filePath, encoding);
+    switch (format) {
+        case 'csv':
+            return parseCsv(content);
+        case 'json':
+            return parseJson(content);
+        case 'jsonl':
+            return parseJsonl(content);
+    }
+}
+// ---------------------------------------------------------------------------
+// Dedup helper
+// ---------------------------------------------------------------------------
+export function dedupRows(rows, keyField) {
+    const seen = new Set();
+    const deduped = [];
+    for (const row of rows) {
+        const keyValue = String(row[keyField] ?? '');
+        if (!keyValue) {
+            deduped.push(row);
+            continue;
+        }
+        if (!seen.has(keyValue)) {
+            seen.add(keyValue);
+            deduped.push(row);
+        }
+    }
+    return deduped;
+}
+// ---------------------------------------------------------------------------
+// Batch helpers
+// ---------------------------------------------------------------------------
+export function chunk(arr, size) {
+    const chunks = [];
+    for (let i = 0; i < arr.length; i += size) {
+        chunks.push(arr.slice(i, i + size));
+    }
+    return chunks;
+}
+// ---------------------------------------------------------------------------
+// Command registration
+// ---------------------------------------------------------------------------
+export function registerImport(program) {
+    const getFormat = () => {
+        const f = getGlobalFlags(program);
+        return f.format === 'json' ? 'json' : f.format === 'jsonl' ? 'jsonl' : 'text';
+    };
+    program
+        .command('import <file>')
+        .description('Import data from CSV/JSON/JSONL into ObjectType instances')
+        .requiredOption('--type <typeName>', 'Target ObjectType name')
+        .option('--key <field>', 'Dedup key field (e.g., externalId)')
+        .option('--dry-run', 'Validate without importing')
+        .option('--apply-plan <planId>', 'Apply a previously validated plan')
+        .option('--plan-hash <hash>', 'Plan hash from dry-run (used with --apply-plan)')
+        .option('--idempotency-key <key>', 'Idempotency key for safe retries')
+        .option('--validate-only', 'Parse, validate, and resolve type without importing')
+        .option('--format-input <fmt>', 'Input format: csv|json|jsonl (auto-detected from extension)')
+        .option('--encoding <enc>', 'File encoding', 'utf-8')
+        .option('--batch-size <n>', 'Batch size for import', '100')
+        .action(async (file, opts) => withErrorHandler(async () => {
+        const flags = getGlobalFlags(program);
+        const config = resolveConfig(flags);
+        const client = createDfClient(config);
+        // ---------------------------------------------------------------
+        // Resolve the file path
+        // ---------------------------------------------------------------
+        const filePath = path.resolve(file);
+        if (!fs.existsSync(filePath)) {
+            throw Object.assign(new Error(`File not found: ${filePath}`), { code: 'INVALID_USAGE', statusCode: 400 });
+        }
+        // ---------------------------------------------------------------
+        // Parse the input file
+        // ---------------------------------------------------------------
+        const format = detectFormat(filePath, opts.formatInput);
+        const encoding = (opts.encoding || 'utf-8');
+        let rows = parseFile(filePath, format, encoding);
+        if (rows.length === 0) {
+            process.stderr.write('Warning: File contains no data rows.\n');
+        }
+        // ---------------------------------------------------------------
+        // Dedup by key field if specified
+        // ---------------------------------------------------------------
+        const originalCount = rows.length;
+        if (opts.key && rows.length > 0) {
+            rows = dedupRows(rows, opts.key);
+            if (rows.length < originalCount) {
+                process.stderr.write(`Dedup: ${originalCount - rows.length} duplicate(s) removed by key "${opts.key}".\n`);
+            }
+        }
+        // ---------------------------------------------------------------
+        // Resolve type name to ID
+        // ---------------------------------------------------------------
+        process.stderr.write(`Resolving type "${opts.type}"...\n`);
+        const typeId = await resolveTypeId(client, opts.type);
+        process.stderr.write(`Resolved type "${opts.type}" -> ${typeId}\n`);
+        // ---------------------------------------------------------------
+        // Validate-only mode: parse + resolve + report (no import)
+        // This is read-only — exempt from mutation guards.
+        // ---------------------------------------------------------------
+        if (opts.validateOnly) {
+            const columns = rows.length > 0 ? Object.keys(rows[0]) : [];
+            const plan = {
+                typeId,
+                typeName: opts.type,
+                rowCount: rows.length,
+                columnsDetected: columns,
+                dedupKey: opts.key ?? null,
+                duplicatesRemoved: originalCount - rows.length,
+                sampleRows: rows.slice(0, 3),
+                validated: true,
+            };
+            const meta = buildCliMeta({
+                command: 'import.validate',
+                workspaceId: config.workspaceId,
+                apiUrl: config.apiUrl,
+            });
+            output(plan, meta, flags);
+            return;
+        }
+        // ---------------------------------------------------------------
+        // Mutation guards: mutual exclusion, plan-hash, idempotency-key
+        // (checked after validate-only, which is read-only)
+        // ---------------------------------------------------------------
+        const mode = resolveMutationMode(opts);
+        // ---------------------------------------------------------------
+        // Dry-run mode: validate and report
+        // ---------------------------------------------------------------
+        if (mode === 'dry-run') {
+            const columns = rows.length > 0 ? Object.keys(rows[0]) : [];
+            const plan = {
+                typeId,
+                typeName: opts.type,
+                rowCount: rows.length,
+                columnsDetected: columns,
+                dedupKey: opts.key ?? null,
+                duplicatesRemoved: originalCount - rows.length,
+                sampleRows: rows.slice(0, 3),
+            };
+            const meta = buildCliMeta({
+                command: 'import.dry-run',
+                workspaceId: config.workspaceId,
+                apiUrl: config.apiUrl,
+            });
+            output(plan, meta, flags);
+            return;
+        }
+        // ---------------------------------------------------------------
+        // Import: batch-create instances
+        // ---------------------------------------------------------------
+        const batchSize = Math.max(1, Number(opts.batchSize) || 100);
+        const batches = chunk(rows, batchSize);
+        const errors = [];
+        const warnings = [];
+        let imported = 0;
+        process.stderr.write(`Importing ${rows.length} row(s) in ${batches.length} batch(es) (batch size: ${batchSize})...\n`);
+        for (let batchIdx = 0; batchIdx < batches.length; batchIdx++) {
+            const batch = batches[batchIdx];
+            const batchStart = batchIdx * batchSize;
+            for (let i = 0; i < batch.length; i++) {
+                const rowIndex = batchStart + i;
+                const row = batch[i];
+                try {
+                    await client.transport.requestWithHeaders({
+                        method: 'POST',
+                        path: `/api/v1/object-types/${typeId}/instances`,
+                        body: {
+                            data: row,
+                            sourceType: 'import',
+                            ...(opts.key && row[opts.key] != null
+                                ? { externalId: String(row[opts.key]) }
+                                : {}),
+                            ...(opts.applyPlan ? { planId: opts.applyPlan, ...(opts.planHash ? { planHash: opts.planHash } : {}) } : {}),
+                        },
+                        idempotencyKey: opts.idempotencyKey
+                            ? `${opts.idempotencyKey}:${rowIndex}`
+                            : undefined,
+                    });
+                    imported++;
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    errors.push({ row: rowIndex + 1, message });
+                }
+            }
+            // Progress on stderr
+            const processed = Math.min((batchIdx + 1) * batchSize, rows.length);
+            process.stderr.write(`Progress: ${processed}/${rows.length} rows processed.\n`);
+        }
+        if (errors.length > 0 && errors.length < rows.length) {
+            warnings.push(`${errors.length} row(s) failed out of ${rows.length}.`);
+        }
+        // ---------------------------------------------------------------
+        // Output results
+        // ---------------------------------------------------------------
+        const result = {
+            imported,
+            total: rows.length,
+            errors: errors.slice(0, 50), // Cap error output for readability
+            warnings,
+            typeId,
+            typeName: opts.type,
+        };
+        const headerMeta = errors.length === 0
+            ? extractMetaFromHeaders({})
+            : {};
+        const meta = buildCliMeta({
+            command: 'import',
+            workspaceId: config.workspaceId,
+            apiUrl: config.apiUrl,
+            ...headerMeta,
+        });
+        output(result, meta, flags);
+        // Exit with error code if all rows failed
+        if (imported === 0 && rows.length > 0) {
+            process.exitCode = getExitCode('INTERNAL_ERROR');
+        }
+    }, getFormat)());
+}
+//# sourceMappingURL=import.js.map

package/dist/commands/import.js.map

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

package/dist/commands/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Canonical CLI commands registry — single source of truth.
+ *
+ * Every command registered on the `dataforge` Commander program lives in this
+ * array. Consumers:
+ *   - `sdk/packages/cli/src/cli.ts` iterates this list to call `registerFn`.
+ *   - `tests/structural/sdk-cli-parity.test.ts` ratchet diffs this list
+ *     against the tests in `sdk/tests/verify/` and the contract docs
+ *     (`CLI-CONFORM-01`). The SDK-path ↔ backend-mount diff
+ *     (`SDK-PARITY-02`) is `it.todo()` until AST or runtime probe lands —
+ *     see #990 / #992 review notes.
+ *   - Future doc generators / shell completions read it instead of duplicating
+ *     the command list.
+ *
+ * Stability tiers map to `sdk/docs/SDK-PUBLIC-STRATEGY.md`:
+ *   - `stable`   — committed surface, SemVer + 12-month deprecation window
+ *   - `preview`  — best-effort, may change in minor versions
+ *   - `internal` — hidden from `--help`, not part of the public contract
+ *
+ * **Rule** (no double SOT): if a command is added or removed, this array is the
+ * authoritative location. Do not register commands directly in `cli.ts`.
+ */
+export type CliCommandStability = 'stable' | 'preview' | 'internal';
+export interface CliCommandSpec {
+    /** Top-level Commander command name, e.g. `whoami`, `schema`. */
+    readonly name: string;
+    /** Direct subcommands (one level deep). Empty for leaf commands. */
+    readonly subcommands: readonly string[];
+    /** Source file relative to `commands/`, used for traceability and doc gen. */
+    readonly source: string;
+    /** Stability tier — see `sdk/docs/SDK-PUBLIC-STRATEGY.md`. */
+    readonly stability: CliCommandStability;
+    /** One-line description shown in `--help` and generated docs. */
+    readonly description: string;
+    /**
+     * Commander registration callback. Signature varies — some `register*`
+     * fns take a second `options` arg (`registerCache(program, { hidden:true })`),
+     * others don't (`registerWhoami(program)`).
+     *
+     * Typed as `(program: any, options?)` to side-step a Commander `^12.x`
+     * typings quirk where `Command` (the instance type) and the static
+     * `CommanderStatic.Command` namespace are flagged as incompatible at the
+     * call site even when both resolve to the same constructor. Tightening
+     * this to `Command` causes a spurious `TS2345` at `cli.ts:62` —
+     * `Argument of type 'Command' is not assignable to parameter of type
+     * 'CommanderStatic.Command'`. Runtime is unaffected.
+     *
+     * If a future `register*` fn is written with a *required* options arg,
+     * TypeScript will not catch the mismatch — `registerOptions` is the
+     * authoritative input contract on this entry. Keep both in sync.
+     */
+    readonly registerFn: (program: any, options?: Record<string, unknown>) => void;
+    /** Optional options forwarded to `registerFn` (e.g. `{hidden: true}`). */
+    readonly registerOptions?: Record<string, unknown>;
+}
+/**
+ * Every command registered on the `dataforge` program. Counts are pinned in
+ * `tests/structural/sdk-cli-parity.test.ts` (`CLI-CONFORM-01`) so any
+ * add/remove/tier-change forces an intentional update on both sides.
+ * Order matches the original `cli.ts` to preserve `--help` output stability.
+ */
+export declare const CANONICAL_CLI_COMMANDS: readonly CliCommandSpec[];
+/**
+ * Returns the immutable registry of canonical CLI commands.
+ *
+ * Exposed as a function (rather than re-exporting the `const`) so callers can
+ * mock it in tests or wrap it with extra logic without circular imports.
+ */
+export declare function getCanonicalCliCommands(): readonly CliCommandSpec[];
+/**
+ * Convenience helper used by `cli.ts` to wire every command in one pass.
+ * Honors `registerOptions` so commands like `cache` keep their `hidden:true`.
+ *
+ * `program` is intentionally typed as `any` — Commander ships two
+ * incompatible-looking exports (`Command` and `CommanderStatic.Command`) that
+ * TypeScript narrows differently depending on the call site, causing a
+ * spurious mismatch. The runtime is unaffected.
+ */
+export declare function registerAllCommands(program: any): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAmCH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC;AAEpE,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,EAAE,mBAAmB,CAAC;IACxC,iEAAiE;IACjE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,UAAU,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IAC/E,0EAA0E;IAC1E,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpD;AAMD;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,cAAc,EAgQ3D,CAAC;AAMF;;;;;GAKG;AACH,wBAAgB,uBAAuB,IAAI,SAAS,cAAc,EAAE,CAEnE;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,GAAG,GAAG,IAAI,CAWtD"}