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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yerson Argote
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,179 @@
-# Temporary Holding Version
+# Artifacts CLI reference
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The `artifacts` Node CLI reads and writes retained artifacts through REST. It prints JSON results to stdout and diagnostics to stderr. Node 24 or later is required. Its private credential database uses Node's experimental built-in SQLite API.
+
+The `@yargote/artifacts-cli` package exposes the `artifacts` binary as compiled ESM JavaScript. Its client and contracts dependencies install automatically. Repository development uses `pnpm artifacts` with the same command syntax.
+
+## Install the beta
+
+Use Node 24 or later. The beta targets macOS and Linux. Windows has not been verified.
+
+Choose one persistent installation:
+
+```sh
+npm install --global @yargote/artifacts-cli@0.1.0-beta.1
+# Or, with pnpm and an existing global bin directory on PATH:
+pnpm add --global @yargote/artifacts-cli@0.1.0-beta.1
+artifacts --version
+```
+
+If pnpm reports that no global bin directory exists, run `pnpm setup` and reopen your shell before installation.
+
+For one-off execution, pin the same version:
+
+```sh
+npx --yes @yargote/artifacts-cli@0.1.0-beta.1 --help
+pnpm dlx @yargote/artifacts-cli@0.1.0-beta.1 --help
+```
+
+`@beta` follows future prereleases. Exact versions remain reproducible. No stable `latest` release is part of this beta. An organization's pnpm minimum release age or trust policy can delay a new release. Follow that policy rather than disabling it globally.
+
+## Complete first use
+
+An existing Artifacts account is required. Select the complete OAuth resource, including `/mcp`:
+
+```sh
+export ARTIFACTS_SERVER='https://artifacts-mcp.yersonargotev.workers.dev/mcp'
+artifacts login
+artifacts whoami
+```
+
+Login opens browser authorization. After you approve access, `whoami` prints JSON with your user ID and scopes. Use `artifacts login --no-browser` to open the printed authorization URL yourself on the same machine.
+
+Create `snapshot.json`:
+
+```json
+{
+	"metadata": { "title": "My first CLI artifact", "description": "Created through REST" },
+	"content": { "kind": "text", "text": "Hello from the Artifacts CLI." },
+	"files": []
+}
+```
+
+```sh
+artifacts create --snapshot snapshot.json
+artifacts list --limit 5
+```
+
+The create result contains `artifactId` and `headRevisionId`. Use those values to read, publish, and export the exact revision:
+
+```sh
+artifacts read ARTIFACT_ID
+artifacts publish ARTIFACT_ID --revision REVISION_ID --expected-version 0
+artifacts export ARTIFACT_ID --revision REVISION_ID --out artifact.zip
+artifacts logout
+```
+
+Publication URLs require authenticated owner access. A retained request ID appears on stderr before each mutation. If the response is lost, run `artifacts retry REQUEST_ID` with the same server and state directory. Keep that state directory when upgrading, reinstalling, or switching between global and one-off execution.
+
+## Upgrade or uninstall
+
+Install another exact version with the same package manager to change the executable version. Credentials and retained operation files live outside the package installation and remain available.
+
+```sh
+npm uninstall --global @yargote/artifacts-cli
+# Or:
+pnpm remove --global @yargote/artifacts-cli
+```
+
+Run `artifacts logout` before uninstalling if you want to clear credentials. Uninstalling does not delete retained operations.
+
+## Server and local state
+
+`--server RESOURCE` selects the exact canonical OAuth resource. `ARTIFACTS_SERVER` supplies the same value. A resource ending in `/mcp` uses REST under `/mcp/v1`. The CLI has no production default.
+
+`--state-dir DIR` overrides `ARTIFACTS_STATE_DIR`. The default is `~/.local/state/artifacts`. The state directory must be private and owned by the current user. Credentials are separate from operation files. Profiles bind credentials to the exact resource. Retained operation paths hash the resource and request ID, so request IDs cannot select filesystem paths.
+
+HTTPS is required except for HTTP on the exact loopback hosts `localhost`, `127.0.0.1`, and `[::1]`. Server URLs cannot contain credentials, a query, or a fragment.
+
+## Authentication
+
+`artifacts login --server RESOURCE` verifies protected-resource metadata, registers a public native OAuth client, and opens browser authorization with PKCE. `--no-browser` prints the authorization URL for manual navigation. The loopback callback listener starts before browser navigation. Login requests read, write, and publication scopes. Client registration is reused for the profile.
+
+`artifacts whoami` returns the verified user, session, OAuth client, and scopes.
+
+`artifacts logout` clears local credentials and attempts to revoke the refresh token. Its JSON contains `signedOut: true` and `remoteRevocation` with `confirmed`, `unconfirmed`, or `not-needed`. Issued access JWTs can remain valid until expiry or central-session revocation.
+
+`ARTIFACTS_ACCESS_TOKEN` supplies an access token for automation. It does not require local login. Tokens are never command arguments or retained operation fields.
+
+The private `credentials.sqlite` file stores credentials. The separate `credentials-lock.sqlite` file contains no credentials and holds a SQLite write lock to serialize refresh and logout across processes. A committed uncertainty marker in the data file survives process death, while SQLite releases the lock. Login and logout generations prevent a late browser callback from restoring signed-out credentials. An uncertain refresh requires login.
+
+## Command syntax
+
+`artifacts --help` prints this command reference. `artifacts --version` prints the installed package version without requiring a server or login.
+
+```text
+artifacts login [--no-browser]
+artifacts logout
+artifacts whoami
+artifacts create --snapshot FILE [--request-id ID] [--response full|compact]
+artifacts create --command FILE
+artifacts list [--limit N] [--cursor CURSOR]
+artifacts read ID [--revision REV] [--response full|compact] [--out FILE]
+artifacts update ID --snapshot FILE --expected-revision REV [--request-id ID]
+                 [--response full|compact]
+artifacts update [ID] --command FILE
+artifacts edit ID --changes FILE [--request-id ID]
+artifacts history ID [--limit N] [--before-sequence N] [--summary]
+artifacts publish ID --revision REV --expected-version N [--request-id ID]
+artifacts publish [ID] --command FILE
+artifacts export ID --revision REV --out FILE
+artifacts retry REQUEST_ID
+```
+
+Global `--server RESOURCE` and `--state-dir DIR` options can appear before or after the command. Options cannot be repeated. Unknown options and options for another command fail before submission.
+
+Create and update snapshot files contain the complete domain snapshot.
+
+```json
+{
+	"metadata": { "title": "Example", "description": "A retained document", "custom": { "team": "design" } },
+	"content": { "kind": "html", "text": "<h1>Example</h1>" },
+	"files": [{ "path": "data.txt", "mediaType": "text/plain", "encoding": "utf8", "data": "retained attachment" }]
+}
+```
+
+`read --out FILE` saves the returned artifact JSON and also prints it to stdout. A default full read contains the complete snapshot under `revision.snapshot`. `export --out FILE` saves the exact ZIP and prints its filename, local path, media type, SHA-256, and byte count. Output files use exclusive creation and never overwrite an existing path.
+
+History defaults to complete revisions. `--summary` returns revision metadata and attachment summaries. `--before-sequence` continues a page. `list --cursor` continues an artifact list.
+
+## Complete commands and edits
+
+`--command FILE` accepts a complete create, update, or publish command. It cannot be combined with other mutation options. For update and publish, an optional positional artifact ID must equal the command's `artifactId`. Every field, including the omission of `response`, is retained.
+
+A complete update command has this shape.
+
+```json
+{
+	"requestId": "reviewed-update-001",
+	"artifactId": "artifact-id",
+	"expectedRevisionId": "reviewed-revision-id",
+	"snapshot": {
+		"metadata": { "title": "Reviewed title", "description": "Complete replacement" },
+		"content": { "kind": "text", "text": "Reviewed text" },
+		"files": []
+	}
+}
+```
+
+`edit ID --changes FILE` reads the current snapshot, merges partial `metadata` and `content` changes, and retains the resulting complete update. An explicit `files` array replaces the attachments. Omitted fields and attachments are preserved.
+
+```json
+{ "metadata": { "title": "Changed title" }, "content": { "text": "Changed text" } }
+```
+
+Publish always selects an immutable revision. `--expected-version 0` expects no existing publication. Later publication commands require the current publication version.
+
+## Recovery
+
+Each invocation resolves one access token for its reads, owner check, and submission. A concurrent login cannot change the command owner between these requests. Every mutation verifies the owner and retains an exclusive private operation file before submission. Missing request IDs default to random UUIDs. The operation stores its exact command, owner, and resource. It contains no credentials. Existing operation files require explicit `retry` and are never replaced by another preparation.
+
+`retry REQUEST_ID` verifies the current resource and owner, then sends the unchanged command once. Retry does not read a new head, change expected versions, add a response projection, or rebase a conflict. Its diagnostic identifies the result as a retained receipt. A fresh `read` returns current state.
+
+If a response is lost after commit, retry recovers the original receipt. If a conflict occurs, the retained operation remains available for inspection. A new read and a deliberate new command with a new request ID are required to incorporate another writer's changes.
+
+Commands exit with code `1` on failure and print a JSON error to stderr. Server errors preserve their HTTP status, code, and conflict details. Successful JSON stdout contains no progress messages or credentials.
+
+## License and support
+
+This package is MIT licensed. The client and contracts packages have their own MIT licenses. This does not license the private Artifacts application repository. Contact your Artifacts service administrator with `artifacts --version`, Node and package-manager versions, and a redacted error. Never include credentials or the contents of `credentials.sqlite`.

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@yargote/artifacts-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-beta.1",
+  "private": false,
+  "type": "module",
+  "description": "Command-line client for the Artifacts REST API.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yersonargotev/artifacts.git",
+    "directory": "apps/cli"
+  },
+  "homepage": "https://github.com/yersonargotev",
+  "bugs": {
+    "url": "https://github.com/yersonargotev"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "artifacts": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@yargote/artifacts-contracts": "0.1.0-beta.1",
+    "@yargote/artifacts-client": "0.1.0-beta.1",
+    "openid-client": "6.8.8",
+    "zod": "4.6.5"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta",
+    "provenance": false
+  }
+}

