@aopslabs/aops 0.2.0

package/dist/commands/artifact.js

@@ -0,0 +1,535 @@
+import { Command } from 'commander';
+import { logError, logSuccess } from '@aopslabs/xf-cli-ui';
+import { applyCommonOptions, compactPayload, normalizeNonEmpty } from '../utils/command.js';
+import { invokeHostedToolWithApiState, parseJsonInput, requireApiState, unwrapHostedToolResult, } from '../utils/agent-gateway.js';
+import { resolveOwnerScopeIdFromBinding, resolveOwnerScopeIdFromProjectRecord, resolveProjectBindingContext, } from '../utils/project-context.js';
+import { buildHostedSugarEnvelope, buildOperatorCookbook, ensureDestructiveWrite, ensureGuardedWrite, missingScopeIdMessage, } from '../utils/hosted-sugar.js';
+import { GUIDE_PATHS } from '../utils/guide-paths.js';
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function unwrapResultData(result) {
+    if (isRecord(result) && Object.prototype.hasOwnProperty.call(result, 'data')) {
+        return result.data;
+    }
+    return result;
+}
+function parseJsonSeed(input, label = '--input') {
+    const normalized = normalizeNonEmpty(input);
+    if (!normalized)
+        return {};
+    const parsed = parseJsonInput(normalized, label);
+    if (!isRecord(parsed))
+        throw new Error(`${label} must be a JSON object or @file.json object.`);
+    return parsed;
+}
+function parseUnknownJsonInput(input, label) {
+    const normalized = normalizeNonEmpty(input);
+    if (!normalized)
+        return undefined;
+    return parseJsonInput(normalized, label);
+}
+function resolveStringField(explicit, seed, key) {
+    return normalizeNonEmpty(explicit) ?? normalizeNonEmpty(seed[key]);
+}
+function resolveUnknownField(explicit, seed, key, label) {
+    const explicitValue = parseUnknownJsonInput(explicit, label);
+    if (explicitValue !== undefined)
+        return explicitValue;
+    return seed[key];
+}
+function toInteger(value, label) {
+    if (typeof value === 'number' && Number.isInteger(value))
+        return value;
+    const normalized = normalizeNonEmpty(value);
+    if (!normalized)
+        throw new Error(`${label} must be an integer.`);
+    const parsed = Number.parseInt(normalized, 10);
+    if (!Number.isInteger(parsed))
+        throw new Error(`${label} must be an integer.`);
+    return parsed;
+}
+function resolveIntegerField(explicit, seed, key, label) {
+    if (explicit !== undefined && explicit !== null && explicit !== '')
+        return toInteger(explicit, label);
+    if (seed[key] !== undefined && seed[key] !== null && seed[key] !== '')
+        return toInteger(seed[key], label);
+    return undefined;
+}
+function extractId(value) {
+    return normalizeNonEmpty(value);
+}
+function collectArtifactArtifacts(result) {
+    const root = unwrapResultData(result) ?? (isRecord(result) ? result : {});
+    const artifacts = {};
+    const push = (key, value) => {
+        const normalized = extractId(value);
+        if (normalized)
+            artifacts[key] = normalized;
+    };
+    push('artifactId', root.artifactId);
+    if (!artifacts.artifactId)
+        push('artifactId', root.id);
+    push('artifactLinkId', root.artifactLinkId);
+    if (!artifacts.artifactLinkId && normalizeNonEmpty(root.artifactId))
+        push('artifactLinkId', root.id);
+    return Object.keys(artifacts).length > 0 ? artifacts : undefined;
+}
+function jsonByteLength(value) {
+    try {
+        return Buffer.byteLength(JSON.stringify(value), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+function summarizeText(value, maxLength = 180) {
+    const text = normalizeNonEmpty(value);
+    if (!text)
+        return undefined;
+    if (text.length <= maxLength)
+        return text;
+    return `${text.slice(0, maxLength - 3)}...`;
+}
+function summarizeMeta(value) {
+    if (value === undefined)
+        return undefined;
+    if (isRecord(value)) {
+        const keys = Object.keys(value).sort();
+        return compactPayload({
+            kind: 'object',
+            keyCount: keys.length,
+            keys,
+            bytes: jsonByteLength(value),
+        });
+    }
+    if (Array.isArray(value)) {
+        return compactPayload({
+            kind: 'array',
+            length: value.length,
+            bytes: jsonByteLength(value),
+        });
+    }
+    return compactPayload({
+        kind: value === null ? 'null' : typeof value,
+        bytes: jsonByteLength(value),
+        preview: summarizeText(value, 80),
+    });
+}
+function summarizeArtifactRecord(value) {
+    if (!isRecord(value))
+        return value;
+    return compactPayload({
+        id: normalizeNonEmpty(value.id),
+        scopeId: normalizeNonEmpty(value.scopeId),
+        artifactType: normalizeNonEmpty(value.artifactType),
+        label: summarizeText(value.label),
+        storagePath: normalizeNonEmpty(value.storagePath),
+        mimeType: normalizeNonEmpty(value.mimeType),
+        sizeBytes: typeof value.sizeBytes === 'number' ? value.sizeBytes : undefined,
+        hash: normalizeNonEmpty(value.hash),
+        metaSummary: summarizeMeta(value.meta),
+        createdAt: normalizeNonEmpty(value.createdAt),
+        updatedAt: normalizeNonEmpty(value.updatedAt),
+    });
+}
+function summarizeArtifactGetResult(result) {
+    if (isRecord(result) && Object.prototype.hasOwnProperty.call(result, 'data')) {
+        return {
+            ...result,
+            data: summarizeArtifactRecord(result.data),
+            summary: {
+                ...(isRecord(result.summary) ? result.summary : {}),
+                mode: 'artifact-get-summary',
+                omitted: ['meta'],
+                fullRecordHint: 'Use `aops-cli artifact get --id <artifact-id> --json` without --summary for full metadata.',
+            },
+        };
+    }
+    return summarizeArtifactRecord(result);
+}
+function summarizeArtifactRefListResult(result) {
+    if (Array.isArray(result))
+        return result.map(summarizeArtifactRecord);
+    if (isRecord(result) && Array.isArray(result.data)) {
+        const data = result.data.map(summarizeArtifactRecord);
+        return {
+            ...result,
+            data,
+            summary: {
+                ...(isRecord(result.summary) ? result.summary : {}),
+                mode: 'artifact-ref-list-summary',
+                count: data.length,
+                omitted: ['meta'],
+                fullRecordHint: 'Use `aops-cli artifact get --id <artifact-id> --json` for full metadata.',
+            },
+        };
+    }
+    return summarizeArtifactGetResult(result);
+}
+function buildGatewayOptions(options, resolvedContext) {
+    return {
+        ...options,
+        projectId: normalizeNonEmpty(options.projectId) ?? normalizeNonEmpty(resolvedContext.projectId),
+        projectName: normalizeNonEmpty(options.projectName) ?? normalizeNonEmpty(resolvedContext.projectName),
+    };
+}
+async function hydrateProjectContext(apiState, options, resolvedContext) {
+    const projectId = normalizeNonEmpty(resolvedContext.projectId);
+    if (!projectId)
+        return resolvedContext;
+    if (normalizeNonEmpty(resolvedContext.scopeId) === projectId && normalizeNonEmpty(resolvedContext.projectName)) {
+        return resolvedContext;
+    }
+    const payload = await invokeHostedToolWithApiState(apiState, {
+        ...buildGatewayOptions(options, resolvedContext),
+        toolId: 'agentspace.project.get-by-id',
+        input: { id: projectId },
+    });
+    const result = unwrapHostedToolResult(payload);
+    const project = unwrapResultData(result);
+    if (!isRecord(project))
+        return resolvedContext;
+    const scopeId = resolveOwnerScopeIdFromProjectRecord(project, resolvedContext.scopeId);
+    const projectName = normalizeNonEmpty(project.name) ?? resolvedContext.projectName;
+    return {
+        ...resolvedContext,
+        scopeId,
+        projectName,
+    };
+}
+async function resolveArtifactContext(options, apiState) {
+    const resolved = await resolveProjectBindingContext(options, {
+        requireProject: false,
+    });
+    const scopeId = normalizeNonEmpty(options.scopeId) ?? resolveOwnerScopeIdFromBinding(resolved);
+    return hydrateProjectContext(apiState, options, {
+        ...resolved,
+        scopeId,
+    });
+}
+function buildResolvedContextRecord(context) {
+    return compactPayload({
+        repoRoot: context.repoRoot,
+        configPath: context.configPath,
+        configFound: context.configFound,
+        scopeId: context.scopeId,
+        projectId: context.projectId,
+        projectName: context.projectName,
+    });
+}
+const buildEnvelope = buildHostedSugarEnvelope;
+function ensureArtifactId(id, label = '--id') {
+    const resolved = normalizeNonEmpty(id);
+    if (!resolved)
+        throw new Error(`Provide ${label}.`);
+    return resolved;
+}
+function requireScopeId(context, seed) {
+    const scopeId = normalizeNonEmpty(context.scopeId) ?? normalizeNonEmpty(seed.scopeId);
+    if (!scopeId) {
+        throw new Error(missingScopeIdMessage('Artifact create'));
+    }
+    return scopeId;
+}
+function requireProjectId(context, seed) {
+    const projectId = normalizeNonEmpty(context.projectId) ??
+        normalizeNonEmpty(seed.projectId);
+    if (!projectId) {
+        throw new Error('Artifact link requires repo-bound project context or --project-id / input.projectId.');
+    }
+    return projectId;
+}
+async function invokeArtifactTool(apiState, options, resolvedContext, params) {
+    ensureGuardedWrite(options, 'This command mutates hosted artifact state.');
+    const payload = await invokeHostedToolWithApiState(apiState, {
+        ...buildGatewayOptions(options, resolvedContext),
+        tenantId: options.tenantId,
+        locale: options.locale,
+        fallbackLocale: options.fallbackLocale,
+        timeoutMs: options.timeoutMs,
+        apiBaseUrl: options.apiBaseUrl,
+        accessToken: options.accessToken,
+        refreshToken: options.refreshToken,
+        toolId: params.toolId,
+        input: params.input,
+        preview: options.preview,
+        apply: options.apply,
+        confirm: options.confirm,
+        idempotencyKey: options.idempotencyKey,
+    });
+    const result = unwrapHostedToolResult(payload);
+    if (options.json) {
+        console.log(JSON.stringify(buildEnvelope({
+            command: params.command,
+            toolId: params.toolId,
+            resolvedContext: buildResolvedContextRecord(resolvedContext),
+            input: params.input,
+            artifacts: collectArtifactArtifacts(result),
+            result,
+        }), null, 2));
+        return;
+    }
+    logSuccess(params.successText);
+    console.log(JSON.stringify(result, null, 2));
+}
+export async function runArtifactGet(options = {}) {
+    try {
+        const apiState = await requireApiState(options);
+        if (!apiState)
+            return;
+        const resolvedContext = await resolveArtifactContext(options, apiState);
+        const id = ensureArtifactId(options.id);
+        const input = { id };
+        const payload = await invokeHostedToolWithApiState(apiState, {
+            ...buildGatewayOptions(options, resolvedContext),
+            tenantId: options.tenantId,
+            locale: options.locale,
+            fallbackLocale: options.fallbackLocale,
+            timeoutMs: options.timeoutMs,
+            apiBaseUrl: options.apiBaseUrl,
+            accessToken: options.accessToken,
+            refreshToken: options.refreshToken,
+            toolId: 'agentspace.artifact.get-artifact',
+            input,
+        });
+        const result = unwrapHostedToolResult(payload);
+        const outputResult = options.summary ? summarizeArtifactGetResult(result) : result;
+        if (options.json) {
+            console.log(JSON.stringify(buildEnvelope({
+                command: 'artifact.get',
+                toolId: 'agentspace.artifact.get-artifact',
+                resolvedContext: buildResolvedContextRecord(resolvedContext),
+                input,
+                artifacts: collectArtifactArtifacts(result),
+                result: outputResult,
+            }), null, 2));
+            return;
+        }
+        logSuccess('Artifact loaded.');
+        console.log(JSON.stringify(outputResult, null, 2));
+    }
+    catch (error) {
+        logError(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}
+export async function runArtifactCreate(options = {}) {
+    try {
+        const apiState = await requireApiState(options);
+        if (!apiState)
+            return;
+        const resolvedContext = await resolveArtifactContext(options, apiState);
+        const seed = parseJsonSeed(options.input);
+        const artifactType = resolveStringField(options.artifactType, seed, 'artifactType');
+        const storagePath = resolveStringField(options.storagePath, seed, 'storagePath');
+        if (!artifactType)
+            throw new Error('Artifact create requires --artifact-type or input.artifactType.');
+        if (!storagePath)
+            throw new Error('Artifact create requires --storage-path or input.storagePath.');
+        const input = {
+            data: compactPayload({
+                scopeId: requireScopeId(resolvedContext, seed),
+                artifactType,
+                storagePath,
+                label: resolveStringField(options.label, seed, 'label'),
+                mimeType: resolveStringField(options.mimeType, seed, 'mimeType'),
+                sizeBytes: resolveIntegerField(options.sizeBytes, seed, 'sizeBytes', '--size-bytes'),
+                hash: resolveStringField(options.hash, seed, 'hash'),
+                meta: resolveUnknownField(options.meta, seed, 'meta', '--meta'),
+            }),
+        };
+        await invokeArtifactTool(apiState, options, resolvedContext, {
+            command: 'artifact.create',
+            toolId: 'agentspace.artifact.store-artifact',
+            input,
+            successText: 'Artifact created.',
+        });
+    }
+    catch (error) {
+        logError(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}
+export async function runArtifactDelete(options = {}) {
+    try {
+        ensureDestructiveWrite(options, 'This command deletes hosted artifacts.');
+        const apiState = await requireApiState(options);
+        if (!apiState)
+            return;
+        const resolvedContext = await resolveArtifactContext(options, apiState);
+        const id = ensureArtifactId(options.id);
+        const input = { id };
+        await invokeArtifactTool(apiState, options, resolvedContext, {
+            command: 'artifact.delete',
+            toolId: 'agentspace.artifact.remove-artifact',
+            input,
+            successText: 'Artifact deleted.',
+        });
+    }
+    catch (error) {
+        logError(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}
+export async function runArtifactLink(options = {}) {
+    try {
+        const apiState = await requireApiState(options);
+        if (!apiState)
+            return;
+        const resolvedContext = await resolveArtifactContext(options, apiState);
+        const seed = parseJsonSeed(options.input);
+        const artifactId = resolveStringField(options.artifactId, seed, 'artifactId');
+        const refType = resolveStringField(options.refType, seed, 'refType');
+        const refId = resolveStringField(options.refId, seed, 'refId');
+        if (!artifactId)
+            throw new Error('Artifact link requires --artifact-id or input.artifactId.');
+        if (!refType)
+            throw new Error('Artifact link requires --ref-type or input.refType.');
+        if (!refId)
+            throw new Error('Artifact link requires --ref-id or input.refId.');
+        const input = {
+            data: compactPayload({
+                projectId: requireProjectId({
+                    ...resolvedContext,
+                    projectId: normalizeNonEmpty(options.projectId) ?? resolvedContext.projectId,
+                }, seed),
+                artifactId,
+                refType,
+                refId,
+                createdBy: resolveStringField(undefined, seed, 'createdBy'),
+            }),
+        };
+        await invokeArtifactTool(apiState, options, resolvedContext, {
+            command: 'artifact.link',
+            toolId: 'agentspace.artifact.link-artifact',
+            input,
+            successText: 'Artifact linked.',
+        });
+    }
+    catch (error) {
+        logError(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}
+export async function runArtifactRefList(options = {}) {
+    try {
+        const apiState = await requireApiState(options);
+        if (!apiState)
+            return;
+        const resolvedContext = await resolveArtifactContext(options, apiState);
+        const refType = ensureArtifactId(options.refType, '--ref-type');
+        const refId = ensureArtifactId(options.refId, '--ref-id');
+        const input = compactPayload({
+            refType,
+            refId,
+            scopeId: normalizeNonEmpty(options.scopeId) ?? normalizeNonEmpty(resolvedContext.scopeId),
+            scopeResolution: options.scopeResolution,
+        });
+        const payload = await invokeHostedToolWithApiState(apiState, {
+            ...buildGatewayOptions(options, resolvedContext),
+            tenantId: options.tenantId,
+            locale: options.locale,
+            fallbackLocale: options.fallbackLocale,
+            timeoutMs: options.timeoutMs,
+            apiBaseUrl: options.apiBaseUrl,
+            accessToken: options.accessToken,
+            refreshToken: options.refreshToken,
+            toolId: 'agentspace.artifact.list-artifacts-by-ref',
+            input,
+        });
+        const result = unwrapHostedToolResult(payload);
+        const outputResult = options.summary ? summarizeArtifactRefListResult(result) : result;
+        if (options.json) {
+            console.log(JSON.stringify(buildEnvelope({
+                command: 'artifact.ref.list',
+                toolId: 'agentspace.artifact.list-artifacts-by-ref',
+                resolvedContext: buildResolvedContextRecord(resolvedContext),
+                input,
+                result: outputResult,
+            }), null, 2));
+            return;
+        }
+        logSuccess('Artifact ref list loaded.');
+        console.log(JSON.stringify(outputResult, null, 2));
+    }
+    catch (error) {
+        logError(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}
+function applyArtifactContextOptions(cmd, params = {}) {
+    applyCommonOptions(cmd);
+    cmd.option('--project-id <id>', 'Project id used to resolve repo-bound artifact ownership or linking');
+    cmd.option('--project-name <name>', 'Project name used to resolve repo-bound artifact ownership');
+    cmd.option('--scope-id <id>', 'Explicit scope id override for artifact ownership');
+    if (params.withScopeResolution) {
+        cmd.option('--scope-resolution <mode>', 'Scope resolution policy: explicit or cascade');
+    }
+    return cmd;
+}
+function applyWriteGuards(cmd, params = {}) {
+    cmd.option('--preview', 'Return a validated preflight summary without executing the tool');
+    cmd.option('--apply', 'Execute the hosted write operation');
+    if (params.destructive) {
+        cmd.option('--confirm', 'Required with --apply for destructive deletes');
+    }
+    cmd.option('--idempotency-key <key>', 'Optional idempotency key for hosted writes');
+    return cmd;
+}
+function applyJsonSeedOption(cmd) {
+    cmd.option('--input <jsonOrFile>', 'Optional JSON object seed or @file.json');
+    return cmd;
+}
+export function makeArtifactCommand() {
+    const cmd = new Command('artifact').description('Agentspace artifact sugar commands over the hosted AOPS gateway');
+    applyArtifactContextOptions(cmd.command('get')
+        .description('Get an artifact by id')
+        .requiredOption('--id <id>', 'Artifact id')
+        .option('--summary', 'Omit raw artifact meta and print metadata size summary')).action(async (options) => {
+        await runArtifactGet(options);
+    });
+    applyWriteGuards(applyJsonSeedOption(applyArtifactContextOptions(cmd.command('create')
+        .description('Create a scope-owned artifact shell')
+        .requiredOption('--artifact-type <type>', 'Artifact type')
+        .requiredOption('--storage-path <path>', 'Artifact storage path')
+        .option('--label <text>', 'Artifact label')
+        .option('--mime-type <text>', 'Artifact mime type')
+        .option('--size-bytes <n>', 'Artifact byte size')
+        .option('--hash <text>', 'Artifact hash')
+        .option('--meta <jsonOrFile>', 'JSON meta object/array/value or @file.json')))).action(async (options) => {
+        await runArtifactCreate(options);
+    });
+    applyWriteGuards(applyJsonSeedOption(applyArtifactContextOptions(cmd.command('link')
+        .description('Link an artifact to a project-scoped ref')
+        .requiredOption('--artifact-id <id>', 'Artifact id')
+        .requiredOption('--ref-type <type>', 'Ref type')
+        .requiredOption('--ref-id <id>', 'Ref id')))).action(async (options) => {
+        await runArtifactLink(options);
+    });
+    const ref = cmd.command('ref').description('Artifact ref lookup commands');
+    applyArtifactContextOptions(ref.command('list')
+        .description('List artifacts linked to a ref')
+        .requiredOption('--ref-type <type>', 'Ref type')
+        .requiredOption('--ref-id <id>', 'Ref id')
+        .option('--summary', 'Print compact artifact records and omit raw meta payloads'), { withScopeResolution: true }).action(async (options) => {
+        await runArtifactRefList(options);
+    });
+    applyWriteGuards(applyArtifactContextOptions(cmd.command('delete')
+        .description('Delete an artifact')
+        .requiredOption('--id <id>', 'Artifact id')), { destructive: true }).action(async (options) => {
+        await runArtifactDelete(options);
+    });
+    cmd.addHelpText('after', buildOperatorCookbook({
+        examples: [
+            'aops-cli artifact create --artifact-type file --storage-path s3://bucket/report.json --apply --json',
+            'aops-cli artifact link --artifact-id <artifact-id> --ref-type resource --ref-id <resource-id> --apply --json',
+            'aops-cli artifact ref list --ref-type resource --ref-id <resource-id> --summary --json',
+            'aops-cli artifact get --id <artifact-id> --summary --json',
+            'aops-cli artifact delete --id <artifact-id> --apply --confirm --json',
+        ],
+        guide: GUIDE_PATHS.agentspace,
+        notes: ['Artifact get/ref list are curated read surfaces and do not require --apply; use --summary unless you need full meta.'],
+    }));
+    return cmd;
+}