@yargote/artifacts-cli 0.1.0-beta.3 → 0.1.0-beta.4

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.3
+npm install --global @yargote/artifacts-cli@0.1.0-beta.4
 # Or, with pnpm and an existing global bin directory on PATH:
-pnpm add --global @yargote/artifacts-cli@0.1.0-beta.3
+pnpm add --global @yargote/artifacts-cli@0.1.0-beta.4
 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.3 --help
-pnpm dlx @yargote/artifacts-cli@0.1.0-beta.3 --help
+npx --yes @yargote/artifacts-cli@0.1.0-beta.4 --help
+pnpm dlx @yargote/artifacts-cli@0.1.0-beta.4 --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.
@@ -108,9 +108,11 @@ The private `credentials.sqlite` file stores credentials. The separate `credenti
 artifacts login [--no-browser]
 artifacts logout
 artifacts whoami
-artifacts create --snapshot FILE [--request-id ID] [--response full|compact]
+artifacts create --snapshot FILE [--project NAME] [--request-id ID]
+                 [--response full|compact]
 artifacts create --command FILE
-artifacts list [--limit N] [--cursor CURSOR]
+artifacts list [--limit N] [--cursor CURSOR] [--project NAME]
+artifacts projects
 artifacts read ID [--revision REV] [--response full|compact] [--out FILE [--quiet]]
 artifacts update ID --snapshot FILE --expected-revision REV [--request-id ID]
                  [--response full|compact]
@@ -120,6 +122,8 @@ 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 move ID --project NAME [--request-id ID]
+artifacts move ID --no-project [--request-id ID]
 artifacts retry REQUEST_ID
 artifacts skills [list]
 artifacts skills get NAME [--full]
@@ -175,6 +179,24 @@ A default full read contains the complete snapshot under `revision.snapshot`. `e
 
 History defaults to complete revisions. `--summary` returns revision metadata and attachment summaries. `--before-sequence` continues a page. `list --cursor` continues an artifact list.
 
+## Projects
+
+A project groups artifacts by name. `create --snapshot FILE --project NAME` files the new artifact under that project. A name that matches an existing project regardless of letter case reuses its stored spelling, so `--project alpha` joins `Alpha`. Names are trimmed and NFC-normalized, contain 1 to 80 characters, and cannot contain control characters. A complete create command file can include the same optional `project` field.
+
+```sh
+artifacts create --snapshot snapshot.json --project Alpha
+artifacts list --project alpha
+artifacts projects
+artifacts move ARTIFACT_ID --project Beta
+artifacts move ARTIFACT_ID --no-project
+```
+
+Every artifact read and list item includes `project`, a name or null. `projects` prints `{ "items": [{ "name": "Alpha", "artifactCount": 1 }] }`, ordered by name without regard to letter case. A project exists only while it contains an artifact.
+
+`move ID` requires exactly one of `--project NAME` or `--no-project`. It prints `{ "artifactId": "...", "project": "Beta" }` with the stored spelling, or `null` after `--no-project`. Move never creates a revision or changes the publication. Moving to the current project succeeds without change. Move is a retained mutation like the others, so `retry` recovers a lost response.
+
+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.
+
 ## 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yargote/artifacts-cli",
-  "version": "0.1.0-beta.3",
+  "version": "0.1.0-beta.4",
   "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.3",
-    "@yargote/artifacts-client": "0.1.0-beta.3",
+    "@yargote/artifacts-contracts": "0.1.0-beta.4",
+    "@yargote/artifacts-client": "0.1.0-beta.4",
     "openid-client": "6.8.8",
     "zod": "4.6.5"
   },

package/skills/artifacts-cli/SKILL.md

@@ -31,6 +31,12 @@ Resolve an existing artifact by its supplied ID, an observed publication URL, or
 
 Use `edit` for partial changes that preserve omitted fields. Use `update` for a complete next snapshot with the observed `headRevisionId` as its expected revision. Changing the attachment list replaces that inventory; an empty list removes all attachments. An update creates a retained revision and does not change the published revision.
 
