@interop/did-cli 0.6.0 → 0.8.0

package/dist/commands/was/resource.js

@@ -0,0 +1,402 @@
+/**
+ * `was resource` run functions: add (server-generated id), put (upsert at a
+ * known id), get (JSON or binary), list, delete, and the resource-metadata
+ * verbs `meta get` / `meta put`. Each addressing-capable verb accepts either
+ * a path or a `--capability` targeting the resource or its collection.
+ */
+import { readFile } from 'node:fs/promises';
+import { resolveWasTarget } from '../../was/client.js';
+import { resolveCapabilityTarget } from '../../was/capability.js';
+import { readPayload, writeResourceOutput } from '../../was/io.js';
+import { assertOneAddressing, printResourceListing, reportError, requireCollectionTarget, requireResourceTarget, wasUrl } from './shared.js';
+/**
+ * Resolves a single resource handle and its URL from either a path address
+ * or a `--capability` targeting a resource -- the shared addressing logic of
+ * the resource verbs that operate on one resource (`put`, `get`, `meta`).
+ *
+ * @param options {object}
+ * @param [options.address] {string}   The resource address.
+ * @param [options.capability] {string}   A capability reference instead of
+ *   a path.
+ * @param options.verb {string}   The verb name, for the capability-depth
+ *   error message.
+ * @param [options.server] {string}   The server base URL.
+ * @param [options.did] {string}   The signing DID or stored-DID handle.
+ * @returns {Promise<{resource: Resource, url: string}>}
+ */
+async function resolveResourceHandle({ address, capability, verb, server, did }) {
+    assertOneAddressing({ address, capability });
+    if (capability) {
+        const resolved = await resolveCapabilityTarget({ ref: capability, did });
+        if (resolved.depth !== 'resource') {
+            throw new Error(`The capability targets a ${resolved.depth}; ` +
+                `${verb} needs a resource capability.`);
+        }
+        return { resource: resolved.handle, url: resolved.url };
+    }
+    const target = requireResourceTarget({
+        target: await resolveWasTarget({
+            address: address,
+            server,
+            did
+        }),
+        address: address
+    });
+    const resource = target.client
+        .space(target.spaceId)
+        .collection(target.collectionId)
+        .resource(target.resourceId);
+    const url = wasUrl({
+        server: target.server,
+        spaceId: target.spaceId,
+        collectionId: target.collectionId,
+        resourceId: target.resourceId
+    });
+    return { resource, url };
+}
+/**
+ * Adds a resource to a collection (server-generated id) and prints the
+ * `{ id, url, contentType }` add result. The collection comes from a path
+ * or a `--capability` targeting one.
+ *
+ * @param options {object}
+ * @param [options.address] {string}   The collection address.
+ * @param [options.capability] {string}   A capability reference instead of
+ *   a path.
+ * @param [options.file] {string}   The payload file; stdin when omitted.
+ * @param [options.contentType] {string}   Explicit payload content type.
+ * @param [options.server] {string}   The server base URL.
+ * @param [options.did] {string}   The signing DID or stored-DID handle.
+ * @returns {Promise<number>}   The process exit code.
+ */
+export async function runResourceAdd(options) {
+    try {
+        assertOneAddressing(options);
+        let collection;
+        if (options.capability) {
+            const resolved = await resolveCapabilityTarget({
+                ref: options.capability,
+                did: options.did
+            });
+            if (resolved.depth !== 'collection') {
+                throw new Error(`The capability targets a ${resolved.depth}; ` +
+                    'add needs a collection capability.');
+            }
+            collection = resolved.handle;
+        }
+        else {
+            const target = requireCollectionTarget({
+                target: await resolveWasTarget({
+                    address: options.address,
+                    server: options.server,
+                    did: options.did
+                }),
+                address: options.address
+            });
+            collection = target.client
+                .space(target.spaceId)
+                .collection(target.collectionId);
+        }
+        const payload = await readPayload({
+            file: options.file,
+            contentType: options.contentType
+        });
+        const result = await collection.add(payload.data, {
+            ...(payload.contentType !== undefined && {
+                contentType: payload.contentType
+            })
+        });
+        console.log(JSON.stringify(result, null, 2));
+        return 0;
+    }
+    catch (err) {
+        return reportError({ action: 'add the resource', err });
+    }
+}
+/**
+ * Creates or replaces a resource at a known id (upsert) and prints
+ * `{ id, url }`. The resource comes from a path or a `--capability`
+ * targeting one.
+ *
+ * @param options {object}
+ * @param [options.address] {string}   The resource address.
+ * @param [options.capability] {string}   A capability reference instead of
+ *   a path.
+ * @param [options.file] {string}   The payload file; stdin when omitted.
+ * @param [options.contentType] {string}   Explicit payload content type.
+ * @param [options.server] {string}   The server base URL.
+ * @param [options.did] {string}   The signing DID or stored-DID handle.
+ * @returns {Promise<number>}   The process exit code.
+ */
+export async function runResourcePut(options) {
+    try {
+        const { resource, url } = await resolveResourceHandle({
+            ...options,
+            verb: 'put'
+        });
+        const payload = await readPayload({
+            file: options.file,
+            contentType: options.contentType
+        });
+        await resource.put(payload.data, {
+            ...(payload.contentType !== undefined && {
+                contentType: payload.contentType
+            })
+        });
+        console.log(JSON.stringify({ id: resource.id, url }, null, 2));
+        return 0;
+    }
+    catch (err) {
+        return reportError({ action: 'put the resource', err });
+    }
+}
+/**
+ * Reads a resource: JSON pretty-printed to stdout, binary written raw
+ * (`--output` for files). The resource comes from a path or a
+ * `--capability` targeting one.
+ *
+ * @param options {object}
+ * @param [options.address] {string}   The resource address.
+ * @param [options.capability] {string}   A capability reference instead of
+ *   a path.
+ * @param [options.output] {string}   The output file path; stdout when
+ *   omitted.
+ * @param [options.server] {string}   The server base URL.
+ * @param [options.did] {string}   The signing DID or stored-DID handle.
+ * @returns {Promise<number>}   The process exit code.
+ */
+export async function runResourceGet(options) {
+    try {
+        const { resource, url } = await resolveResourceHandle({
+            ...options,
+            verb: 'get'
+        });
+        const data = await resource.get();
+        if (data === null) {
+            console.error(`Not found (or not visible to you): ${url}`);
+            return 1;
+        }
+        await writeResourceOutput({ data, output: options.output });
+        return 0;
+    }
+    catch (err) {
+        return reportError({ action: 'get the resource', err });
+    }
+}
+/**
+ * Reads a resource's metadata object (server-managed `contentType` / `size` /
+ * timestamps plus the user-writable `custom`) and pretty-prints it. The
+ * resource comes from a path or a `--capability` targeting one.
+ *
+ * @param options {object}
+ * @param [options.address] {string}   The resource address.
+ * @param [options.capability] {string}   A capability reference instead of
+ *   a path.
+ * @param [options.server] {string}   The server base URL.
+ * @param [options.did] {string}   The signing DID or stored-DID handle.
+ * @returns {Promise<number>}   The process exit code.
+ */
+export async function runResourceMetaGet(options) {
+    try {
+        const { resource, url } = await resolveResourceHandle({
+            ...options,
+            verb: 'meta get'
+        });
+        const meta = await resource.meta();
+        if (meta === null) {
+            console.error(`Not found (or not visible to you): ${url}`);
+            return 1;
+        }
+        console.log(JSON.stringify(meta, null, 2));
+        return 0;
+    }
+    catch (err) {
+        return reportError({ action: 'get the resource metadata', err });
+    }
+}
+/**
+ * Parses the repeatable `--tag key=value` flags into a tags record. Returns
+ * `undefined` when no `--tag` was given (so the caller can leave tags
+ * untouched).
+ *
+ * @param rawTags {string[]}   The raw `key=value` strings, as collected.
+ * @returns {Record<string, string> | undefined}
+ */
+function parseTags(rawTags) {
+    if (rawTags.length === 0) {
+        return undefined;
+    }
+    const tags = {};
+    for (const entry of rawTags) {
+        const separator = entry.indexOf('=');
+        const key = separator === -1 ? entry : entry.slice(0, separator);
+        if (separator === -1 || key === '') {
+            throw new Error(`Invalid --tag "${entry}"; expected key=value.`);
+        }
+        tags[key] = entry.slice(separator + 1);
+    }
+    return tags;
+}
+/**
+ * Parses the `--json` escape hatch -- inline JSON, or a path to a JSON file
+ * when the value does not itself parse -- into a `custom` metadata object.
+ *
+ * @param input {string}   Inline JSON or a JSON file path.
+ * @returns {Promise<ResourceMetadataCustom>}
+ */
+async function parseCustomJson(input) {
+    let parsed;
+    try {
+        parsed = JSON.parse(input);
+    }
+    catch {
+        let contents;
+        try {
+            contents = await readFile(input, 'utf8');
+        }
+        catch {
+            throw new Error(`--json is neither valid JSON nor a readable file: ${input}`);
+        }
+        parsed = JSON.parse(contents);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error('--json must be a JSON object (the custom metadata).');
+    }
+    return parsed;
+}
+/**
+ * Updates a resource's user-writable metadata and prints the resulting
+ * metadata. `--name`/`--tag` are read-modify-write sugar that preserve the
+ * other field; giving both, or `--json`, is a full `custom` replacement so
+ * any omitted property is cleared. The resource comes from a path or a
+ * `--capability` targeting one.
+ *
+ * @param options {object}
+ * @param [options.address] {string}   The resource address.
+ * @param [options.capability] {string}   A capability reference instead of
+ *   a path.
+ * @param [options.name] {string}   The resource's display name.
+ * @param options.tag {string[]}   Repeatable `key=value` tag pairs.
+ * @param [options.json] {string}   Full `custom` JSON (inline or a file
+ *   path); mutually exclusive with `--name`/`--tag`.
+ * @param [options.server] {string}   The server base URL.
+ * @param [options.did] {string}   The signing DID or stored-DID handle.
+ * @returns {Promise<number>}   The process exit code.
+ */
+export async function runResourceMetaPut(options) {
+    try {
+        const tags = parseTags(options.tag);
+        const hasName = options.name !== undefined;
+        const hasTags = tags !== undefined;
+        const hasJson = options.json !== undefined;
+        if (hasJson && (hasName || hasTags)) {
+            throw new Error('Provide either --json or --name/--tag, not both.');
+        }
+        if (!hasJson && !hasName && !hasTags) {
+            throw new Error('Provide --name, --tag <key=value>, or --json.');
+        }
+        const { resource, url } = await resolveResourceHandle({
+            ...options,
+            verb: 'meta put'
+        });
+        if (hasJson) {
+            await resource.setMeta({ custom: await parseCustomJson(options.json) });
+        }
+        else if (hasName && hasTags) {
+            await resource.setMeta({ custom: { name: options.name, tags } });
+        }
+        else if (hasName) {
+            await resource.setName(options.name);
+        }
+        else {
+            await resource.setTags(tags);
+        }
+        console.error(`Updated metadata for ${url}`);
+        const meta = await resource.meta();
+        console.log(JSON.stringify(meta, null, 2));
+        return 0;
+    }
+    catch (err) {
+        return reportError({ action: 'update the resource metadata', err });
+    }
+}
+/**
+ * Lists the resources in a collection.
+ *
+ * @param options {object}
+ * @param options.address {string}   The collection address.
+ * @param [options.json] {boolean}   Output the raw listing JSON.
+ * @param [options.plain] {boolean}   Output one resource id per line.
+ * @param [options.server] {string}   The server base URL.
+ * @param [options.did] {string}   The signing DID or stored-DID handle.
+ * @returns {Promise<number>}   The process exit code.
+ */
+export async function runResourceList(options) {
+    try {
+        const target = requireCollectionTarget({
+            target: await resolveWasTarget({
+                address: options.address,
+                server: options.server,
+                did: options.did
+            }),
+            address: options.address
+        });
+        const listing = await target.client
+            .space(target.spaceId)
+            .collection(target.collectionId)
+            .list();
+        if (listing === null) {
+            console.error('Not found (or not visible to you): ' +
+                wasUrl({
+                    server: target.server,
+                    spaceId: target.spaceId,
+                    collectionId: target.collectionId
+                }));
+            return 1;
+        }
+        printResourceListing({ listing, json: options.json, plain: options.plain });
+        return 0;
+    }
+    catch (err) {
+        return reportError({ action: 'list resources', err });
+    }
+}
+/**
+ * Deletes a resource on the server. Idempotent.
+ *
+ * @param options {object}
+ * @param options.address {string}   The resource address.
+ * @param [options.server] {string}   The server base URL.
+ * @param [options.did] {string}   The signing DID or stored-DID handle.
+ * @returns {Promise<number>}   The process exit code.
+ */
+export async function runResourceDelete(options) {
+    try {
+        const target = requireResourceTarget({
+            target: await resolveWasTarget({
+                address: options.address,
+                server: options.server,
+                did: options.did
+            }),
+            address: options.address
+        });
+        await target.client
+            .space(target.spaceId)
+            .collection(target.collectionId)
+            .resource(target.resourceId)
+            .delete();
+        console.error('Deleted ' +
+            wasUrl({
+                server: target.server,
+                spaceId: target.spaceId,
+                collectionId: target.collectionId,
+                resourceId: target.resourceId
+            }) +
+            ' on the server.');
+        return 0;
+    }
+    catch (err) {
+        return reportError({ action: 'delete the resource', err });
+    }
+}
+//# sourceMappingURL=resource.js.map

