@yargote/artifacts-cli 0.1.0-beta.1 → 0.1.0-beta.10

package/src/index.js

@@ -6,28 +6,41 @@ 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, listSharesSchema, moveSchema, publishSchema, shareSchema, unshareSchema, updateSchema } from '@yargote/artifacts-contracts';
 import { canonicalResource } from '@yargote/artifacts-contracts/http';
 import { createArtifactHttpClient, HttpError, prepareArtifactEdit } from '@yargote/artifacts-client';
 import { accessToken, login, logout } from "./auth.js";
+import { CredentialStore } from "./credentials.js";
 import { loadOperation, retainOperation, submitOperation } from "./operations.js";
+import { runSkillsCommand } from "./skills.js";
 const help = `Usage: artifacts COMMAND [OPTIONS]
 
 Global options:
-  --server RESOURCE       Canonical OAuth resource, or ARTIFACTS_SERVER
+  --server RESOURCE       Exact REST OAuth resource, or ARTIFACTS_SERVER
+                         Defaults to the last successful login
   --state-dir DIR         Private local state, or ARTIFACTS_STATE_DIR
                          Default: ~/.local/state/artifacts
   --help                 Print this reference
   --version              Print the installed package version
 
 Commands:
+  skills [list]
+  skills get NAME [--full]
+  skills get --all [--full]
+  skills path [NAME]
+  skills install [NAME] [--agent claude] [--global] [--force]
   login [--no-browser]
   logout
   whoami
-  create --snapshot FILE [--request-id ID] [--response full|compact]
+  create --snapshot FILE [--project NAME] [--slug SLUG] [--request-id ID]
+         [--response full|compact]
   create --command FILE
-  list [--limit N] [--cursor CURSOR]
-  read ID [--revision REV] [--response full|compact] [--out FILE]
+  list [--limit N] [--cursor CURSOR] [--project NAME]
+  projects
+  search QUERY [--project NAME] [--limit N] [--cursor CURSOR]
+  read ID [--revision REV] [--response full|compact] [--out FILE [--quiet]]
+  read --slug SLUG [--project NAME] [--revision REV] [--response full|compact]
+         [--out FILE [--quiet]]
   update ID --snapshot FILE --expected-revision REV [--request-id ID]
          [--response full|compact]
   update [ID] --command FILE
@@ -36,26 +49,63 @@ 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 | --no-project] [--slug SLUG | --no-slug]
+         [--request-id ID]
+  share ID --email EMAIL [--notify] [--request-id ID]
+  shares ID
+  unshare ID SHARE_ID [--request-id ID]
   retry REQUEST_ID
 
 Mutation command files contain the complete create, update, or publish JSON.
 Mutation request IDs default to a random UUID. Commands are retained before
 submission. Retry sends the exact retained command for the same server and owner.
-Read --out saves the complete artifact JSON. Export --out saves the ZIP.
+Projects group artifacts by name without regard to letter case. A project
+exists while it contains an artifact. Move changes the project or the slug of
+an artifact without creating a revision. It needs at least one of its four
+options. --no-project removes the artifact from its project, and --no-slug
+clears its slug. An option left out keeps that value, so a move to another
+project keeps the slug.
+A slug such as concepts/rag names an artifact within its project, or within
+the unfiled artifacts without --project. Read --slug finds it without its ID.
+Create or move fails with slug_conflict when the project already uses the slug.
+Search finds owned Markdown and text artifacts whose title, description, or
+content contains every term of QUERY, ignoring letter case and accents. Quote a
+QUERY with spaces. Results are ordered by relevance with a **bold** snippet.
+Read --out saves the returned artifact JSON. Export --out saves the ZIP.
+Read --quiet requires --out and suppresses successful JSON stdout.
 Output files are created exclusively and never overwrite an existing path.
 JSON results go to stdout. Diagnostics and recovery guidance go to stderr.
+Login accepts an MCP URL when its metadata advertises artifacts_rest_resource.
+Split MCP and REST resources require this relation. Login remembers the verified
+REST URL for later commands. --server takes precedence over ARTIFACTS_SERVER,
+which takes precedence over the saved URL. Ordinary overrides do not replace
+the saved URL. Logout keeps it for a later login.
+Login checks <resource>/v1/identity before browser
+authorization. Legacy /mcp
+resources work when their REST API is at /mcp/v1. If the check fails, confirm
+the configured REST URL with your service administrator.
+Login errors report the phase, method, endpoint, and HTTP status when received.
+Network failures have no HTTP status. Login verifies identity again after OAuth.
 ARTIFACTS_ACCESS_TOKEN supplies a token for automation without local login.
+Skills commands work offline without a server, login, or private state.
+They print plain text. Global server and state options are accepted and ignored.
+Skills install defaults to artifacts-cli under .agents/skills in the current
+directory. --agent claude uses .claude/skills. --global uses your home directory.
+The installed discovery file loads instructions through artifacts skills get.
+Identical files stay unchanged. Differing files require --force.
 `;
 class UsageError extends Error {
 }
 const commandOptions = {
     login: ['no-browser'], logout: [], whoami: [],
-    create: ['snapshot', 'request-id', 'response', 'command'],
-    list: ['limit', 'cursor'], read: ['revision', 'response', 'out'],
+    create: ['snapshot', 'project', 'slug', 'request-id', 'response', 'command'],
+    list: ['limit', 'cursor', 'project'], projects: [], search: ['project', 'limit', 'cursor'], read: ['slug', 'project', 'revision', 'response', 'out', 'quiet'],
     update: ['snapshot', 'expected-revision', 'request-id', 'response', 'command'],
     edit: ['changes', 'request-id'], history: ['limit', 'before-sequence', 'summary'],
     publish: ['revision', 'expected-version', 'request-id', 'command'],
-    export: ['revision', 'out'], retry: [],
+    share: ['email', 'notify', 'request-id'], shares: [], unshare: ['request-id'],
+    export: ['revision', 'out'], move: ['project', 'no-project', 'slug', 'no-slug', 'request-id'], retry: [],
+    skills: ['full', 'all', 'agent', 'global', 'force'],
 };
 async function jsonFile(path) {
     const file = await open(path, constants.O_RDONLY);
@@ -88,7 +138,10 @@ async function main() {
             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' },
+            summary: { type: 'boolean' }, out: { type: 'string' }, quiet: { type: 'boolean' },
+            full: { type: 'boolean' }, all: { type: 'boolean' }, agent: { type: 'string' },
+            global: { type: 'boolean' }, force: { type: 'boolean' },
+            project: { type: 'string' }, 'no-project': { type: 'boolean' }, slug: { type: 'string' }, 'no-slug': { type: 'boolean' }, email: { type: 'string' }, notify: { type: 'boolean' },
         },
     });
     const seen = new Set();