+## Organize projects
+
+When the user names a project for new content, add `--project NAME` to `create`. Run `artifacts projects` first when an existing project may already fit. A name matching an existing project regardless of letter case joins it and keeps the stored spelling. Do not invent a project the user did not ask for. Use `list --project NAME` to find artifacts in a project.
+
+Use `move ID --project NAME` to file an existing artifact under a project and `move ID --no-project` to remove it from one. A move changes only the project. It creates no revision and leaves the publication unchanged. It is a retained mutation, so recover an uncertain move with `retry`. Verify it with `read` or `list --project NAME`. A project disappears when its last artifact leaves it.
+
 ## Publish deliberately
 
 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.

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

@@ -75,6 +75,22 @@ For `read`, `--out FILE --quiet` saves the returned response without printing su
 
 Check installed help for `--quiet` support before running these examples. Older versions, including `0.1.0-beta.1`, can suppress stdout with `artifacts read ARTIFACT_ID --out saved.json > /dev/null`. This redirection preserves stderr and the command's exit status. Use the same fallback for the revision reads below.
 
+## Organize projects
+
+Check that installed help lists `projects` and `move` before using them.
+
+```sh
+artifacts create --snapshot snapshot.json --project "Client onboarding"
+artifacts projects
+artifacts list --project "client onboarding"
+artifacts move ARTIFACT_ID --project Archive
+artifacts move ARTIFACT_ID --no-project
+```
+
+A project name contains 1 to 80 characters after trimming and NFC normalization, without control characters. A name that matches an existing project regardless of letter case joins it and keeps its stored spelling. Every read and list item includes `project`, a name or null. `projects` prints `{ "items": [{ "name": "Client onboarding", "artifactCount": 1 }] }`, ordered by name without regard to letter case. A project exists only while it contains an artifact.
+
+`move` takes exactly one of `--project NAME` or `--no-project` and prints `{ "artifactId": "...", "project": "Archive" }`, or `null` for the project after `--no-project`. It creates no revision and leaves the publication unchanged. Moving to the current project succeeds without change. A lost move response is recovered with `retry REQUEST_ID` like any other retained mutation.
+
 ## Edit without losing retained data
 
 For a title change, save `changes.json` with only the requested field.
@@ -104,7 +120,7 @@ Command files contain the command itself, without the CLI's retained-operation w
 | `update` | `requestId`, `artifactId`, `expectedRevisionId`, `snapshot` |
 | `publish` | `requestId`, `artifactId`, `revisionId`, `expectedPublicationVersion` |
 