package/dist/commands/was/resource.js.map

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

package/dist/commands/was/shared.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Shared helpers for the `was` command group: option factories, address
+ * parsing/assertion, URL building, error reporting, listing renderers, and
+ * the run-and-exit wrapper. Commander `Option` instances are bound to the
+ * command they are added to, so the options are exposed as factories.
+ */
+import { Option } from 'commander';
+import { type Collection, type CollectionsList, type Resource, type CollectionResourcesList, type Space } from '@interop/was-client';
+import { type ResolvedWasTarget } from '../../was/client.js';
+/**
+ * Awaits a command's run function and exits the process with its code when
+ * non-zero -- the shared tail of every `was` command action.
+ *
+ * @param run {Promise<number>}
+ * @returns {Promise<void>}
+ */
+export declare function runAndExit(run: Promise<number>): Promise<void>;
+/**
+ * The shared command options, as factories (commander `Option` instances
+ * are bound to the command they are added to, so they cannot be shared).
+ * Centralizing them keeps the flag names and help text consistent across
+ * the whole command tree.
+ *
+ * @returns {Option}
+ */
+export declare function serverOption(): Option;
+export declare function didOption(): Option;
+export declare function capabilityOption(): Option;
+export declare function contentTypeOption(): Option;
+/**
+ * Guards a run function against receiving both path- and capability-based
+ * addressing (or neither).
+ *
+ * @param options {object}
+ * @param [options.address] {string}
+ * @param [options.capability] {string}
+ * @returns {void}
+ */
+export declare function assertOneAddressing({ address, capability }: {
+    address?: string;
+    capability?: string;
+}): void;
+/**
+ * Builds the canonical URL of a space, collection, or resource on its
+ * server, for messages and output.
+ *
+ * @param options {object}
+ * @param options.server {string}
+ * @param options.spaceId {string}
+ * @param [options.collectionId] {string}
+ * @param [options.resourceId] {string}
+ * @returns {string}
+ */
+export declare function wasUrl({ server, spaceId, collectionId, resourceId }: {
+    server: string;
+    spaceId: string;
+    collectionId?: string;
+    resourceId?: string;
+}): string;
+/**
+ * Prints a one-line error for a failed command and classifies its exit code:
+ * 1 for operation errors (typed WAS errors from the server exchange), 2 for
+ * input errors (bad addresses, unknown handles/DIDs, missing server URL).
+ *
+ * @param options {object}
+ * @param options.action {string}   What failed, e.g. `create the space`.
+ * @param options.err {unknown}
+ * @returns {number}   The process exit code.
+ */
+export declare function reportError({ action, err }: {
+    action: string;
+    err: unknown;
+}): number;
+/**
+ * Parses a WAS address and asserts it addresses a space only (no
+ * collection/resource segments), as the `space` subcommands require.
+ *
+ * @param address {string}
+ * @returns {{server?: string, spaceRef: string}}
+ */
+export declare function parseSpaceAddress(address: string): {
+    server?: string;
+    spaceRef: string;
+};
+/**
+ * Asserts a resolved target addresses a collection (`SPACE/COLLECTION`,
+ * no resource segment) and narrows its type accordingly.
+ *
+ * @param options {object}
+ * @param options.target {ResolvedWasTarget}
+ * @param options.address {string}   The original address, for error messages.
+ * @returns {ResolvedWasTarget & {collectionId: string}}
+ */
+export declare function requireCollectionTarget({ target, address }: {
+    target: ResolvedWasTarget;
+    address: string;
+}): ResolvedWasTarget & {
+    collectionId: string;
+};
+/**
+ * Asserts a resolved target addresses a resource
+ * (`SPACE/COLLECTION/RESOURCE`) and narrows its type accordingly.
+ *
+ * @param options {object}
+ * @param options.target {ResolvedWasTarget}
+ * @param options.address {string}   The original address, for error messages.
+ * @returns {ResolvedWasTarget & {collectionId: string, resourceId: string}}
+ */
+export declare function requireResourceTarget({ target, address }: {
+    target: ResolvedWasTarget;
+    address: string;
+}): ResolvedWasTarget & {
+    collectionId: string;
+    resourceId: string;
+};
+/**
+ * Renders a collection listing as a table, raw JSON, or one id per line.
+ *
+ * @param options {object}
+ * @param options.listing {CollectionsList}
+ * @param [options.json] {boolean}
+ * @param [options.plain] {boolean}
+ * @returns {void}
+ */
+export declare function printCollectionListing({ listing, json, plain }: {
+    listing: CollectionsList;
+    json?: boolean;
+    plain?: boolean;
+}): void;
+/**
+ * Renders a resource listing as a table, raw JSON, or one id per line.
+ *
+ * @param options {object}
+ * @param options.listing {CollectionResourcesList}
+ * @param [options.json] {boolean}
+ * @param [options.plain] {boolean}
+ * @returns {void}
+ */
+export declare function printResourceListing({ listing, json, plain }: {
+    listing: CollectionResourcesList;
+    json?: boolean;
+    plain?: boolean;
+}): void;
+/**
+ * Builds the access handle (space, collection, or resource) a resolved
+ * target addresses, together with its URL. Policies and publishing work at
+ * every depth, so these commands dispatch through this helper.
+ *
+ * @param target {ResolvedWasTarget}
+ * @returns {{handle: Space | Collection | Resource, url: string}}
+ */
+export declare function handleForTarget(target: ResolvedWasTarget): {
+    handle: Space | Collection | Resource;
+    url: string;
+};
+//# sourceMappingURL=shared.d.ts.map

package/dist/commands/was/shared.d.ts.map

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