@undefineds.co/xpod 0.3.56 → 0.3.58

package/dist/cli/commands/obj.js

@@ -1,16 +1,28 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.objCommand = void 0;
+exports.resolveObjMutationContext = resolveObjMutationContext;
+exports.getObjLocalOutboxPath = getObjLocalOutboxPath;
 exports.redactDescriptorObject = redactDescriptorObject;
+exports.serializeSchemaDescriptor = serializeSchemaDescriptor;
+exports.listSchemaDescriptors = listSchemaDescriptors;
+exports.describeSchemaDescriptor = describeSchemaDescriptor;
 exports.buildDescriptorUpsertSparql = buildDescriptorUpsertSparql;
 exports.buildDescriptorPatchSparql = buildDescriptorPatchSparql;
 exports.buildDescriptorLinkSparql = buildDescriptorLinkSparql;
 exports.buildDescriptorDeleteSparql = buildDescriptorDeleteSparql;
 exports.extractReservedWhereSelectors = extractReservedWhereSelectors;
 exports.buildDescriptorObjectQuery = buildDescriptorObjectQuery;
+exports.descriptorObjectFromTurtle = descriptorObjectFromTurtle;
+exports.descriptorUpsertPlanItem = descriptorUpsertPlanItem;
+exports.executeRows = executeRows;
+exports.mutationItemsResultCode = mutationItemsResultCode;
 const fs_1 = require("fs");
+const path_1 = require("path");
+const n3_1 = require("n3");
 const models_1 = require("@undefineds.co/models");
 const auth_context_1 = require("../lib/auth-context");
+const credentials_store_1 = require("../lib/credentials-store");
 const output_1 = require("../lib/output");
 const resource_1 = require("../lib/resource");
 const rdf_1 = require("./rdf");