-`requestId` is a caller-chosen string of 8 to 128 characters. Create and update also accept optional `response` with value `full` or `compact`. This complete update example replaces a snapshot. Substitute the observed IDs and preserve all required content and attachments in its `snapshot`.
+`requestId` is a caller-chosen string of 8 to 128 characters. Create and update also accept optional `response` with value `full` or `compact`. Create also accepts an optional `project` name. This complete update example replaces a snapshot. Substitute the observed IDs and preserve all required content and attachments in its `snapshot`.
 
 ```json
 {

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, publishSchema, updateSchema } from '@yargote/artifacts-contracts';
+import { createSchema, moveSchema, 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";
@@ -30,9 +30,11 @@ Commands:
   login [--no-browser]
   logout
   whoami
-  create --snapshot FILE [--request-id ID] [--response full|compact]
+  create --snapshot FILE [--project NAME] [--request-id ID]
+         [--response full|compact]
   create --command FILE
-  list [--limit N] [--cursor CURSOR]
+  list [--limit N] [--cursor CURSOR] [--project NAME]
+  projects
   read ID [--revision REV] [--response full|compact] [--out FILE [--quiet]]
   update ID --snapshot FILE --expected-revision REV [--request-id ID]
          [--response full|compact]
@@ -42,11 +44,16 @@ Commands:
   publish ID --revision REV --expected-version N [--request-id ID]
   publish [ID] --command FILE
   export ID --revision REV --out FILE
+  move ID --project NAME [--request-id ID]
+  move ID --no-project [--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 of an artifact
+without creating a revision; --no-project removes it from its project.
 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.
@@ -63,12 +70,12 @@ class UsageError extends Error {
 }
 const commandOptions = {
     login: ['no-browser'], logout: [], whoami: [],
-    create: ['snapshot', 'request-id', 'response', 'command'],
-    list: ['limit', 'cursor'], read: ['revision', 'response', 'out', 'quiet'],
+    create: ['snapshot', 'project', 'request-id', 'response', 'command'],
+    list: ['limit', 'cursor', 'project'], projects: [], read: ['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'],
-    export: ['revision', 'out'], retry: [],
+    export: ['revision', 'out'], move: ['project', 'no-project', 'request-id'], retry: [],
     skills: ['full', 'all', 'agent', 'global', 'force'],
 };
 async function jsonFile(path) {
@@ -105,6 +112,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' },
         },
     });
     const seen = new Set();
@@ -203,11 +211,14 @@ async function main() {
             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 }) }) });
+            return mutate({ kind: 'create', command: createSchema.parse({ requestId: values['request-id'] ?? randomUUID(), snapshot: await jsonFile(required('snapshot')), ...(values.project === undefined ? {} : { project: values.project }), ...(response === undefined ? {} : { response }) }) });
         }
         case 'list':
             none();
-            return client.list({ ...(values.limit === undefined ? {} : { limit: integer('limit') }), ...(values.cursor === undefined ? {} : { cursor: values.cursor }) });
+            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 'read': {
             const result = await client.read({ artifactId: argument(), ...(values.revision === undefined ? {} : { revisionId: values.revision }), ...(response === undefined ? {} : { response }) });
             if (values.out)
@@ -238,6 +249,12 @@ async function main() {
             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();
+            if ((values.project !== undefined) === (values['no-project'] ?? false))
+                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 'retry': {
             const requestId = argument();
             const owner = await client.identity();

package/src/operations.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { createSchema, publishSchema, updateSchema } from '@yargote/artifacts-contracts';
+import { createSchema, moveSchema, 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">;
@@ -29,6 +29,7 @@ export declare const operationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                 data: z.ZodString;
             }, z.core.$strict>>;
         }, z.core.$strict>;
+        project: z.ZodOptional<z.ZodString>;
         response: z.ZodOptional<z.ZodEnum<{
             full: "full";
             compact: "compact";
@@ -86,6 +87,16 @@ 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<"move">;
+    command: z.ZodObject<{
+        requestId: z.ZodString;
+        artifactId: z.ZodString;
+        project: 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>], "kind">;
 export type PreparedOperation = z.infer<typeof operationSchema>;
 export type Mutation = {
@@ -97,48 +108,19 @@ export type Mutation = {
 } | {
     kind: 'publish';
     command: z.input<typeof publishSchema>;
+} | {
+    kind: 'move';
+    command: z.input<typeof moveSchema>;
 };
 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<{
+    artifactId: string;
+    project: string | null;
+}> | 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

@@ -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, publishSchema, updateSchema } from '@yargote/artifacts-contracts';
+import { createSchema, moveSchema, publishSchema, updateSchema } from '@yargote/artifacts-contracts';
 import { canonicalResource } from '@yargote/artifacts-contracts/http';
 const binding = {
     version: z.literal(1),
@@ -14,6 +14,7 @@ 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 }),
+    z.strictObject({ ...binding, kind: z.literal('move'), command: moveSchema }),
 ]);
 export function operationPath(stateDir, resource, requestId) {
     createSchema.shape.requestId.parse(requestId);
@@ -86,5 +87,6 @@ export function submitOperation(client, operation) {
         case 'create': return client.create(operation.command);
         case 'update': return client.update(operation.command);
         case 'publish': return client.publish(operation.command);
+        case 'move': return client.move(operation.command);
     }
 }