@yargote/artifacts-cli 0.0.0-stage → 0.1.0-beta.10

package/src/credentials.js

@@ -0,0 +1,116 @@
+import { constants } from 'node:fs';
+import { chmod, lstat, mkdir, open } from 'node:fs/promises';
+import { join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { setTimeout as delay } from 'node:timers/promises';
+import { z } from 'zod';
+import { canonicalResource } from '@yargote/artifacts-contracts/http';
+const registrationSchema = z.strictObject({ issuer: z.string(), clientId: z.string().min(1) });
+const tokensSchema = z.strictObject({ accessToken: z.string().min(1), refreshToken: z.string().min(1).optional(), expiresAt: z.number().finite() });
+const profileSchema = z.strictObject({
+    epoch: z.number().int().nonnegative(),
+    registration: registrationSchema.nullable(),
+    tokens: tokensSchema.nullable(),
+    refreshAttempt: z.string().nullable(),
+});
+async function privateFile(path) {
+    const file = await open(path, constants.O_CREAT | constants.O_RDWR | constants.O_NOFOLLOW, 0o600);
+    try {
+        const stat = await file.stat();
+        if (!stat.isFile() || stat.nlink !== 1 || (process.getuid && stat.uid !== process.getuid()))
+            throw new Error('Credential storage must be a private file owned by the current user');
+        await file.chmod(0o600);
+    }
+    finally {
+        await file.close();
+    }
+}
+export class CredentialStore {
+    data;
+    lock;
+    constructor(data, lock) {
+        this.data = data;
+        this.lock = lock;
+    }
+    static async open(stateDir) {
+        await mkdir(stateDir, { recursive: true, mode: 0o700 });
+        const directory = await lstat(stateDir);
+        if (!directory.isDirectory() || directory.isSymbolicLink() || (process.getuid && directory.uid !== process.getuid()))
+            throw new Error('Credential storage must be a private directory owned by the current user');
+        await chmod(stateDir, 0o700);
+        const dataPath = join(stateDir, 'credentials.sqlite');
+        const lockPath = join(stateDir, 'credentials-lock.sqlite');
+        await privateFile(dataPath);
+        await privateFile(lockPath);
+        const lock = new DatabaseSync(lockPath);
+        let data;
+        try {
+            data = new DatabaseSync(dataPath);
+            lock.exec('PRAGMA busy_timeout = 0;');
+            const store = new CredentialStore(data, lock);
+            await store.exclusive(() => {
+                data.exec('PRAGMA busy_timeout = 0; PRAGMA synchronous = FULL; PRAGMA secure_delete = ON;');
+                data.exec('CREATE TABLE IF NOT EXISTS profiles (resource TEXT PRIMARY KEY, profile TEXT NOT NULL) STRICT');
+                data.exec('CREATE TABLE IF NOT EXISTS selected_resource (id INTEGER PRIMARY KEY CHECK (id = 1), resource TEXT NOT NULL) STRICT');
+            });
+            return store;
+        }
+        catch (error) {
+            data?.close();
+            lock.close();
+            throw error;
+        }
+    }
+    async exclusive(work) {
+        const deadline = Date.now() + 45_000;
+        for (;;) {
+            try {
+                this.lock.exec('BEGIN IMMEDIATE');
+                break;
+            }
+            catch (error) {
+                if (!(error instanceof Error) || !('errcode' in error) || (error.errcode !== 5 && error.errcode !== 6))
+                    throw error;
+                if (Date.now() >= deadline)
+                    throw new Error('Credential storage is busy. Try the command again');
+                await delay(25);
+            }
+        }
+        try {
+            return await work();
+        }
+        finally {
+            this.lock.exec('ROLLBACK');
+        }
+    }
+    read(resource) {
+        const row = this.data.prepare('SELECT profile FROM profiles WHERE resource = ?').get(resource);
+        if (!row)
+            return { epoch: 0, registration: null, tokens: null, refreshAttempt: null };
+        return profileSchema.parse(JSON.parse(String(row.profile)));
+    }
+    write(resource, profile) {
+        this.data.prepare('INSERT INTO profiles(resource, profile) VALUES (?, ?) ON CONFLICT(resource) DO UPDATE SET profile = excluded.profile').run(resource, JSON.stringify(profileSchema.parse(profile)));
+    }
+    readSelectedResource() {
+        const row = this.data.prepare('SELECT resource FROM selected_resource WHERE id = 1').get();
+        return row ? canonicalResource(String(row.resource)) : undefined;
+    }
+    commitLogin(resource, epoch, tokens) {
+        canonicalResource(resource);
+        this.data.exec('BEGIN IMMEDIATE');
+        try {
+            const profile = this.read(resource);
+            if (profile.epoch !== epoch)
+                throw new Error('Login was superseded by another login or logout');
+            this.write(resource, { ...profile, tokens, refreshAttempt: null });
+            this.data.prepare('INSERT INTO selected_resource(id, resource) VALUES (1, ?) ON CONFLICT(id) DO UPDATE SET resource = excluded.resource').run(resource);
+            this.data.exec('COMMIT');
+        }
+        catch (error) {
+            this.data.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    close() { this.data.close(); this.lock.close(); }
+}

package/src/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/src/index.js

@@ -0,0 +1,343 @@
+#!/usr/bin/env node
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { open, readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { z } from 'zod';
+import { createSchema, listSharesSchema, moveSchema, publishSchema, shareSchema, unshareSchema, updateSchema } from '@yargote/artifacts-contracts';
+import { canonicalResource } from '@yargote/artifacts-contracts/http';
+import { createArtifactHttpClient, HttpError, prepareArtifactEdit } from '@yargote/artifacts-client';
+import { accessToken, login, logout } from "./auth.js";
+import { CredentialStore } from "./credentials.js";
+import { loadOperation, retainOperation, submitOperation } from "./operations.js";
+import { runSkillsCommand } from "./skills.js";
+const help = `Usage: artifacts COMMAND [OPTIONS]
+
+Global options:
+  --server RESOURCE       Exact REST OAuth resource, or ARTIFACTS_SERVER
+                         Defaults to the last successful login
+  --state-dir DIR         Private local state, or ARTIFACTS_STATE_DIR
+                         Default: ~/.local/state/artifacts
+  --help                 Print this reference
+  --version              Print the installed package version
+
+Commands:
+  skills [list]
+  skills get NAME [--full]
+  skills get --all [--full]
+  skills path [NAME]
+  skills install [NAME] [--agent claude] [--global] [--force]
+  login [--no-browser]
+  logout
+  whoami
+  create --snapshot FILE [--project NAME] [--slug SLUG] [--request-id ID]
+         [--response full|compact]
+  create --command FILE
+  list [--limit N] [--cursor CURSOR] [--project NAME]
+  projects
+  search QUERY [--project NAME] [--limit N] [--cursor CURSOR]
+  read ID [--revision REV] [--response full|compact] [--out FILE [--quiet]]
+  read --slug SLUG [--project NAME] [--revision REV] [--response full|compact]
+         [--out FILE [--quiet]]
+  update ID --snapshot FILE --expected-revision REV [--request-id ID]
+         [--response full|compact]
+  update [ID] --command FILE
+  edit ID --changes FILE [--request-id ID]
+  history ID [--limit N] [--before-sequence N] [--summary]
+  publish ID --revision REV --expected-version N [--request-id ID]
+  publish [ID] --command FILE
+  export ID --revision REV --out FILE
+  move ID [--project NAME | --no-project] [--slug SLUG | --no-slug]
+         [--request-id ID]
+  share ID --email EMAIL [--notify] [--request-id ID]
+  shares ID
+  unshare ID SHARE_ID [--request-id ID]
+  retry REQUEST_ID
+
+Mutation command files contain the complete create, update, or publish JSON.
+Mutation request IDs default to a random UUID. Commands are retained before
+submission. Retry sends the exact retained command for the same server and owner.
+Projects group artifacts by name without regard to letter case. A project
+exists while it contains an artifact. Move changes the project or the slug of
+an artifact without creating a revision. It needs at least one of its four
+options. --no-project removes the artifact from its project, and --no-slug
+clears its slug. An option left out keeps that value, so a move to another
+project keeps the slug.
+A slug such as concepts/rag names an artifact within its project, or within
+the unfiled artifacts without --project. Read --slug finds it without its ID.
+Create or move fails with slug_conflict when the project already uses the slug.
+Search finds owned Markdown and text artifacts whose title, description, or
+content contains every term of QUERY, ignoring letter case and accents. Quote a
+QUERY with spaces. Results are ordered by relevance with a **bold** snippet.
+Read --out saves the returned artifact JSON. Export --out saves the ZIP.
+Read --quiet requires --out and suppresses successful JSON stdout.
+Output files are created exclusively and never overwrite an existing path.
+JSON results go to stdout. Diagnostics and recovery guidance go to stderr.
+Login accepts an MCP URL when its metadata advertises artifacts_rest_resource.
+Split MCP and REST resources require this relation. Login remembers the verified
+REST URL for later commands. --server takes precedence over ARTIFACTS_SERVER,
+which takes precedence over the saved URL. Ordinary overrides do not replace
+the saved URL. Logout keeps it for a later login.
+Login checks <resource>/v1/identity before browser
+authorization. Legacy /mcp
+resources work when their REST API is at /mcp/v1. If the check fails, confirm
+the configured REST URL with your service administrator.
+Login errors report the phase, method, endpoint, and HTTP status when received.
+Network failures have no HTTP status. Login verifies identity again after OAuth.
+ARTIFACTS_ACCESS_TOKEN supplies a token for automation without local login.
+Skills commands work offline without a server, login, or private state.
+They print plain text. Global server and state options are accepted and ignored.
+Skills install defaults to artifacts-cli under .agents/skills in the current
+directory. --agent claude uses .claude/skills. --global uses your home directory.
+The installed discovery file loads instructions through artifacts skills get.
+Identical files stay unchanged. Differing files require --force.
+`;
+class UsageError extends Error {
+}
+const commandOptions = {
+    login: ['no-browser'], logout: [], whoami: [],
+    create: ['snapshot', 'project', 'slug', 'request-id', 'response', 'command'],
+    list: ['limit', 'cursor', 'project'], projects: [], search: ['project', 'limit', 'cursor'], read: ['slug', 'project', 'revision', 'response', 'out', 'quiet'],
+    update: ['snapshot', 'expected-revision', 'request-id', 'response', 'command'],
+    edit: ['changes', 'request-id'], history: ['limit', 'before-sequence', 'summary'],
+    publish: ['revision', 'expected-version', 'request-id', 'command'],
+    share: ['email', 'notify', 'request-id'], shares: [], unshare: ['request-id'],
+    export: ['revision', 'out'], move: ['project', 'no-project', 'slug', 'no-slug', 'request-id'], retry: [],
+    skills: ['full', 'all', 'agent', 'global', 'force'],
+};
+async function jsonFile(path) {
+    const file = await open(path, constants.O_RDONLY);
+    try {
+        const stat = await file.stat();
+        if (!stat.isFile() || stat.size > 8 * 1024 * 1024)
+            throw new UsageError('JSON input must be a regular file no larger than 8 MiB');
+        return JSON.parse(await file.readFile('utf8'));
+    }
+    finally {
+        await file.close();
+    }
+}
+async function writeOutput(path, bytes) {
+    const file = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try {
+        await file.writeFile(bytes);
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+}
+async function main() {
+    const { values, positionals, tokens } = parseArgs({
+        allowPositionals: true, tokens: true,
+        options: {
+            server: { type: 'string' }, 'state-dir': { type: 'string' }, help: { type: 'boolean' }, version: { type: 'boolean' },
+            'no-browser': { type: 'boolean' }, command: { type: 'string' }, snapshot: { type: 'string' },
+            changes: { type: 'string' }, 'request-id': { type: 'string' }, response: { type: 'string' },
+            revision: { type: 'string' }, 'expected-revision': { type: 'string' }, 'expected-version': { type: 'string' },
+            limit: { type: 'string' }, cursor: { type: 'string' }, 'before-sequence': { type: 'string' },
+            summary: { type: 'boolean' }, out: { type: 'string' }, quiet: { type: 'boolean' },
+            full: { type: 'boolean' }, all: { type: 'boolean' }, agent: { type: 'string' },
+            global: { type: 'boolean' }, force: { type: 'boolean' },
+            project: { type: 'string' }, 'no-project': { type: 'boolean' }, slug: { type: 'string' }, 'no-slug': { type: 'boolean' }, email: { type: 'string' }, notify: { type: 'boolean' },
+        },
+    });
+    const seen = new Set();
+    for (const token of tokens) {
+        if (token.kind !== 'option')
+            continue;
+        if (seen.has(token.name))
+            throw new UsageError(`Option --${token.name} cannot be repeated`);
+        seen.add(token.name);
+    }
+    if (values.version) {
+        const manifest = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+        process.stdout.write(`${manifest.version}\n`);
+        return;
+    }
+    if (values.help) {
+        process.stdout.write(help);
+        return;
+    }
+    const [command, ...arguments_] = positionals;
+    if (!command || !Object.hasOwn(commandOptions, command))
+        throw new UsageError('Specify a command. Use artifacts --help for the reference.');
+    for (const option of seen)
+        if (!['server', 'state-dir', 'help', ...commandOptions[command]].includes(option))
+            throw new UsageError(`Option --${option} is not supported by ${command}`);
+    if (command === 'skills')
+        return runSkillsCommand(arguments_, values, seen);
+    const stateDir = resolve(values['state-dir'] ?? process.env.ARTIFACTS_STATE_DIR ?? join(homedir(), '.local', 'state', 'artifacts'));
+    let resourceValue = values.server ?? process.env.ARTIFACTS_SERVER;
+    if (resourceValue === undefined) {
+        const store = await CredentialStore.open(stateDir);
+        try {
+            resourceValue = await store.exclusive(() => store.readSelectedResource());
+        }
+        finally {
+            store.close();
+        }
+    }
+    if (resourceValue === undefined)
+        throw new UsageError('No server is saved. Run artifacts login --server RESOURCE or set ARTIFACTS_SERVER.');
+    const resource = canonicalResource(resourceValue);
+    function argument(required = true) {
+        if (arguments_.length > 1 || (required && arguments_.length !== 1))
+            throw new UsageError(`${command} requires ${required ? 'one' : 'zero or one'} positional argument`);
+        return arguments_[0];
+    }
+    function none() {
+        if (arguments_.length)
+            throw new UsageError(`${command} does not accept positional arguments`);
+    }
+    function required(name) {
+        const value = values[name];
+        if (typeof value !== 'string' || !value)
+            throw new UsageError(`Specify --${name}`);
+        return value;
+    }
+    function integer(name) {
+        const value = values[name];
+        if (value === undefined)
+            return undefined;
+        if (typeof value !== 'string' || !/^(0|[1-9]\d*)$/.test(value) || !Number.isSafeInteger(Number(value)))
+            throw new UsageError(`--${name} requires a nonnegative safe integer`);
+        return Number(value);
+    }
+    function cleared(name, value, clear) {
+        if (value !== undefined && clear)
+            throw new UsageError(`Specify at most one of --${name} or --no-${name}`);
+        return clear ? null : value;
+    }
+    const response = values.response;
+    if (response !== undefined && response !== 'full' && response !== 'compact')
+        throw new UsageError('--response requires full or compact');
+    const quiet = values.quiet ?? false;
+    if (quiet)
+        required('out');
+    let commandToken;
+    const client = createArtifactHttpClient({ resource, accessToken: () => commandToken ??= accessToken({ resource, stateDir }) });
+    async function mutate(mutation) {
+        const owner = await client.identity();
+        const operation = await retainOperation(stateDir, resource, owner.userId, mutation);
+        process.stderr.write(`Retained operation ${operation.command.requestId}. Recover with artifacts retry ${operation.command.requestId} using the same server and state directory.\n`);
+        return submitOperation(client, operation);
+    }
+    async function commandFile(kind) {
+        const extra = [...seen].filter((option) => !['server', 'state-dir', 'command'].includes(option));
+        if (extra.length)
+            throw new UsageError('--command cannot be combined with mutation options');
+        const value = await jsonFile(required('command'));
+        if (kind === 'create') {
+            none();
+            return { kind, command: createSchema.parse(value) };
+        }
+        const mutation = kind === 'update' ? { kind, command: updateSchema.parse(value) } : { kind, command: publishSchema.parse(value) };
+        const id = argument(false);
+        if (id !== undefined && id !== mutation.command.artifactId)
+            throw new UsageError('The positional artifact ID must match the command file');
+        return mutation;
+    }
+    switch (command) {
+        case 'login':
+            none();
+            {
+                const result = await login({ resource, stateDir, noBrowser: values['no-browser'] ?? false, onAuthorizationUrl: (url) => { process.stderr.write(`Authorize this login in your browser:\n${url}\n`); } });
+                if (result.resource !== resource)
+                    process.stderr.write(`REST resource: ${result.resource}\nThis verified REST URL is saved for subsequent commands.\n`);
+                return result.identity;
+            }
+        case 'logout':
+            none();
+            return logout({ resource, stateDir });
+        case 'whoami':
+            none();
+            return client.identity();
+        case 'create': {
+            if (values.command)
+                return mutate(await commandFile('create'));
+            none();
+            return mutate({ kind: 'create', command: createSchema.parse({ requestId: values['request-id'] ?? randomUUID(), snapshot: await jsonFile(required('snapshot')), ...(values.project === undefined ? {} : { project: values.project }), ...(values.slug === undefined ? {} : { slug: values.slug }), ...(response === undefined ? {} : { response }) }) });
+        }
+        case 'list':
+            none();
+            return client.list({ ...(values.limit === undefined ? {} : { limit: integer('limit') }), ...(values.cursor === undefined ? {} : { cursor: values.cursor }), ...(values.project === undefined ? {} : { project: values.project }) });
+        case 'projects':
+            none();
+            return client.projects();
+        case 'search': return client.search({ query: argument(), ...(values.project === undefined ? {} : { project: values.project }), ...(values.limit === undefined ? {} : { limit: integer('limit') }), ...(values.cursor === undefined ? {} : { cursor: values.cursor }) });
+        case 'read': {
+            if (values.slug === undefined && values.project !== undefined)
+                throw new UsageError('read --project requires --slug');
+            if ((values.slug === undefined) !== (arguments_.length === 1) || arguments_.length > 1)
+                throw new UsageError('read requires exactly one of an artifact ID or --slug SLUG');
+            const target = values.slug === undefined ? { artifactId: arguments_[0] } : { slug: values.slug, ...(values.project === undefined ? {} : { project: values.project }) };
+            const result = await client.read({ ...target, ...(values.revision === undefined ? {} : { revisionId: values.revision }), ...(response === undefined ? {} : { response }) });
+            if (values.out)
+                await writeOutput(values.out, `${JSON.stringify(result, null, 2)}\n`);
+            return quiet ? undefined : result;
+        }
+        case 'update': {
+            if (values.command)
+                return mutate(await commandFile('update'));
+            return mutate({ kind: 'update', command: updateSchema.parse({ artifactId: argument(), requestId: values['request-id'] ?? randomUUID(), expectedRevisionId: required('expected-revision'), snapshot: await jsonFile(required('snapshot')), ...(response === undefined ? {} : { response }) }) });
+        }
+        case 'edit': {
+            const artifactId = argument();
+            const changes = await jsonFile(required('changes'));
+            const input = await prepareArtifactEdit(client, { artifactId, requestId: values['request-id'] ?? randomUUID(), changes: changes });
+            return mutate({ kind: 'update', command: updateSchema.parse(input) });
+        }
+        case 'history': return client.history({ artifactId: argument(), ...(values.limit === undefined ? {} : { limit: integer('limit') }), ...(values['before-sequence'] === undefined ? {} : { beforeSequence: integer('before-sequence') }), ...(values.summary ? { response: 'summary' } : {}) });
+        case 'publish': {
+            if (values.command)
+                return mutate(await commandFile('publish'));
+            required('expected-version');
+            return mutate({ kind: 'publish', command: publishSchema.parse({ artifactId: argument(), requestId: values['request-id'] ?? randomUUID(), revisionId: required('revision'), expectedPublicationVersion: integer('expected-version') }) });
+        }
+        case 'export': {
+            const output = required('out');
+            const archive = await client.export({ artifactId: argument(), revisionId: required('revision') });
+            await writeOutput(output, archive.bytes);
+            return { filename: archive.filename, path: resolve(output), mediaType: archive.mediaType, sha256: archive.sha256, bytes: archive.bytes.byteLength };
+        }
+        case 'move': {
+            const artifactId = argument();
+            const project = cleared('project', values.project, values['no-project']);
+            const slug = cleared('slug', values.slug, values['no-slug']);
+            if (project === undefined && slug === undefined)
+                throw new UsageError('move requires --project NAME, --no-project, --slug SLUG, or --no-slug');
+            return mutate({ kind: 'move', command: moveSchema.parse({ artifactId, requestId: values['request-id'] ?? randomUUID(), ...(project === undefined ? {} : { project }), ...(slug === undefined ? {} : { slug }) }) });
+        }
+        case 'share': return mutate({ kind: 'share', command: shareSchema.parse({ artifactId: argument(), requestId: values['request-id'] ?? randomUUID(), email: required('email'), ...(values.notify === undefined ? {} : { notify: values.notify }) }) });
+        case 'shares': return client.listShares(listSharesSchema.parse({ artifactId: argument() }));
+        case 'unshare': {
+            if (arguments_.length !== 2)
+                throw new UsageError('unshare requires two positional arguments');
+            return mutate({ kind: 'unshare', command: unshareSchema.parse({ artifactId: arguments_[0], shareId: arguments_[1], requestId: values['request-id'] ?? randomUUID() }) });
+        }
+        case 'retry': {
+            const requestId = argument();
+            const owner = await client.identity();
+            const operation = await loadOperation(stateDir, requestId, resource, owner.userId);
+            process.stderr.write(`Replaying retained ${operation.kind} operation ${requestId}. Replay confirms the original operation and does not establish current state.\n`);
+            return submitOperation(client, operation);
+        }
+    }
+}
+try {
+    const result = await main();
+    if (result !== undefined)
+        process.stdout.write(`${JSON.stringify(result)}\n`);
+}
+catch (error) {
+    const body = error instanceof HttpError
+        ? { code: error.code, message: error.message, status: error.status, details: error.details }
+        : error instanceof z.ZodError
+            ? { code: 'invalid_input', message: 'Input does not match the artifact command schema', details: { issues: error.issues } }
+            : { code: error instanceof UsageError || error instanceof TypeError || error instanceof SyntaxError ? 'invalid_arguments' : 'local_error', message: error instanceof Error ? error.message : 'Command failed', details: {} };
+    process.stderr.write(`${JSON.stringify({ error: body })}\n`);
+    process.exitCode = 1;
+}

package/src/operations.d.ts

@@ -0,0 +1,174 @@
+import { z } from 'zod';
+import { createSchema, moveSchema, publishSchema, shareSchema, unshareSchema, updateSchema } from '@yargote/artifacts-contracts';
+import type { ArtifactHttpClient } from '@yargote/artifacts-client';
+export declare const operationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"create">;
+    command: z.ZodObject<{
+        requestId: z.ZodString;
+        snapshot: z.ZodObject<{
+            metadata: z.ZodObject<{
+                title: z.ZodString;
+                description: z.ZodString;
+                custom: z.ZodOptional<z.ZodJSONSchema>;
+            }, z.core.$strict>;
+            content: z.ZodObject<{
+                kind: z.ZodEnum<{
+                    text: "text";
+                    html: "html";
+                    markdown: "markdown";
+                    design: "design";
+                }>;
+                text: z.ZodString;
+            }, z.core.$strict>;
+            files: z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+                mediaType: z.ZodString;
+                encoding: z.ZodEnum<{
+                    utf8: "utf8";
+                    base64: "base64";
+                }>;
+                data: z.ZodString;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+        project: z.ZodOptional<z.ZodString>;
+        slug: z.ZodOptional<z.ZodString>;
+        response: z.ZodOptional<z.ZodEnum<{
+            full: "full";
+            compact: "compact";
+        }>>;
+    }, z.core.$strict>;
+    version: z.ZodLiteral<1>;
+    resource: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    ownerId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"update">;
+    command: z.ZodObject<{
+        requestId: z.ZodString;
+        artifactId: z.ZodString;
+        expectedRevisionId: z.ZodString;
+        snapshot: z.ZodObject<{
+            metadata: z.ZodObject<{
+                title: z.ZodString;
+                description: z.ZodString;
+                custom: z.ZodOptional<z.ZodJSONSchema>;
+            }, z.core.$strict>;
+            content: z.ZodObject<{
+                kind: z.ZodEnum<{
+                    text: "text";
+                    html: "html";
+                    markdown: "markdown";
+                    design: "design";
+                }>;
+                text: z.ZodString;
+            }, z.core.$strict>;
+            files: z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+                mediaType: z.ZodString;
+                encoding: z.ZodEnum<{
+                    utf8: "utf8";
+                    base64: "base64";
+                }>;
+                data: z.ZodString;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+        response: z.ZodOptional<z.ZodEnum<{
+            full: "full";
+            compact: "compact";
+        }>>;
+    }, z.core.$strict>;
+    version: z.ZodLiteral<1>;
+    resource: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    ownerId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"publish">;
+    command: z.ZodObject<{
+        requestId: z.ZodString;
+        artifactId: z.ZodString;
+        revisionId: z.ZodString;
+        expectedPublicationVersion: z.ZodNumber;
+    }, z.core.$strict>;
+    version: z.ZodLiteral<1>;
+    resource: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    ownerId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"move">;
+    command: z.ZodObject<{
+        requestId: z.ZodString;
+        artifactId: z.ZodString;
+        project: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        slug: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>;
+    version: z.ZodLiteral<1>;
+    resource: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    ownerId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"share">;
+    command: z.ZodObject<{
+        requestId: z.ZodString;
+        artifactId: z.ZodString;
+        email: z.ZodPipe<z.ZodString, z.ZodEmail>;
+        notify: z.ZodOptional<z.ZodBoolean>;
+        requireNew: z.ZodOptional<z.ZodLiteral<true>>;
+    }, z.core.$strict>;
+    version: z.ZodLiteral<1>;
+    resource: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    ownerId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"unshare">;
+    command: z.ZodObject<{
+        requestId: z.ZodString;
+        artifactId: z.ZodString;
+        shareId: z.ZodString;
+    }, z.core.$strict>;
+    version: z.ZodLiteral<1>;
+    resource: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    ownerId: z.ZodString;
+}, z.core.$strict>], "kind">;
+export type PreparedOperation = z.infer<typeof operationSchema>;
+export type Mutation = {
+    kind: 'create';
+    command: z.input<typeof createSchema>;
+} | {
+    kind: 'update';
+    command: z.input<typeof updateSchema>;
+} | {
+    kind: 'publish';
+    command: z.input<typeof publishSchema>;
+} | {
+    kind: 'move';
+    command: z.input<typeof moveSchema>;
+} | {
+    kind: 'share';
+    command: z.input<typeof shareSchema>;
+} | {
+    kind: 'unshare';
+    command: z.input<typeof unshareSchema>;
+};
+export declare function operationPath(stateDir: string, resource: string, requestId: string): string;
+export declare function retainOperation(stateDir: string, resource: string, ownerId: string, mutation: Mutation): Promise<PreparedOperation>;
+export declare function loadOperation(stateDir: string, requestId: string, resource: string, ownerId: string): Promise<PreparedOperation>;
+export declare function submitOperation(client: ArtifactHttpClient, operation: PreparedOperation): Promise<void> | Promise<{
+    shareId: string;
+    artifactId: string;
+    kind: "email";
+    value: string;
+    createdAt: string;
+    notification?: {
+        status: "requested";
+    } | {
+        status: "skipped";
+        reason: "disabled";
+    } | {
+        status: "skipped";
+        reason: "rate_limited";
+        retryAt: string;
+    } | undefined;
+}> | Promise<{
+    artifactId: string;
+    project: string | null;
+}> | Promise<{
+    revisionId: string;
+    version: number;
+    url: string;
+    artifactId: string;
+}>;