@yargote/artifacts-cli 0.1.0-beta.5 → 0.1.0-beta.6

package/README.md

@@ -11,9 +11,9 @@ Use Node 24 or later. The beta targets macOS and Linux. Windows has not been ver
 Choose one persistent installation:
 
 ```sh
-npm install --global @yargote/artifacts-cli@0.1.0-beta.5
+npm install --global @yargote/artifacts-cli@0.1.0-beta.6
 # Or, with pnpm and an existing global bin directory on PATH:
-pnpm add --global @yargote/artifacts-cli@0.1.0-beta.5
+pnpm add --global @yargote/artifacts-cli@0.1.0-beta.6
 artifacts --version
 ```
 
@@ -22,8 +22,8 @@ If pnpm reports that no global bin directory exists, run `pnpm setup` and reopen
 For one-off execution, pin the same version:
 
 ```sh
-npx --yes @yargote/artifacts-cli@0.1.0-beta.5 --help
-pnpm dlx @yargote/artifacts-cli@0.1.0-beta.5 --help
+npx --yes @yargote/artifacts-cli@0.1.0-beta.6 --help
+pnpm dlx @yargote/artifacts-cli@0.1.0-beta.6 --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.
@@ -64,7 +64,7 @@ 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.
+A publication URL requires sign-in. It opens for the owner and for a user whose verified email equals an email share of the artifact. That user sees only the published revision and its attachments. 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
 
@@ -124,6 +124,9 @@ artifacts publish [ID] --command FILE
 artifacts export ID --revision REV --out FILE
 artifacts move ID --project NAME [--request-id ID]
 artifacts move ID --no-project [--request-id ID]
+artifacts share ID --email EMAIL [--notify] [--request-id ID]
+artifacts shares ID
+artifacts unshare ID SHARE_ID [--request-id ID]
 artifacts retry REQUEST_ID
 artifacts skills [list]
 artifacts skills get NAME [--full]
@@ -197,6 +200,27 @@ Every artifact read and list item includes `project`, a name or null. `projects`
 
 Version `0.1.0-beta.4` and earlier parse artifact responses strictly and fail with `invalid_response` against a server that returns `project`. Upgrade the CLI together with the server.
 
+## Share publication access
+
+These commands are available from `0.1.0-beta.6`. Check installed help for support.
+
+```sh
+artifacts share ARTIFACT_ID --email ana@example.com --request-id share-ana-001
+artifacts shares ARTIFACT_ID
+artifacts unshare ARTIFACT_ID SHARE_ID --request-id unshare-ana-001
+artifacts retry share-ana-001
+```
+
+`share` trims and lowercases the email and prints one share as JSON with `shareId`, `artifactId`, `kind: "email"`, `value`, and `createdAt`. `shares` prints `{ "items": [...] }` with current grants and retains no operation. Take `SHARE_ID` from that output. `unshare` and a successful retry of an unshare exit zero with empty stdout. All three commands require the owner's `artifacts:publish` scope.
+
+A signed-in user whose verified email matches a share can view the published revision and its attachments. History, export, edits, and project moves remain owner-only. Shares created before first publication remain stored, but the URL opens only after publication. Add `--notify` to request one invitation email. Invited people can sign in with an email code when the server enables email.
+
+Share and unshare retain the complete normalized command before submission. Recover an uncertain result with `retry REQUEST_ID`. A replay confirms the original operation, so a historical share replay does not restore a revoked grant. An old unshare replay leaves a deliberate new share intact. Run `shares ARTIFACT_ID` to verify current grants.
+
+Share with `--notify` to request one email attempt. Access succeeds when mail is disabled or the owner has used the daily allowance. The JSON result adds `notification.status` as `requested` or `skipped`, with `disabled` or `rate_limited` as the skip reason. `requested` does not confirm delivery. A crash after commit can lose the message. An exact retry preserves the captured flag and never sends a second email. Use a new deliberate command to request another attempt for existing access.
+
+Owners can reserve 100 invitations per UTC day. Revoke, deletion, and failed delivery do not refund reservations. New access is limited to 100 people per artifact and 1000 grants per owner. Existing access remains listable and revocable.
+
 ## 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.
@@ -228,7 +252,7 @@ Publish always selects an immutable revision. `--expected-version 0` expects no
 
 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.
+`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 replay of the original operation and warns that replay does not establish current state. A fresh `read` or `shares` 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yargote/artifacts-cli",
-  "version": "0.1.0-beta.5",
+  "version": "0.1.0-beta.6",
   "private": false,
   "type": "module",
   "description": "Command-line client for the Artifacts REST API.",