@@ -93,14 +105,28 @@ async function readJsonl(input) {
 function descriptorLocalName(value) {
     return value.split(/[\/#]/u).filter(Boolean).pop() ?? value;
 }
+function normalizeDescriptorAlias(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/gu, '');
+}
+function descriptorAliases(descriptor) {
+    const discovery = descriptor;
+    return discovery.aliases?.length ? discovery.aliases : [descriptorLocalName(descriptor.class)];
+}
+function descriptorMatchesRef(descriptor, ref) {
+    const normalized = normalizeDescriptorAlias(ref);
+    return descriptor.uri === ref ||
+        descriptor.class === ref ||
+        descriptor.resourceKind.toLowerCase() === ref.trim().toLowerCase() ||
+        normalizeDescriptorAlias(descriptorLocalName(descriptor.uri)) === normalized ||
+        normalizeDescriptorAlias(descriptorLocalName(descriptor.class)) === normalized ||
+        descriptorAliases(descriptor).some((alias) => normalizeDescriptorAlias(alias) === normalized);
+}
 function resolveDescriptorOrNull(schema) {
-    const exact = models_1.podSchema.describe({ schemaUri: schema });
+    const exact = models_1.podSchema.describe({ schemaUri: schema }) ??
+        models_1.podSchema.describe?.({ alias: schema });
     if (exact)
         return exact;
-    const normalized = schema.trim().toLowerCase();
-    return models_1.podSchema.list().find((descriptor) => descriptor.resourceKind.toLowerCase() === normalized ||
-        descriptorLocalName(descriptor.uri).toLowerCase() === normalized ||
-        descriptorLocalName(descriptor.class).toLowerCase() === normalized) ?? null;
+    return models_1.podSchema.list().find((descriptor) => descriptorMatchesRef(descriptor, schema)) ?? null;
 }
 function resolveDescriptor(schema) {
     const descriptor = resolveDescriptorOrNull(schema);
@@ -112,6 +138,48 @@ function resolveDescriptor(schema) {
 function resourceUrlFromPlan(podRoot, plan) {
     return new URL(plan.resourceUri.replace(/^\/+/, ''), podRoot).toString();
 }
+async function resolveObjMutationContext(argv, commit) {
+    try {
+        return await (0, auth_context_1.requireAuthContext)(argv);
+    }
+    catch (error) {
+        const podRoot = (0, auth_context_1.normalizeBaseUrl)(argv.url ?? 'https://pod.local/');
+        const outboxPath = getObjLocalOutboxPath();
+        return {
+            baseUrl: podRoot,
+            webId: 'urn:xpod:unauthenticated',
+            podRoot,
+            baseIri: podRoot,
+            accessToken: '',
+            credentials: {
+                url: podRoot,
+                webId: 'urn:xpod:unauthenticated',
+                authType: 'client_credentials',
+                secrets: {
+                    clientId: '',
+                    clientSecret: '',
+                },
+            },
+            ...(commit
+                ? {
+                    pendingOnly: true,
+                    outboxPath,
+                    pendingWarning: `No Solid credentials found; mutation was written to local xpod outbox at ${outboxPath} and was not saved to a Pod.`,
+                }
+                : {
+                    planningOnly: true,
+                    planningWarning: 'No Solid credentials found; this is an offline dry-run plan and was not saved to a Pod.',
+                }),
+        };
+    }
+}
+function getObjLocalOutboxPath() {
+    return (0, path_1.join)((0, credentials_store_1.getSolidHomeDir)(), 'apps', 'xpod', 'outbox', 'obj-mutations.jsonl');
+}
+function appendObjLocalOutbox(entry, outboxPath = getObjLocalOutboxPath()) {
+    (0, fs_1.mkdirSync)((0, path_1.dirname)(outboxPath), { recursive: true });
+    (0, fs_1.appendFileSync)(outboxPath, `${JSON.stringify(entry)}\n`, 'utf-8');
+}
 function varName(field) {
     return `v_${field.replace(/[^A-Za-z0-9_]/gu, '_')}`;
 }
@@ -159,6 +227,47 @@ function redactDescriptorObject(descriptor, value) {
     }
     return redacted;
 }
+function serializeSchemaDescriptor(descriptor) {
+    const discovery = descriptor;
+    return {
+        schema: descriptor.uri,
+        uri: descriptor.uri,
+        alias: descriptorAliases(descriptor)[0] ?? descriptor.resourceKind,
+        aliases: descriptorAliases(descriptor),
+        domains: discovery.domains ?? [],
+        version: descriptor.version,
+        source: descriptor.source,
+        trustLevel: descriptor.trustLevel,
+        namespace: descriptor.namespace,
+        class: descriptor.class,
+        resourceKind: descriptor.resourceKind,
+        description: descriptor.description,
+        storage: descriptor.storage,
+        idSemantics: discovery.idSemantics ?? null,
+        relationFields: discovery.relationFields ?? Object.entries(descriptor.fields)
+            .filter(([, field]) => field.type === 'uri')
+            .map(([field]) => field),
+        documentPathPolicy: discovery.documentPathPolicy ?? null,
+        fields: descriptor.fields,
+        requiredFields: Object.entries(descriptor.fields)
+            .filter(([, field]) => field.required)
+            .map(([field]) => field),
+        uniqueBy: descriptor.uniqueBy,
+        writableFields: descriptor.writableFields,
+        mergePolicy: descriptor.mergePolicy,
+        exampleInput: discovery.exampleInput ?? descriptor.examples[0] ?? null,
+        examples: descriptor.examples,
+    };
+}
+function listSchemaDescriptors(input = {}, descriptors = models_1.podSchema.list()) {
+    return descriptors
+        .filter((descriptor) => !input.domain || (descriptor.domains ?? []).includes(input.domain))
+        .map(serializeSchemaDescriptor);
+}
+function describeSchemaDescriptor(schemaOrAlias, descriptors = models_1.podSchema.list()) {
+    const descriptor = descriptors.find((item) => descriptorMatchesRef(item, schemaOrAlias));
+    return descriptor ? serializeSchemaDescriptor(descriptor) : null;
+}
 function buildDescriptorUpsertSparql(descriptor, subject, row) {
     const fields = descriptor.fields;
     const match = row.match ?? {};
@@ -167,15 +276,17 @@ function buildDescriptorUpsertSparql(descriptor, subject, row) {
     assertWritableFields(descriptor, set);
     const merged = { ...match, ...set };
     const deleteFields = Object.keys(set).filter((field) => fields[field]);
-    const deletes = deleteFields.map((field) => `<${subject}> <${fields[field].predicate}> ?old_${field.replace(/[^A-Za-z0-9_]/gu, '_')} .`);
-    const optionals = deleteFields.map((field) => `OPTIONAL { <${subject}> <${fields[field].predicate}> ?old_${field.replace(/[^A-Za-z0-9_]/gu, '_')} }`);
+    const deletes = deleteFields.map((field) => `DELETE WHERE {\n  <${subject}> <${fields[field].predicate}> ?old_${field.replace(/[^A-Za-z0-9_]/gu, '_')} .\n}`);
     const inserts = [
         `<${subject}> a <${descriptor.class}>`,
         ...Object.entries(merged)
             .filter(([field, value]) => fields[field] && value !== undefined && value !== null)
             .map(([field, value]) => `<${subject}> <${fields[field].predicate}> ${sparqlValue(value, fields[field])}`),
     ];
-    return `DELETE {\n  ${deletes.join('\n  ')}\n}\nINSERT {\n  ${inserts.join(' .\n  ')} .\n}\nWHERE {\n  ${optionals.join('\n  ')}\n}`;
+    return [
+        ...deletes,
+        `INSERT DATA {\n  ${inserts.join(' .\n  ')} .\n}`,
+    ].join(';\n');
 }
 function buildDescriptorPatchSparql(descriptor, subject, set) {
     return buildDescriptorUpsertSparql(descriptor, subject, { set });
@@ -382,6 +493,42 @@ function bindingToValue(binding, field) {
     }
     return binding.value;
 }
+function descriptorObjectFromTurtle(descriptor, subject, resourceUrl, turtle) {
+    const quads = new n3_1.Parser({ baseIRI: resourceUrl }).parse(turtle);
+    const object = {};
+    let hasDescriptorType = false;
+    for (const quad of quads) {
+        if (quad.subject.value !== subject)
+            continue;
+        if (quad.predicate.value === 'http://www.w3.org/1999/02/22-rdf-syntax-ns#type' &&
+            quad.object.value === descriptor.class) {
+            hasDescriptorType = true;
+        }
+    }
+    for (const [field, descriptorField] of Object.entries(descriptor.fields)) {
+        const quad = quads.find((item) => item.subject.value === subject &&
+            item.predicate.value === descriptorField.predicate);
+        if (!quad)
+            continue;
+        const value = bindingToValue({
+            type: quad.object.termType === 'NamedNode' ? 'uri' : 'literal',
+            value: quad.object.value,
+            datatype: 'datatype' in quad.object ? quad.object.datatype.value : undefined,
+        }, descriptorField);
+        if (value !== undefined) {
+            object[field] = descriptorField.secret ? '[redacted]' : value;
+        }
+    }
+    if (!hasDescriptorType && Object.keys(object).length === 0) {
+        return null;
+    }
+    return {
+        schema: descriptor.uri,
+        subject,
+        resourceUrl,
+        object,
+    };
+}
 async function applyEtags(context, objects) {
     const cache = new Map();
     for (const object of objects) {
@@ -417,6 +564,12 @@ async function queryDescriptorObjects(context, selector) {
         },
         body: query,
     });
+    if (!response.ok) {
+        const fallback = await queryDescriptorObjectFromResource(context, selector);
+        if (fallback) {
+            return fallback;
+        }
+    }
     (0, resource_1.ensureOk)(response, 'obj_query_failed', `Failed to list objects for ${selector.descriptor.uri}`);
     const result = (await response.json());
     const objects = (result.results?.bindings ?? []).flatMap((binding) => {
@@ -442,6 +595,31 @@ async function queryDescriptorObjects(context, selector) {
     }
     return objects;
 }
+async function queryDescriptorObjectFromResource(context, selector) {
+    if (!selector.subject)
+        return null;
+    if (Object.keys(selector.where).length > 0)
+        return null;
+    if (Object.keys(selector.relations).length > 0)
+        return null;
+    const resourceUrl = (0, rdf_1.documentResourceInput)(selector.subject);
+    const target = (0, resource_1.resolveResourceTarget)(context, resourceUrl);
+    const response = await (0, resource_1.fetchResource)(context, target, {
+        method: 'GET',
+        headers: { Accept: 'text/turtle' },
+    });
+    if (response.status === 404)
+        return [];
+    if (!response.ok)
+        return null;
+    const turtle = await response.text();
+    const object = descriptorObjectFromTurtle(selector.descriptor, selector.subject, target.resourceUrl, turtle);
+    const objects = object ? [object] : [];
+    if (selector.includeMetadata) {
+        await applyEtags(context, objects);
+    }
+    return objects;
+}
 function jsonlForObjects(objects) {
     return `${objects.map((object, index) => JSON.stringify({
         index,
@@ -701,36 +879,51 @@ async function executeDescriptorRow(context, row, index, commit) {
         }
         throw new output_1.CliCommandError('unsupported_operation', `Unsupported object operation: ${op}`, 2);
     }
-    const storage = (0, models_1.createPodStorage)();
+    const item = descriptorUpsertPlanItem({
+        descriptor,
+        index,
+        commit,
+        podRoot: context.podRoot,
+        row,
+    });
+    const subject = String(item.subject);
+    if (commit) {
+        const sparql = buildDescriptorUpsertSparql(descriptor, subject, row);
+        await patchSubject({ context, subject, sparql, ifMatch: row.ifMatch, errorCode: 'obj_commit_failed' });
+    }
+    return item;
+}
+function descriptorUpsertPlanItem(input) {
+    const storage = (0, models_1.createPodStorage)((0, models_1.createPodModelDescriptorRegistry)([input.descriptor]));
     const validation = storage.validate({
-        schemaUri: descriptor.uri,
+        schemaUri: input.descriptor.uri,
         operation: 'upsert',
-        match: row.match ?? {},
-        set: row.set ?? {},
+        match: input.row.match ?? {},
+        set: input.row.set ?? {},
     });
     if (!validation.ok) {
         throw new output_1.CliCommandError(validation.error.code, validation.error.message, 2);
     }
-    const subject = resourceUrlFromPlan(context.podRoot, validation.plan);
-    if (commit) {
-        const sparql = buildDescriptorUpsertSparql(descriptor, subject, row);
-        await patchSubject({ context, subject, sparql, ifMatch: row.ifMatch, errorCode: 'obj_commit_failed' });
-    }
+    const discovery = input.descriptor;
+    const subject = resourceUrlFromPlan(input.podRoot, validation.plan);
     return {
-        index,
+        index: input.index,
         ok: true,
-        code: commit ? 'committed' : 'plan_ready',
-        operation: op,
-        schema: descriptor.uri,
+        code: input.commit ? 'committed' : 'plan_ready',
+        operation: input.row.op ?? 'upsert',
+        schema: input.descriptor.uri,
         subject,
         resourceUrl: (0, rdf_1.documentResourceInput)(subject),
         planId: validation.plan.id,
-        match: redactDescriptorObject(descriptor, row.match ?? {}),
-        set: redactDescriptorObject(descriptor, row.set ?? {}),
+        resourceId: validation.plan.resourceId,
+        resourceUri: validation.plan.resourceUri,
+        documentPathPolicy: discovery.documentPathPolicy ?? null,
+        match: redactDescriptorObject(input.descriptor, input.row.match ?? {}),
+        set: redactDescriptorObject(input.descriptor, input.row.set ?? {}),
     };
 }
 async function executeRows(input) {
-    const context = await (0, auth_context_1.requireAuthContext)(input.argv);
+    const context = await resolveObjMutationContext(input.argv, input.commit);
     const items = [];
     for (const [index, originalRow] of input.rows.entries()) {
         const row = {
@@ -738,10 +931,44 @@ async function executeRows(input) {
             schema: originalRow.schema ?? input.defaultSchema,
         };
         try {
+            const shouldCommitToPod = input.commit && !context.pendingOnly;
             const item = row.schema
-                ? await executeDescriptorRow(context, row, index, input.commit)
-                : await executeRawRow(context, row, index, input.commit);
-            items.push(item);
+                ? await executeDescriptorRow(context, row, index, shouldCommitToPod)
+                : await executeRawRow(context, row, index, shouldCommitToPod);
+            if (context.pendingOnly && input.commit) {
+                const outboxPath = context.outboxPath ?? getObjLocalOutboxPath();
+                appendObjLocalOutbox({
+                    kind: 'xpod.obj.mutation',
+                    version: 1,
+                    status: 'pending',
+                    createdAt: new Date().toISOString(),
+                    webId: context.webId,
+                    podRoot: context.podRoot,
+                    row,
+                    item,
+                }, outboxPath);
+                items.push({
+                    ...item,
+                    code: 'pending_local',
+                    pendingLocal: true,
+                    outboxPath,
+                    warnings: [
+                        ...(Array.isArray(item.warnings) ? item.warnings : []),
+                        context.pendingWarning,
+                    ],
+                });
+                continue;
+            }
+            items.push(context.planningOnly
+                ? {
+                    ...item,
+                    planningOnly: true,
+                    warnings: [
+                        ...(Array.isArray(item.warnings) ? item.warnings : []),
+                        context.planningWarning,
+                    ],
+                }
+                : item);
         }
         catch (error) {
             const err = error instanceof output_1.CliCommandError
@@ -752,11 +979,61 @@ async function executeRows(input) {
     }
     return items;
 }
+function mutationItemsResultCode(items, commit) {
+    if (!items.every((item) => item.ok))
+        return 'partial_failure';
+    if (items.some((item) => item.code === 'pending_local'))
+        return 'pending_local';
+    return commit ? 'committed' : 'plan_ready';
+}
 function printItems(items) {
     for (const item of items) {
         console.log(`${item.index}\t${item.ok ? item.code : `ERROR ${item.code}`}\t${String(item.subject ?? item.resourceUrl ?? item.message ?? '')}`);
     }
 }
+const schemasCommand = {
+    command: 'schemas',
+    describe: 'List model-backed object schemas available to AI tools',
+    builder: (yargs) => objOptions(yargs)
+        .option('domain', { type: 'string', description: 'Filter schemas by domain such as capture or symphony' }),
+    handler: async (argv) => {
+        try {
+            const schemas = listSchemaDescriptors({ domain: argv.domain });
+            if (argv.json) {
+                (0, output_1.writeJsonResult)({ schemas }, 'schemas');
+                return;
+            }
+            for (const descriptor of schemas) {
+                console.log(`${String(descriptor.alias)}\t${String(descriptor.schema)}\t${String(descriptor.resourceKind)}`);
+            }
+        }
+        catch (error) {
+            (0, output_1.handleCliError)(error, argv.json);
+        }
+    },
+};
+const describeCommand = {
+    command: 'describe <schema>',
+    describe: 'Describe one model-backed object schema by URI or alias',
+    builder: (yargs) => objOptions(yargs)
+        .positional('schema', { type: 'string', demandOption: true, description: 'Schema URI or descriptor alias' }),
+    handler: async (argv) => {
+        try {
+            const descriptor = describeSchemaDescriptor(argv.schema);
+            if (!descriptor) {
+                throw new output_1.CliCommandError('schema_unknown', `Schema is not known by @undefineds.co/models: ${argv.schema}`, 2);
+            }
+            if (argv.json) {
+                (0, output_1.writeJsonResult)({ descriptor }, 'schema');
+                return;
+            }
+            console.log(JSON.stringify(descriptor, null, 2));
+        }
+        catch (error) {
+            (0, output_1.handleCliError)(error, argv.json);
+        }
+    },
+};
 const importCommand = {
     command: 'import <file>',
     describe: 'Import descriptor-backed or explicit raw JSONL rows',
@@ -772,9 +1049,7 @@ const importCommand = {
                 rows: await readJsonl(argv.file),
                 commit: argv.commit === true,
             });
-            const code = items.every((item) => item.ok)
-                ? (argv.commit ? 'committed' : 'plan_ready')
-                : 'partial_failure';
+            const code = mutationItemsResultCode(items, argv.commit === true);
             if (argv.json) {
                 (0, output_1.writeJsonItems)(items, code);
                 return;
@@ -794,6 +1069,7 @@ const upsertCommand = {
     builder: (yargs) => objOptions(yargs)
         .option('schema', { type: 'string', demandOption: true, description: 'Schema URI or descriptor alias' })
         .option('from', { type: 'string', demandOption: true, description: 'JSONL file to read, or - for stdin' })
+        .nargs('from', 1)
         .option('dry-run', { type: 'boolean', description: 'Validate and print a plan without writing' })
         .option('commit', { type: 'boolean', description: 'Commit the validated mutations' })
         .check(mutationModeCheck),
@@ -805,9 +1081,7 @@ const upsertCommand = {
                 defaultSchema: resolveDescriptor(argv.schema).uri,
                 commit: argv.commit === true,
             });
-            const code = items.every((item) => item.ok)
-                ? (argv.commit ? 'committed' : 'plan_ready')
-                : 'partial_failure';
+            const code = mutationItemsResultCode(items, argv.commit === true);
             if (argv.json) {
                 (0, output_1.writeJsonItems)(items, code);
                 return;
@@ -1044,6 +1318,8 @@ exports.objCommand = {
     command: 'obj',
     describe: 'Descriptor-backed object transport',
     builder: (yargs) => yargs
+        .command(schemasCommand)
+        .command(describeCommand)
         .command(exportCommand)
         .command(importCommand)
         .command(getCommand)