@@ -114,11 +167,22 @@ async function main() {
     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);
+    if (command === 'skills')
+        return runSkillsCommand(arguments_, values, seen);
     const stateDir = resolve(values['state-dir'] ?? process.env.ARTIFACTS_STATE_DIR ?? join(homedir(), '.local', 'state', 'artifacts'));
+    let resourceValue = values.server ?? process.env.ARTIFACTS_SERVER;
+    if (resourceValue === undefined) {
+        const store = await CredentialStore.open(stateDir);
+        try {
+            resourceValue = await store.exclusive(() => store.readSelectedResource());
+        }
+        finally {
+            store.close();
+        }
+    }
+    if (resourceValue === undefined)
+        throw new UsageError('No server is saved. Run artifacts login --server RESOURCE or set ARTIFACTS_SERVER.');
+    const resource = canonicalResource(resourceValue);
     function argument(required = true) {
         if (arguments_.length > 1 || (required && arguments_.length !== 1))
             throw new UsageError(`${command} requires ${required ? 'one' : 'zero or one'} positional argument`);
@@ -142,9 +206,17 @@ async function main() {
             throw new UsageError(`--${name} requires a nonnegative safe integer`);
         return Number(value);
     }
+    function cleared(name, value, clear) {
+        if (value !== undefined && clear)
+            throw new UsageError(`Specify at most one of --${name} or --no-${name}`);
+        return clear ? null : value;
+    }
     const response = values.response;
     if (response !== undefined && response !== 'full' && response !== 'compact')
         throw new UsageError('--response requires full or compact');
+    const quiet = values.quiet ?? false;
+    if (quiet)
+        required('out');
     let commandToken;
     const client = createArtifactHttpClient({ resource, accessToken: () => commandToken ??= accessToken({ resource, stateDir }) });
     async function mutate(mutation) {
@@ -171,7 +243,12 @@ async function main() {
     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`); } });
+            {
+                const result = await login({ resource, stateDir, noBrowser: values['no-browser'] ?? false, onAuthorizationUrl: (url) => { process.stderr.write(`Authorize this login in your browser:\n${url}\n`); } });
+                if (result.resource !== resource)
+                    process.stderr.write(`REST resource: ${result.resource}\nThis verified REST URL is saved for subsequent commands.\n`);
+                return result.identity;
+            }
         case 'logout':
             none();
             return logout({ resource, stateDir });
@@ -182,16 +259,25 @@ 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 }), ...(values.slug === undefined ? {} : { slug: values.slug }), ...(response === undefined ? {} : { response }) }) });
         }
         case 'list':
             none();
-            return client.list({ ...(values.limit === undefined ? {} : { limit: integer('limit') }), ...(values.cursor === undefined ? {} : { cursor: values.cursor }) });
+            return client.list({ ...(values.limit === undefined ? {} : { limit: integer('limit') }), ...(values.cursor === undefined ? {} : { cursor: values.cursor }), ...(values.project === undefined ? {} : { project: values.project }) });
+        case 'projects':
+            none();
+            return client.projects();
+        case 'search': return client.search({ query: argument(), ...(values.project === undefined ? {} : { project: values.project }), ...(values.limit === undefined ? {} : { limit: integer('limit') }), ...(values.cursor === undefined ? {} : { cursor: values.cursor }) });
         case 'read': {
-            const result = await client.read({ artifactId: argument(), ...(values.revision === undefined ? {} : { revisionId: values.revision }), ...(response === undefined ? {} : { response }) });
+            if (values.slug === undefined && values.project !== undefined)
+                throw new UsageError('read --project requires --slug');
+            if ((values.slug === undefined) !== (arguments_.length === 1) || arguments_.length > 1)
+                throw new UsageError('read requires exactly one of an artifact ID or --slug SLUG');
+            const target = values.slug === undefined ? { artifactId: arguments_[0] } : { slug: values.slug, ...(values.project === undefined ? {} : { project: values.project }) };
+            const result = await client.read({ ...target, ...(values.revision === undefined ? {} : { revisionId: values.revision }), ...(response === undefined ? {} : { response }) });
             if (values.out)
                 await writeOutput(values.out, `${JSON.stringify(result, null, 2)}\n`);
-            return result;
+            return quiet ? undefined : result;
         }
         case 'update': {
             if (values.command)
@@ -217,11 +303,26 @@ 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();
+            const project = cleared('project', values.project, values['no-project']);
+            const slug = cleared('slug', values.slug, values['no-slug']);
+            if (project === undefined && slug === undefined)
+                throw new UsageError('move requires --project NAME, --no-project, --slug SLUG, or --no-slug');
+            return mutate({ kind: 'move', command: moveSchema.parse({ artifactId, requestId: values['request-id'] ?? randomUUID(), ...(project === undefined ? {} : { project }), ...(slug === undefined ? {} : { slug }) }) });
+        }
+        case 'share': return mutate({ kind: 'share', command: shareSchema.parse({ artifactId: argument(), requestId: values['request-id'] ?? randomUUID(), email: required('email'), ...(values.notify === undefined ? {} : { notify: values.notify }) }) });
+        case 'shares': return client.listShares(listSharesSchema.parse({ artifactId: argument() }));
+        case 'unshare': {
+            if (arguments_.length !== 2)
+                throw new UsageError('unshare requires two positional arguments');
+            return mutate({ kind: 'unshare', command: unshareSchema.parse({ artifactId: arguments_[0], shareId: arguments_[1], requestId: values['request-id'] ?? randomUUID() }) });
+        }
         case 'retry': {
             const requestId = argument();
             const owner = await client.identity();
             const operation = await loadOperation(stateDir, requestId, resource, owner.userId);
-            process.stderr.write(`Replaying retained ${operation.kind} operation ${requestId}. 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, 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">;
@@ -16,6 +16,7 @@ export declare const operationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                     text: "text";
                     html: "html";
                     markdown: "markdown";
+                    design: "design";
                 }>;
                 text: z.ZodString;
             }, z.core.$strict>;
@@ -29,6 +30,8 @@ export declare const operationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                 data: z.ZodString;
             }, z.core.$strict>>;
         }, z.core.$strict>;