@@ -27,8 +27,8 @@
     "skills"
   ],
   "dependencies": {
-    "@yargote/artifacts-contracts": "0.1.0-beta.5",
-    "@yargote/artifacts-client": "0.1.0-beta.5",
+    "@yargote/artifacts-contracts": "0.1.0-beta.6",
+    "@yargote/artifacts-client": "0.1.0-beta.6",
     "openid-client": "6.8.8",
     "zod": "4.6.5"
   },

package/skills/artifacts-cli/SKILL.md

@@ -41,7 +41,17 @@ Use `move ID --project NAME` to file an existing artifact under a project and `m
 
 Publish when the user requests publication, a shareable artifact URL, or a change to the live artifact. Use the exact saved revision selected by the user or returned by the edit. Read the current publication version before preparing publication. Use zero only when the artifact is unpublished.
 
-A published URL still requires its owner's Artifacts login. Publishing a historical revision leaves the draft head unchanged. Report the returned protected URL only after the publication succeeds and its current state is verified.
+A published URL requires sign-in by the owner or a user whose verified email matches a current share. Publishing a historical revision leaves the draft head unchanged. Report the returned protected URL only after the publication succeeds and its current state is verified.
+
+## Share publication access
+
+Check installed help for `share`, `shares`, and `unshare` support. These commands are available from `0.1.0-beta.6`. Share only when the user requests access for an exact email. Use `share ARTIFACT_ID --email EMAIL`, then verify the normalized email with `shares ARTIFACT_ID`. Use the observed `shareId` with `unshare ARTIFACT_ID SHARE_ID` to revoke it. Unshare and its successful retry exit zero with empty stdout.
+
+A matching signed-in user must have a verified email. Access covers the published revision and its attachments. History, export, editing, and project moves stay owner-only. A share before first publication remains stored and waits for publication. Add `--notify` when the user asks for an invitation email. Invited people can sign in with an email code when the server enables email.
+
+Recover uncertain share or unshare results with `retry REQUEST_ID`. Replay confirms the original operation and does not establish current grants. An old share replay does not restore revoked access. An old unshare replay does not remove a deliberate new share. Verify current grants with `shares ARTIFACT_ID`.
+
+When the user asks to notify an invited person, add `--notify` to `artifacts share`. Preserve that flag in the retained command and use `artifacts retry` after an uncertain response. Report `requested` as an invitation request, never as confirmed delivery. A skipped notification still grants access. A new deliberate share command can request another attempt for existing access, subject to the owner's daily allowance.
 
 ## Recover an uncertain write
 

package/skills/artifacts-cli/references/commands.md

@@ -158,6 +158,27 @@ The publication example applies only to an unpublished artifact. For an existing
 
 History returns `nextBeforeSequence`; pass it as `--before-sequence N` to continue. List returns `nextCursor`; pass it as `--cursor CURSOR`. Do not substitute an offset or assume that one page contains everything.
 
+## Share publication access
+
+Check installed help for these commands. They are available from `0.1.0-beta.6`.
+
+```sh
+artifacts share ARTIFACT_ID --email ana@example.com --request-id share-ana-001
+artifacts shares ARTIFACT_ID
+artifacts unshare ARTIFACT_ID SHARE_ID --request-id unshare-ana-001
+artifacts retry share-ana-001
+```
+
+Share requires the owner's `artifacts:publish` scope, trims and lowercases the email, and prints a share with `shareId`, `artifactId`, `kind: "email"`, `value`, and `createdAt`. `shares` requires the same scope and prints `{ "items": [...] }` with current grants without retaining a mutation. Use an observed `shareId` to unshare. Unshare requires the same scope. Unshare and its successful retry exit zero with empty stdout.
+
+The publication admits the owner and signed-in users whose verified email matches a current share. Guests see the published revision and attachments. History, export, editing, and project moves remain owner-only. Shares before first publication wait for publication. Add `--notify` to request one invitation email. Invited people can sign in with an email code when the server enables email.
+
+Share and unshare retain complete normalized commands. `retry REQUEST_ID` replays the original operation. A historical share replay does not regrant revoked access, and an old unshare replay leaves a deliberate new share intact. Verify current grants with `shares ARTIFACT_ID` after a replay.
+
+Share with `--notify` to request one email attempt. Access succeeds when mail is disabled or the owner has used the daily allowance. The JSON result adds `notification.status` as `requested` or `skipped`, with `disabled` or `rate_limited` as the skip reason. `requested` does not confirm delivery. A crash after commit can lose the message. An exact retry preserves the captured flag and never sends a second email. Use a new deliberate command to request another attempt for existing access.
+
+Owners can reserve 100 invitations per UTC day. Revoke, deletion, and failed delivery do not refund reservations. New access is limited to 100 people per artifact and 1000 grants per owner. Existing access remains listable and revocable.
+
 ## Retry and export
 
 ```sh