package/src/auth.d.ts

@@ -0,0 +1,18 @@
+import { type Identity } from '@yargote/artifacts-contracts/http';
+export declare function login(options: {
+    resource: string;
+    stateDir: string;
+    noBrowser: boolean;
+    onAuthorizationUrl: (url: string) => void;
+}): Promise<Identity>;
+export declare function accessToken(options: {
+    resource: string;
+    stateDir: string;
+}): Promise<string>;
+export declare function logout(options: {
+    resource: string;
+    stateDir: string;
+}): Promise<{
+    signedOut: true;
+    remoteRevocation: 'confirmed' | 'unconfirmed' | 'not-needed';
+}>;

package/src/auth.js

@@ -0,0 +1,276 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { createServer } from 'node:http';
+import * as oidc from 'openid-client';
+import { canonicalResource, identitySchema, protectedResourceMetadataUrl, restBase } from '@yargote/artifacts-contracts/http';
+import { z } from 'zod';
+import { CredentialStore } from "./credentials.js";
+const networkTimeout = 10_000;
+const callbackTimeout = 180_000;
+const scopes = 'openid profile offline_access artifacts:read artifacts:write artifacts:publish';
+const resourceMetadata = z.object({ resource: z.string(), authorization_servers: z.array(z.string()).min(1) });
+function endpoint(value, issuer) {
+    const url = new URL(value);
+    const loopback = /^http:\/\/(?:127\.0\.0\.1|\[::1\]|localhost)(?::[0-9]+)?(?:\/|$)/.test(value);
+    if (value.trim() !== value || url.username || url.password || url.search || url.hash || (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)))
+        throw new Error('OAuth URLs require HTTPS or an exact loopback HTTP host, without credentials, query, or fragment');
+    if (issuer && url.origin !== new URL(issuer).origin)
+        throw new Error('OAuth endpoints must use the issuer origin');
+    return url;
+}
+async function boundedFetch(url, options = {}) {
+    const signal = options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(networkTimeout)]) : AbortSignal.timeout(networkTimeout);
+    const response = await fetch(url, { ...options, redirect: 'manual', signal });
+    if (response.status >= 300 && response.status < 400) {
+        await response.body?.cancel();
+        throw new Error('Authentication redirects are not allowed');
+    }
+    const reader = response.body?.getReader();
+    const chunks = [];
+    let size = 0;
+    if (reader) {
+        try {
+            for (;;) {
+                const chunk = await reader.read();
+                if (chunk.done)
+                    break;
+                size += chunk.value.byteLength;
+                if (size > 1024 * 1024)
+                    throw new Error('Authentication response is too large');
+                chunks.push(chunk.value);
+            }
+        }
+        catch (error) {
+            await reader.cancel().catch(() => { });
+            throw error;
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+    return new Response(size ? Buffer.concat(chunks) : null, { status: response.status, statusText: response.statusText, headers: response.headers });
+}
+function discoveryOptions(issuer, signal) {
+    endpoint(issuer);
+    return {
+        timeout: networkTimeout / 1000,
+        execute: [...(new URL(issuer).protocol === 'http:' ? [oidc.allowInsecureRequests] : []), oidc.enableNonRepudiationChecks],
+        [oidc.customFetch]: (url, options) => boundedFetch(endpoint(url, issuer), { ...options, signal: signal && options.signal ? AbortSignal.any([signal, options.signal]) : signal ?? options.signal, body: options.body instanceof Uint8Array ? Uint8Array.from(options.body) : options.body }),
+    };
+}
+function validateConfiguration(config, issuer) {
+    const metadata = config.serverMetadata();
+    if (metadata.issuer !== issuer)
+        throw new Error('OAuth issuer metadata does not match the configured issuer');
+    for (const [key, value] of Object.entries(metadata)) {
+        if ((key.endsWith('_endpoint') || key === 'jwks_uri') && typeof value === 'string')
+            endpoint(value, issuer);
+    }
+    if (!metadata.authorization_endpoint || !metadata.token_endpoint)
+        throw new Error('OAuth metadata is missing authorization or token endpoints');
+    if (config.clientMetadata().client_secret || config.clientMetadata().token_endpoint_auth_method !== 'none')
+        throw new Error('The CLI requires a public OAuth client without a secret');
+}
+async function configuration(registration, signal) {
+    const config = await oidc.discovery(new URL(registration.issuer), registration.clientId, { token_endpoint_auth_method: 'none', id_token_signed_response_alg: 'EdDSA' }, oidc.None(), discoveryOptions(registration.issuer, signal));
+    validateConfiguration(config, registration.issuer);
+    return config;
+}
+function tokenRecord(tokens, previousRefresh) {
+    if (typeof tokens.expires_in !== 'number' || !Number.isFinite(tokens.expires_in) || tokens.expires_in <= 0)
+        throw new Error('OAuth token response is missing a valid expiration');
+    return { accessToken: tokens.access_token, refreshToken: tokens.refresh_token ?? previousRefresh, expiresAt: Date.now() + tokens.expires_in * 1000 };
+}
+async function callback() {
+    const controller = new AbortController();
+    let accept;
+    let reject;
+    let expectedState;
+    let expectedIssuer;
+    let redirectUri = '';
+    let settled = false;
+    const result = new Promise((resolve, fail) => { accept = resolve; reject = fail; });
+    void result.catch(() => { });
+    const server = createServer((request, response) => {
+        response.setHeader('cache-control', 'no-store');
+        response.setHeader('content-type', 'text/plain; charset=utf-8');
+        if (request.method !== 'GET' || !request.url || request.url.length > 8192 || request.headers.host !== new URL(redirectUri).host || request.url.split('?')[0] !== '/oauth/callback') {
+            response.writeHead(404).end('Not found');
+            return;
+        }
+        const url = new URL(request.url, redirectUri);
+        if (settled || !expectedState || url.searchParams.getAll('state').length !== 1 || url.searchParams.get('state') !== expectedState || url.searchParams.getAll('iss').length !== 1 || url.searchParams.get('iss') !== expectedIssuer || url.searchParams.getAll('code').length + url.searchParams.getAll('error').length !== 1) {
+            response.writeHead(400).end('Invalid OAuth callback');
+            return;
+        }
+        settled = true;
+        response.end('Authorization received. Return to the terminal to check the result.');
+        accept(url);
+    });
+    await new Promise((resolve, fail) => {
+        server.once('error', fail);
+        server.listen(0, '127.0.0.1', () => { server.removeListener('error', fail); resolve(); });
+    });
+    const address = server.address();
+    if (!address || typeof address === 'string')
+        throw new Error('Cannot bind the OAuth loopback callback');
+    redirectUri = `http://127.0.0.1:${address.port}/oauth/callback`;
+    const fail = (error) => { controller.abort(error); reject(error); };
+    const timer = setTimeout(() => fail(new Error('Login timed out. Run artifacts login again')), callbackTimeout);
+    const cancel = () => fail(new Error('Login cancelled'));
+    process.once('SIGINT', cancel);
+    process.once('SIGTERM', cancel);
+    return {
+        redirectUri, signal: controller.signal,
+        wait(state, issuer) { expectedState = state; expectedIssuer = issuer; return result; },
+        async close() {
+            clearTimeout(timer);
+            process.removeListener('SIGINT', cancel);
+            process.removeListener('SIGTERM', cancel);
+            server.closeAllConnections();
+            await new Promise((resolve) => server.close(() => resolve()));
+        },
+    };
+}
+async function openBrowser(url) {
+    const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'rundll32' : 'xdg-open';
+    const args = process.platform === 'win32' ? ['url.dll,FileProtocolHandler', url] : [url];
+    await new Promise((resolve, reject) => {
+        const child = spawn(command, args, { detached: true, stdio: 'ignore' });
+        child.once('error', () => reject(new Error('Cannot open a browser. Run artifacts login with --no-browser')));
+        child.once('spawn', () => { child.unref(); resolve(); });
+    });
+}
+export async function login(options) {
+    const resource = canonicalResource(options.resource);
+    const store = await CredentialStore.open(options.stateDir);
+    let listener;
+    try {
+        const epoch = await store.exclusive(() => {
+            const profile = store.read(resource);
+            store.write(resource, { ...profile, epoch: profile.epoch + 1 });
+            return profile.epoch + 1;
+        });
+        const response = await boundedFetch(protectedResourceMetadataUrl(resource));
+        if (!response.ok)
+            throw new Error('Cannot discover the protected resource');
+        const metadata = resourceMetadata.parse(await response.json());
+        if (metadata.resource !== resource)
+            throw new Error('Protected resource metadata does not match the exact server URL');
+        const issuer = metadata.authorization_servers[0];
+        endpoint(issuer);
+        listener = await callback();
+        const { redirectUri, signal } = listener;
+        const config = await store.exclusive(async () => {
+            const profile = store.read(resource);
+            if (profile.epoch !== epoch)
+                throw new Error('Login was superseded by another login or logout');
+            if (profile.registration?.issuer === issuer)
+                return configuration(profile.registration, signal);
+            const registered = await oidc.dynamicClientRegistration(new URL(issuer), {
+                client_name: 'Artifacts CLI', application_type: 'native', token_endpoint_auth_method: 'none', id_token_signed_response_alg: 'EdDSA',
+                redirect_uris: [redirectUri], grant_types: ['authorization_code', 'refresh_token'], response_types: ['code'], scope: scopes,
+            }, oidc.None(), discoveryOptions(issuer, signal));
+            validateConfiguration(registered, issuer);
+            store.write(resource, { ...profile, registration: { issuer, clientId: registered.clientMetadata().client_id }, tokens: null, refreshAttempt: null });
+            return registered;
+        });
+        const verifier = oidc.randomPKCECodeVerifier();
+        const state = oidc.randomState();
+        const nonce = oidc.randomNonce();
+        const authorizationUrl = oidc.buildAuthorizationUrl(config, {
+            redirect_uri: redirectUri, response_type: 'code', scope: scopes, resource,
+            code_challenge: await oidc.calculatePKCECodeChallenge(verifier), code_challenge_method: 'S256', state, nonce,
+        }).href;
+        const authorization = listener.wait(state, issuer);
+        options.onAuthorizationUrl(authorizationUrl);
+        if (!options.noBrowser)
+            await openBrowser(authorizationUrl);
+        const currentUrl = await authorization;
+        return await store.exclusive(async () => {
+            const profile = store.read(resource);
+            if (profile.epoch !== epoch)
+                throw new Error('Login was superseded by another login or logout');
+            const tokens = await oidc.authorizationCodeGrant(config, currentUrl, { expectedState: state, expectedNonce: nonce, pkceCodeVerifier: verifier, idTokenExpected: true }, { resource });
+            const credentials = tokenRecord(tokens);
+            const identityResponse = await boundedFetch(`${restBase(resource)}/identity`, { signal, headers: { authorization: `Bearer ${credentials.accessToken}` } });
+            if (!identityResponse.ok)
+                throw new Error('The OAuth grant cannot access this Artifacts server');
+            const identity = identitySchema.parse(await identityResponse.json());
+            const claims = tokens.claims();
+            if (claims.sub !== identity.userId || (claims.sid !== undefined && claims.sid !== identity.sessionId))
+                throw new Error('OAuth identity does not match the Artifacts session');
+            signal.throwIfAborted();
+            store.write(resource, { ...profile, tokens: credentials, refreshAttempt: null });
+            return identity;
+        });
+    }
+    finally {
+        await listener?.close();
+        store.close();
+    }
+}
+export async function accessToken(options) {
+    const resource = canonicalResource(options.resource);
+    const automationToken = process.env.ARTIFACTS_ACCESS_TOKEN;
+    if (automationToken !== undefined) {
+        if (!/^[A-Za-z0-9._~+/-]+=*$/.test(automationToken))
+            throw new Error('ARTIFACTS_ACCESS_TOKEN must contain a nonempty bearer token');
+        return automationToken;
+    }
+    const store = await CredentialStore.open(options.stateDir);
+    try {
+        return await store.exclusive(async () => {
+            const profile = store.read(resource);
+            const required = `Run artifacts login --server ${resource}`;
+            if (!profile.tokens || !profile.registration)
+                throw new Error(`You are not signed in. ${required}`);
+            if (profile.refreshAttempt)
+                throw new Error(`The previous token refresh has an uncertain result. ${required}`);
+            if (profile.tokens.expiresAt > Date.now() + 30_000)
+                return profile.tokens.accessToken;
+            if (!profile.tokens.refreshToken)
+                throw new Error(`Your session expired. ${required}`);
+            const config = await configuration(profile.registration);
+            // The separate SQLite lock survives this commit and releases automatically on process death.
+            store.write(resource, { ...profile, refreshAttempt: randomUUID() });
+            try {
+                const tokens = await oidc.refreshTokenGrant(config, profile.tokens.refreshToken, { resource });
+                const credentials = tokenRecord(tokens, profile.tokens.refreshToken);
+                store.write(resource, { ...profile, tokens: credentials, refreshAttempt: null });
+                return credentials.accessToken;
+            }
+            catch {
+                throw new Error(`Token refresh failed and its result is uncertain. ${required}`);
+            }
+        });
+    }
+    finally {
+        store.close();
+    }
+}
+export async function logout(options) {
+    const resource = canonicalResource(options.resource);
+    const store = await CredentialStore.open(options.stateDir);
+    let previous;
+    try {
+        previous = await store.exclusive(() => {
+            const profile = store.read(resource);
+            store.write(resource, { ...profile, epoch: profile.epoch + 1, tokens: null, refreshAttempt: null });
+            return profile;
+        });
+    }
+    finally {
+        store.close();
+    }
+    if (!previous.tokens?.refreshToken || !previous.registration)
+        return { signedOut: true, remoteRevocation: 'not-needed' };
+    try {
+        const config = await configuration(previous.registration);
+        await oidc.tokenRevocation(config, previous.tokens.refreshToken, { token_type_hint: 'refresh_token' });
+        return { signedOut: true, remoteRevocation: previous.refreshAttempt ? 'unconfirmed' : 'confirmed' };
+    }
+    catch {
+        return { signedOut: true, remoteRevocation: 'unconfirmed' };
+    }
+}

package/src/credentials.d.ts

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+declare const registrationSchema: z.ZodObject<{
+    issuer: z.ZodString;
+    clientId: z.ZodString;
+}, z.core.$strict>;
+declare const tokensSchema: z.ZodObject<{
+    accessToken: z.ZodString;
+    refreshToken: z.ZodOptional<z.ZodString>;
+    expiresAt: z.ZodNumber;
+}, z.core.$strict>;
+declare const profileSchema: z.ZodObject<{
+    epoch: z.ZodNumber;
+    registration: z.ZodNullable<z.ZodObject<{
+        issuer: z.ZodString;
+        clientId: z.ZodString;
+    }, z.core.$strict>>;
+    tokens: z.ZodNullable<z.ZodObject<{
+        accessToken: z.ZodString;
+        refreshToken: z.ZodOptional<z.ZodString>;
+        expiresAt: z.ZodNumber;
+    }, z.core.$strict>>;
+    refreshAttempt: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type Registration = z.infer<typeof registrationSchema>;
+export type Tokens = z.infer<typeof tokensSchema>;
+export type CredentialProfile = z.infer<typeof profileSchema>;
+export declare class CredentialStore {
+    private readonly data;
+    private readonly lock;
+    private constructor();
+    static open(stateDir: string): Promise<CredentialStore>;
+    exclusive<T>(work: () => T | Promise<T>): Promise<T>;
+    read(resource: string): CredentialProfile;
+    write(resource: string, profile: CredentialProfile): void;
+    close(): void;
+}
+export {};

package/src/credentials.js

@@ -0,0 +1,94 @@
+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';
+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');
+            });
+            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)));
+    }
+    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,242 @@
+#!/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, publishSchema, 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 { loadOperation, retainOperation, submitOperation } from "./operations.js";
+const help = `Usage: artifacts COMMAND [OPTIONS]
+
+Global options:
+  --server RESOURCE       Canonical OAuth resource, or ARTIFACTS_SERVER
+  --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:
+  login [--no-browser]
+  logout
+  whoami
+  create --snapshot FILE [--request-id ID] [--response full|compact]
+  create --command FILE
+  list [--limit N] [--cursor CURSOR]
+  read ID [--revision REV] [--response full|compact] [--out FILE]
+  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
+  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.
+Read --out saves the complete artifact JSON. Export --out saves the ZIP.
+Output files are created exclusively and never overwrite an existing path.
+JSON results go to stdout. Diagnostics and recovery guidance go to stderr.
+ARTIFACTS_ACCESS_TOKEN supplies a token for automation without local login.
+`;
+class UsageError extends Error {
+}
+const commandOptions = {
+    login: ['no-browser'], logout: [], whoami: [],
+    create: ['snapshot', 'request-id', 'response', 'command'],
+    list: ['limit', 'cursor'], read: ['revision', 'response', 'out'],
+    update: ['snapshot', 'expected-revision', 'request-id', 'response', 'command'],
+    edit: ['changes', 'request-id'], history: ['limit', 'before-sequence', 'summary'],
+    publish: ['revision', 'expected-version', 'request-id', 'command'],
+    export: ['revision', 'out'], retry: [],
+};
+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' },
+        },
+    });
+    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}`);
+    const resourceValue = values.server ?? process.env.ARTIFACTS_SERVER;
+    if (!resourceValue)
+        throw new UsageError('Specify --server RESOURCE or ARTIFACTS_SERVER. No production server is selected by default.');
+    const resource = canonicalResource(resourceValue);
+    const stateDir = resolve(values['state-dir'] ?? process.env.ARTIFACTS_STATE_DIR ?? join(homedir(), '.local', 'state', 'artifacts'));
+    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);
+    }
+    const response = values.response;
+    if (response !== undefined && response !== 'full' && response !== 'compact')
+        throw new UsageError('--response requires full or compact');
+    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();
+            return login({ resource, stateDir, noBrowser: values['no-browser'] ?? false, onAuthorizationUrl: (url) => { process.stderr.write(`Authorize this login in your browser:\n${url}\n`); } });
+        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')), ...(response === undefined ? {} : { response }) }) });
+        }
+        case 'list':
+            none();
+            return client.list({ ...(values.limit === undefined ? {} : { limit: integer('limit') }), ...(values.cursor === undefined ? {} : { cursor: values.cursor }) });
+        case 'read': {
+            const result = await client.read({ artifactId: argument(), ...(values.revision === undefined ? {} : { revisionId: values.revision }), ...(response === undefined ? {} : { response }) });
+            if (values.out)
+                await writeOutput(values.out, `${JSON.stringify(result, null, 2)}\n`);
+            return 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 '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}. The result is its retained receipt and may differ from 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,144 @@
+import { z } from 'zod';
+import { createSchema, publishSchema, 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";
+                }>;
+                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<"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";
+                }>;
+                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>], "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>;
+};
+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<{
+    revisionId: string;
+    version: number;
+    url: string;
+    artifactId: string;
+}> | Promise<{
+    artifactId: string;
+    ownerId: string;
+    headRevisionId: string;
+    publication: {
+        revisionId: string;
+        version: number;
+        url: string;
+    } | null;
+    revision: {
+        id: string;
+        parentRevisionId: string | null;
+        sequence: number;
+        authorUserId: string;
+        authorClientId: string;
+        createdAt: string;
+        sha256: string;
+        snapshot: {
+            metadata: {
+                title: string;
+                description: string;
+                custom?: z.core.util.JSONType | undefined;
+            };
+            content: {
+                kind: "text" | "html" | "markdown";
+                text: string;
+            };
+            files: {
+                path: string;
+                mediaType: string;
+                encoding: "utf8" | "base64";
+                data: string;
+            }[];
+        };
+    };
+} | import("@yargote/artifacts-client").CompactArtifactRead>;

package/src/operations.js

@@ -0,0 +1,90 @@
+import { constants } from 'node:fs';
+import { lstat, mkdir, open } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { createSchema, publishSchema, updateSchema } from '@yargote/artifacts-contracts';
+import { canonicalResource } from '@yargote/artifacts-contracts/http';
+const binding = {
+    version: z.literal(1),
+    resource: z.string().transform(canonicalResource),
+    ownerId: z.string().min(1).max(128),
+};
+export const operationSchema = z.discriminatedUnion('kind', [
+    z.strictObject({ ...binding, kind: z.literal('create'), command: createSchema }),
+    z.strictObject({ ...binding, kind: z.literal('update'), command: updateSchema }),
+    z.strictObject({ ...binding, kind: z.literal('publish'), command: publishSchema }),
+]);
+export function operationPath(stateDir, resource, requestId) {
+    createSchema.shape.requestId.parse(requestId);
+    return join(stateDir, 'operations', `${createHash('sha256').update(JSON.stringify([canonicalResource(resource), requestId])).digest('hex')}.json`);
+}
+async function privateDirectory(path) {
+    await mkdir(path, { recursive: true, mode: 0o700 });
+    const stat = await lstat(path);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || (process.getuid && stat.uid !== process.getuid()) || (process.platform !== 'win32' && (stat.mode & 0o077) !== 0))
+        throw new Error(`The state directory must be private and owned by the current user: ${path}`);
+}
+export async function retainOperation(stateDir, resource, ownerId, mutation) {
+    const operation = operationSchema.parse({ version: 1, resource, ownerId, ...mutation });
+    await privateDirectory(stateDir);
+    const directory = join(stateDir, 'operations');
+    await privateDirectory(directory);
+    const path = operationPath(stateDir, resource, operation.command.requestId);
+    let file;
+    try {
+        file = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            throw new Error(`An operation already exists for ${operation.command.requestId}. Use artifacts retry ${operation.command.requestId} to send the retained command.`);
+        throw error;
+    }
+    try {
+        await file.writeFile(`${JSON.stringify(operation)}\n`, 'utf8');
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+    if (process.platform !== 'win32') {
+        const handle = await open(directory, constants.O_RDONLY);
+        try {
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    return operation;
+}
+export async function loadOperation(stateDir, requestId, resource, ownerId) {
+    await privateDirectory(stateDir);
+    await privateDirectory(join(stateDir, 'operations'));
+    const file = await open(operationPath(stateDir, resource, requestId), constants.O_RDONLY | constants.O_NOFOLLOW);
+    let bytes;
+    try {
+        const stat = await file.stat();
+        if (!stat.isFile() || stat.size > 8 * 1024 * 1024 || (process.getuid && stat.uid !== process.getuid()) || (process.platform !== 'win32' && (stat.mode & 0o077) !== 0))
+            throw new Error('The retained operation must be a private regular file no larger than 8 MiB');
+        bytes = await file.readFile();
+    }
+    finally {
+        await file.close();
+    }
+    const operation = operationSchema.parse(JSON.parse(bytes.toString('utf8')));
+    if (operation.command.requestId !== requestId)
+        throw new Error('The retained request ID does not match the requested operation');
+    if (operation.resource !== canonicalResource(resource))
+        throw new Error('The retained operation belongs to a different server resource');
+    if (operation.ownerId !== ownerId)
+        throw new Error('The retained operation belongs to a different owner');
+    return operation;
+}
+export function submitOperation(client, operation) {
+    switch (operation.kind) {
+        case 'create': return client.create(operation.command);
+        case 'update': return client.update(operation.command);
+        case 'publish': return client.publish(operation.command);
+    }
+}