+        project: z.ZodOptional<z.ZodString>;
+        slug: z.ZodOptional<z.ZodString>;
         response: z.ZodOptional<z.ZodEnum<{
             full: "full";
             compact: "compact";
@@ -54,6 +57,7 @@ export declare const operationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                     text: "text";
                     html: "html";
                     markdown: "markdown";
+                    design: "design";
                 }>;
                 text: z.ZodString;
             }, z.core.$strict>;
@@ -86,6 +90,39 @@ 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.ZodOptional<z.ZodNullable<z.ZodString>>;
+        slug: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>;
+    version: z.ZodLiteral<1>;
+    resource: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    ownerId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"share">;
+    command: z.ZodObject<{
+        requestId: z.ZodString;
+        artifactId: z.ZodString;
+        email: z.ZodPipe<z.ZodString, z.ZodEmail>;
+        notify: z.ZodOptional<z.ZodBoolean>;
+        requireNew: z.ZodOptional<z.ZodLiteral<true>>;
+    }, z.core.$strict>;
+    version: z.ZodLiteral<1>;
+    resource: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    ownerId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"unshare">;
+    command: z.ZodObject<{
+        requestId: z.ZodString;
+        artifactId: z.ZodString;
+        shareId: z.ZodString;
+    }, z.core.$strict>;
+    version: z.ZodLiteral<1>;
+    resource: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    ownerId: z.ZodString;
 }, z.core.$strict>], "kind">;
 export type PreparedOperation = z.infer<typeof operationSchema>;
 export type Mutation = {
@@ -97,48 +134,41 @@ export type Mutation = {
 } | {
     kind: 'publish';
     command: z.input<typeof publishSchema>;
+} | {
+    kind: 'move';
+    command: z.input<typeof moveSchema>;
+} | {
+    kind: 'share';
+    command: z.input<typeof shareSchema>;
+} | {
+    kind: 'unshare';
+    command: z.input<typeof unshareSchema>;
 };
 export declare function operationPath(stateDir: string, resource: string, requestId: string): string;
 export declare function retainOperation(stateDir: string, resource: string, ownerId: string, mutation: Mutation): Promise<PreparedOperation>;
 export declare function loadOperation(stateDir: string, requestId: string, resource: string, ownerId: string): Promise<PreparedOperation>;
-export declare function submitOperation(client: ArtifactHttpClient, operation: PreparedOperation): Promise<{
+export declare function submitOperation(client: ArtifactHttpClient, operation: PreparedOperation): Promise<void> | Promise<{
+    shareId: string;
+    artifactId: string;
+    kind: "email";
+    value: string;
+    createdAt: string;
+    notification?: {
+        status: "requested";
+    } | {
+        status: "skipped";
+        reason: "disabled";
+    } | {
+        status: "skipped";
+        reason: "rate_limited";
+        retryAt: string;
+    } | undefined;
+}> | Promise<{
+    artifactId: string;
+    project: string | null;
+}> | Promise<{
     revisionId: string;
     version: number;
     url: string;
     artifactId: string;
-}> | 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, shareSchema, unshareSchema, updateSchema } from '@yargote/artifacts-contracts';
 import { canonicalResource } from '@yargote/artifacts-contracts/http';
 const binding = {
     version: z.literal(1),
@@ -14,6 +14,9 @@ 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 }),
+    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);
@@ -86,5 +89,10 @@ 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);
+        case 'share': return client.share(operation.command);
+        case 'unshare': return client.unshare(operation.command);
     }