package/src/index.js

@@ -6,7 +6,7 @@ import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
 import { z } from 'zod';
-import { createSchema, moveSchema, publishSchema, updateSchema } from '@yargote/artifacts-contracts';
+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";
@@ -46,6 +46,9 @@ Commands:
   export ID --revision REV --out FILE
   move ID --project NAME [--request-id ID]
   move ID --no-project [--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.
@@ -75,6 +78,7 @@ const commandOptions = {
     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', 'request-id'], retry: [],
     skills: ['full', 'all', 'agent', 'global', 'force'],
 };
@@ -112,7 +116,7 @@ async function main() {
             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' },
+            project: { type: 'string' }, 'no-project': { type: 'boolean' }, email: { type: 'string' }, notify: { type: 'boolean' },
         },
     });
     const seen = new Set();
@@ -255,11 +259,18 @@ async function main() {
                 throw new UsageError('Specify exactly one of --project NAME or --no-project');
             return mutate({ kind: 'move', command: moveSchema.parse({ artifactId, requestId: values['request-id'] ?? randomUUID(), project: values.project ?? null }) });
         }
+        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}. The result is its retained receipt and may differ from current state.\n`);
+            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);
         }
     }

package/src/operations.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { createSchema, moveSchema, publishSchema, updateSchema } from '@yargote/artifacts-contracts';
+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">;
@@ -97,6 +97,28 @@ export declare const operationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     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 = {
@@ -111,11 +133,33 @@ export type Mutation = {
 } | {
     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<{
+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<{

package/src/operations.js

@@ -3,7 +3,7 @@ import { lstat, mkdir, open } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
 import { join } from 'node:path';
 import { z } from 'zod';
-import { createSchema, moveSchema, publishSchema, updateSchema } from '@yargote/artifacts-contracts';
+import { createSchema, moveSchema, publishSchema, shareSchema, unshareSchema, updateSchema } from '@yargote/artifacts-contracts';
 import { canonicalResource } from '@yargote/artifacts-contracts/http';
 const binding = {
     version: z.literal(1),
@@ -15,6 +15,8 @@ export const operationSchema = z.discriminatedUnion('kind', [
     z.strictObject({ ...binding, kind: z.literal('update'), command: updateSchema }),
     z.strictObject({ ...binding, kind: z.literal('publish'), command: publishSchema }),
     z.strictObject({ ...binding, kind: z.literal('move'), command: moveSchema }),
+    z.strictObject({ ...binding, kind: z.literal('share'), command: shareSchema }),
+    z.strictObject({ ...binding, kind: z.literal('unshare'), command: unshareSchema }),
 ]);
 export function operationPath(stateDir, resource, requestId) {
     createSchema.shape.requestId.parse(requestId);
@@ -88,5 +90,9 @@ export function submitOperation(client, operation) {
         case 'update': return client.update(operation.command);
         case 'publish': return client.publish(operation.command);
         case 'move': return client.move(operation.command);
+        case 'share': return client.share(operation.command);
+        case 'unshare': return client.unshare(operation.command);
     }
+    const exhaustive = operation;
+    throw new Error(`Unsupported retained operation: ${exhaustive}`);
 }