+    const exhaustive = operation;
+    throw new Error(`Unsupported retained operation: ${exhaustive}`);
 }

package/src/skills.d.ts

@@ -0,0 +1,9 @@
+interface SkillsOptions {
+    full?: boolean;
+    all?: boolean;
+    agent?: string;
+    global?: boolean;
+    force?: boolean;
+}
+export declare function runSkillsCommand(positionals: string[], options: SkillsOptions, seen: ReadonlySet<string>): Promise<void>;
+export {};

package/src/skills.js

@@ -0,0 +1,181 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, readFile, readdir, rename, rm } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const catalogDirectory = resolve(fileURLToPath(new URL(import.meta.url.endsWith('.ts') ? '../../../skills/' : '../skills/', import.meta.url)));
+function parseCommand(positionals, options, seen) {
+    const [kind = 'list', ...arguments_] = positionals;
+    const allowed = { list: [], get: ['all', 'full'], path: [], install: ['agent', 'global', 'force'] };
+    if (!Object.hasOwn(allowed, kind))
+        throw new TypeError(`Unknown skills command ${kind}. Use artifacts --help for the reference.`);
+    for (const option of seen) {
+        if (!['server', 'state-dir', ...allowed[kind]].includes(option))
+            throw new TypeError(`Option --${option} is not supported by skills ${kind}`);
+    }
+    switch (kind) {
+        case 'list':
+            if (arguments_.length)
+                throw new TypeError('skills list does not accept positional arguments');
+            return { kind };
+        case 'get':
+            if (arguments_.length > 1 || (options.all ? arguments_.length !== 0 : arguments_.length !== 1))
+                throw new TypeError('skills get requires either one skill name or --all');
+            return { kind, selection: options.all ? { all: true } : { name: arguments_[0] }, full: options.full ?? false };
+        case 'path':
+            if (arguments_.length > 1)
+                throw new TypeError('skills path accepts zero or one skill name');
+            return { kind, name: arguments_[0] };
+        case 'install':
+            if (arguments_.length > 1)
+                throw new TypeError('skills install accepts zero or one skill name');
+            if (options.agent !== undefined && options.agent !== 'claude')
+                throw new TypeError('--agent requires claude. Omit --agent to install under .agents.');
+            return { kind, name: arguments_[0] ?? 'artifacts-cli', agent: options.agent === 'claude' ? 'claude' : 'agents', global: options.global ?? false, force: options.force ?? false };
+        default:
+            throw new TypeError(`Unknown skills command ${kind}`);
+    }
+}
+async function loadCatalog() {
+    const manifest = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+    const names = manifest.artifactsSkills;
+    if (!Array.isArray(names) || names.some((name) => typeof name !== 'string' || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) || new Set(names).size !== names.length)
+        throw new Error('Invalid bundled skills declaration');
+    return Promise.all(names.toSorted().map(async (name) => {
+        const directory = join(catalogDirectory, name);
+        const skillText = await readFile(join(directory, 'SKILL.md'));
+        const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(skillText.toString('utf8'))?.[1];
+        const declaredName = frontmatter && /^name: (.+)$/m.exec(frontmatter)?.[1];
+        const description = frontmatter && /^description: (.+)$/m.exec(frontmatter)?.[1];
+        if (declaredName !== name || !description)
+            throw new Error(`Invalid bundled skill frontmatter at ${join(directory, 'SKILL.md')}`);
+        return { name, description, directory, skillText };
+    }));
+}
+async function fullFiles(directory, prefix = '') {
+    const entries = await readdir(directory, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries.toSorted((a, b) => a.name.localeCompare(b.name, 'en'))) {
+        const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory())
+            files.push(...await fullFiles(join(directory, entry.name), relative));
+        else if (entry.isFile())
+            files.push(relative);
+        else
+            throw new Error(`Bundled skill contains a non-regular file at ${join(directory, entry.name)}`);
+    }
+    return files;
+}
+function isText(content) {
+    if (content.includes(0))
+        return false;
+    try {
+        new TextDecoder('utf-8', { fatal: true }).decode(content);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function labeledContent(skills, full) {
+    const chunks = [];
+    for (const skill of skills) {
+        const files = full ? ['SKILL.md', ...(await fullFiles(skill.directory)).filter((path) => path !== 'SKILL.md')] : ['SKILL.md'];
+        for (const path of files) {
+            const content = path === 'SKILL.md' ? skill.skillText : await readFile(join(skill.directory, path));
+            if (!isText(content)) {
+                chunks.push(Buffer.from(`=== ${skill.name}/${path} (binary, ${content.length} bytes) ===\n`));
+                continue;
+            }
+            chunks.push(Buffer.from(`=== ${skill.name}/${path} ===\n`), content);
+            if (content.at(-1) !== 10)
+                chunks.push(Buffer.from('\n'));
+        }
+    }
+    return Buffer.concat(chunks);
+}
+function discoveryText(skill) {
+    return `---\nname: ${skill.name}\ndescription: ${skill.description}\n---\n\nBefore using this skill, run \`artifacts skills get ${skill.name} --full\`.\nLoad and follow the complete instructions, references, and templates bundled with the installed CLI version.\nRelative paths refer to the bundled directory reported by \`artifacts skills path ${skill.name}\`.\n`;
+}
+async function installSkill(skill, command) {
+    const destination = resolve(command.global ? homedir() : process.cwd(), command.agent === 'claude' ? '.claude' : '.agents', 'skills', skill.name, 'SKILL.md');
+    const content = Buffer.from(discoveryText(skill));
+    await mkdir(dirname(destination), { recursive: true });
+    try {
+        const file = await open(destination, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o644);
+        try {
+            await file.writeFile(content);
+        }
+        finally {
+            await file.close();
+        }
+        return destination;
+    }
+    catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'EEXIST'))
+            throw error;
+    }
+    const existing = await lstat(destination);
+    if (!existing.isFile())
+        throw new TypeError(`Cannot install ${destination}. The destination must be a regular file, not a directory or symbolic link.`);
+    const file = await open(destination, constants.O_RDONLY | constants.O_NOFOLLOW);
+    let previous;
+    try {
+        if (!(await file.stat()).isFile())
+            throw new TypeError(`Cannot install ${destination}. The destination must be a regular file.`);
+        previous = await file.readFile();
+    }
+    finally {
+        await file.close();
+    }
+    if (previous.equals(content))
+        return destination;
+    if (!command.force)
+        throw new TypeError(`Cannot replace differing file ${destination}. Use --force to replace it.`);
+    const temporary = join(dirname(destination), `.SKILL.md.${randomUUID()}.tmp`);
+    try {
+        const replacement = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o644);
+        try {
+            await replacement.writeFile(content);
+        }
+        finally {
+            await replacement.close();
+        }
+        const current = await lstat(destination);
+        if (!current.isFile())
+            throw new TypeError(`Cannot install ${destination}. The destination must be a regular file, not a directory or symbolic link.`);
+        if (current.ino !== existing.ino || current.dev !== existing.dev || current.mtimeMs !== existing.mtimeMs || current.ctimeMs !== existing.ctimeMs)
+            throw new TypeError(`Cannot replace ${destination}. The destination changed during installation. Run the command again.`);
+        await rename(temporary, destination);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+    return destination;
+}
+export async function runSkillsCommand(positionals, options, seen) {
+    const command = parseCommand(positionals, options, seen);
+    const skills = await loadCatalog();
+    function named(name) {
+        const skill = skills.find((entry) => entry.name === name);
+        if (!skill)
+            throw new TypeError(`Unknown bundled skill ${name}. Use artifacts skills list to inspect available skills.`);
+        return skill;
+    }
+    switch (command.kind) {
+        case 'list':
+            process.stdout.write(skills.map((skill) => `${skill.name}\t${skill.description}\n`).join(''));
+            return;
+        case 'get': {
+            const selection = 'all' in command.selection ? skills : [named(command.selection.name)];
+            process.stdout.write(!command.full && 'name' in command.selection ? selection[0].skillText : await labeledContent(selection, command.full));
+            return;
+        }
+        case 'path':
+            process.stdout.write(`${command.name === undefined ? catalogDirectory : named(command.name).directory}\n`);
+            return;
+        case 'install':
+            process.stdout.write(`${await installSkill(named(command.name), command)}\n`);
+    }
+}