@quadient/skillshare 1.0.0 → 1.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 Development CLI for the Skillshare registry.
 
-Examples:
+## Examples
 
 ```bash
 bun run index.ts
@@ -11,29 +11,151 @@ bun run index.ts login local
 bun run index.ts list
 bun run index.ts install
 bun run index.ts install "Prompt Lint"
+bun run index.ts update
+bun run index.ts update "Prompt Lint" --dry-run
+bun run index.ts update 12 --target ./installed
 bun run index.ts upload ./examples/prompt-lint --version 0.1.0
 bun run index.ts install 12 0.1.0 --target ./installed
 bun run index.ts install --skill-version-id 42 --target ./installed
 ```
 
-Interactive behavior:
+## Behavior
 
-- If the current directory already contains SKILL.md, the TUI offers to upload it before showing the main action picker.
-- `install` opens the guided installer. When you pass `<skillId|skillName>`, the installer opens with that skill already selected; adding `[version]` skips the version picker too.
-- After install or upload, the CLI writes skillshare.metadata.json into the skill directory with the skill id, name, description, and installed or published version.
-- When skillshare.metadata.json already exists, uploads publish a new version of that skill instead of creating a duplicate entry.
-- New skill creation derives name and description from SKILL.md frontmatter when available, so the user usually only needs to enter the initial version.
 - Upload and publish commands show progress while scanning and reading local files, then keep a timed upload status visible until the registry call finishes.
+- `update` reads the centralized install registry and refreshes recorded installs to the latest published registry versions.
+- `update` can be narrowed to one skill or one target directory, and `--dry-run` prints planned changes without downloading or overwriting files.
+- Interactive mode now checks for recorded installs with newer published versions and offers updating them before showing the main action menu.
+
+## Current TUI Flow
+
+```mermaid
+flowchart TD
+  A[Start: skillshare] --> B{Command provided?}
+
+  B -- No --> C[runInteractive]
+  B -- Yes --> D{Which command?}
+
+  D -->|login local| E[login LOCAL_URL]
+  D -->|login| F[login PROD_URL]
+  D -->|logout| G[logoutSession]
+  D -->|whoami list show upload install update| H[createClient using active baseUrl]
+
+  C --> I[resolveActiveBaseUrl]
+  I --> J[ensureInteractiveLogin]
+  J --> K{Stored session exists?}
+  K -- No --> F
+  K -- Yes --> L{Refresh token still valid?}
+  L -- No --> F
+  L -- Yes --> M[createClient and GET /api/auth/me]
+  M --> N{Session still accepted?}
+  N -- No --> F
+  N -- Yes --> O[Interactive menu ready]
+
+  E --> P[Start PKCE and callback server]
+  F --> P
+  P --> Q[Open browser to /api/cli/login]
+  Q --> R[Wait for local callback with code and state]
+  R --> S[POST /api/cli/token]
+  S --> T[Store session.json]
+  T --> O
+
+  O --> U{Current directory contains SKILL.md?}
+  U -- Yes --> V{Upload current directory now?}
+  V -- Yes --> W[runInteractiveUpload]
+  V -- No --> X[Choose action]
+  U -- No --> X
+
+  X --> Y{Install, Update or Upload?}
+  Y -->|Install| Z[runInteractiveInstall]
+  Y -->|Update| U0[updateInstalledSkills]
+  Y -->|Upload| W
+
+  Z --> Z1[GET /api/skills]
+  Z1 --> Z2[Choose skill or resolve skillRef]
+  Z2 --> Z3[GET skill detail]
+  Z3 --> Z4[Choose version or use provided version]
+  Z4 --> Z5[Choose project/global scope]
+  Z5 --> Z6[Choose agents]
+  Z6 --> Z7[GET version detail]
+  Z7 --> Z8[POST download audit]
+  Z8 --> Z9[Write files to install targets]
+  Z9 --> Z10[Update installed.json]
+  Z10 --> END[Done]
+
+  U0 --> U1[Read installed.json for active baseUrl]
+  U1 --> U2[GET skill detail for each installed target]
+  U2 --> U3{Latest differs from installed version?}
+  U3 -- No --> U4[Skip target]
+  U3 -- Yes --> U5[GET latest version detail]
+  U5 --> U6[POST download audit]
+  U6 --> U7[Overwrite target files]
+  U7 --> U8[Update installed.json]
+  U4 --> END
+  U8 --> END
+
+  W --> W1[Load local skill context]
+  W1 --> W2{uploaded.json has skillId for this directory?}
+
+  W2 -- No --> W3[Prompt initial version]
+  W3 --> W4[createSkillFromDirectory]
+  W4 --> W5[POST create skill]
+  W5 --> W6[GET created skill detail]
+  W6 --> W7[Update uploaded.json]
+  W7 --> END
+
+  W2 -- Yes --> W8[GET existing skill detail]
+  W8 --> W9{Local version differs from latest?}
+  W9 -- Yes --> W10{Download latest first?}
+  W10 -- Yes --> W11[GET latest version detail]
+  W11 --> W12[POST download audit]
+  W12 --> W13[Overwrite local files and update installed.json]
+  W13 --> END
+
+  W10 -- No --> W14[Prompt new version]
+  W9 -- No --> W14
+  W14 --> W15[publishSkillFromDirectory]
+  W15 --> W16[POST publish version]
+  W16 --> W17[GET updated skill detail]
+  W17 --> W18[Update uploaded.json]
+  W18 --> END
+```
 
-Login opens a browser against the selected Skillshare host, exchanges the backend login code for CLI tokens, and stores the access token plus refresh token in the user config directory.
-
-Without an existing session, the CLI now defaults to the production registry. Use `login local` only when you want the local backend.
+## State Storage
 
 Session storage paths:
 
 - macOS/Linux: `~/.config/skillshare/session.json`
 - Windows: `%APPDATA%\\skillshare\\session.json`
 
+Centralized TUI state:
+
+- `uploaded.json` sits next to `session.json` and stores uploaded skill directories plus the registry skill/version they map to.
+- `installed.json` sits next to `session.json` and stores installed target directories plus the installed skill/version for each target.
+- New installs and uploads no longer need to create `skillshare.metadata.json` in the target directories.
+
+## Authentication
+
+Bearer token precedence:
+
+- `--token <token>` has the highest priority.
+- `SKILLSHARE_TOKEN` is used when `--token` is not provided.
+- Stored interactive session is used only when neither explicit token source is present.
+
+Example non-interactive usage with a personal access token:
+
+```bash
+export SKILLSHARE_TOKEN="<personal-access-token>"
+npx @quadient/skillshare whoami
+```
+
+Update recorded installs to the latest versions:
+
+```bash
+npx @quadient/skillshare update
+npx @quadient/skillshare update "Prompt Lint" --dry-run
+npx @quadient/skillshare update 12 --target ./installed
+```
+
 ## Package Distribution
 
 The CLI is prepared for publishing as `@quadient/skillshare`.

package/dist/index.js

@@ -2,7 +2,7 @@ import { createServer } from 'node:http';
 import { createHash, randomBytes } from 'node:crypto';
 import { spawn } from 'node:child_process';
 import { existsSync } from 'node:fs';
-import { mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
+import { mkdir, open, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
 import { basename, dirname, join, relative, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { cancel, confirm, intro, isCancel, multiselect, outro, progress, select, spinner, text } from '@clack/prompts';
@@ -10,6 +10,8 @@ const PROD_URL = 'https://skillshare.inspireclouduat.net';
 const LOCAL_URL = 'http://localhost:5050';
 const APP_DIR = getAppDir();
 const SESSION_PATH = join(APP_DIR, 'session.json');
+const UPLOADED_STATE_PATH = join(APP_DIR, 'uploaded.json');
+const INSTALLED_STATE_PATH = join(APP_DIR, 'installed.json');
 const SKILL_FILE_NAME = 'SKILL.md';
 const SKILL_METADATA_FILE_NAME = 'skillshare.metadata.json';
 const UNIVERSAL_PROJECT_SKILLS_PATH = '.agents/skills';
@@ -75,9 +77,10 @@ Commands:
   install <skillId|skillName> [version]
   install <skillId|skillName> [version] --target <directory>
   install --skill-version-id <id> --target <directory>
+  update [skillId|skillName] [--target <directory>] [--dry-run]
 
 Options:
-  --token <token>    Bearer token for API requests
+  --token <token>    Bearer token for API requests (overrides SKILLSHARE_TOKEN)
 `;
 async function main() {
     const args = process.argv.slice(2);
@@ -104,8 +107,10 @@ async function main() {
         case 'list':
         case 'show':
         case 'upload':
-        case 'install': {
-            const client = await createClient(await resolveActiveBaseUrl(), options.token);
+        case 'install':
+        case 'update': {
+            const activeBaseUrl = await resolveActiveBaseUrl();
+            const client = await createClient(activeBaseUrl, options.token);
             switch (command) {
                 case 'whoami': {
                     const user = await client.get('/api/auth/me');
@@ -139,10 +144,10 @@ async function main() {
                         throw new Error('upload requires <directory> --version <version>');
                     }
                     const localSkill = await loadLocalSkillContext(directory);
-                    const skillId = options.flags['skill-id']
-                        ? parsePositiveInteger(options.flags['skill-id'], '--skill-id')
-                        : localSkill.metadata?.skillId;
-                    if (!skillId) {
+                    const existingSkill = await resolveExistingUploadSkill(client, localSkill, {
+                        explicitSkillId: options.flags['skill-id'],
+                    });
+                    if (!existingSkill) {
                         const created = await createSkillFromDirectory(client, localSkill, {
                             name: options.flags.name,
                             description: options.flags.description,
@@ -152,9 +157,8 @@ async function main() {
                     }
                     else {
                         const published = await publishSkillFromDirectory(client, localSkill, {
-                            skillId,
+                            skillId: existingSkill.id,
                             version,
-                            failIfMissing: false,
                         });
                         console.log(JSON.stringify(published.response, null, 2));
                     }
@@ -176,14 +180,27 @@ async function main() {
                         const detail = await client.get(`/api/skill-versions/${parsedSkillVersionId}`);
                         const skill = await client.get(`/api/skills/${detail.skillId}`);
                         await client.post(`/api/skills/${detail.skillId}/versions/${detail.version}/downloads`);
-                        await writeSkillVersionToDirectory(client, {
-                            skillId: detail.skillId,
+                        const installProgress = createInstallProgressReporter({
                             skillName: skill.name,
-                            skillDescription: skill.description,
                             version: detail.version,
-                            files: detail.files,
-                            targetRoot: target,
+                            totalTargets: 1,
+                            ...calculateInstallTotals(detail.files, 1),
                         });
+                        try {
+                            await writeSkillVersionToDirectory(client, {
+                                skillId: detail.skillId,
+                                skillName: skill.name,
+                                skillDescription: skill.description,
+                                version: detail.version,
+                                files: detail.files,
+                                targetRoot: target,
+                            }, installProgress);
+                            installProgress.stop();
+                        }
+                        catch (error) {
+                            installProgress.clear();
+                            throw error;
+                        }
                         console.log(`Installed skillVersion ${parsedSkillVersionId} (${detail.skillId}@${detail.version}) to ${target}`);
                         return;
                     }
@@ -205,17 +222,38 @@ async function main() {
                     }
                     const detail = await client.get(`/api/skills/${skill.id}/versions/${effectiveVersion}`);
                     await client.post(`/api/skills/${skill.id}/versions/${effectiveVersion}/downloads`);
-                    await writeSkillVersionToDirectory(client, {
-                        skillId: skill.id,
+                    const installProgress = createInstallProgressReporter({
                         skillName: skill.name,
-                        skillDescription: skill.description,
                         version: effectiveVersion,
-                        files: detail.files,
-                        targetRoot: target,
+                        totalTargets: 1,
+                        ...calculateInstallTotals(detail.files, 1),
                     });
+                    try {
+                        await writeSkillVersionToDirectory(client, {
+                            skillId: skill.id,
+                            skillName: skill.name,
+                            skillDescription: skill.description,
+                            version: effectiveVersion,
+                            files: detail.files,
+                            targetRoot: target,
+                        }, installProgress);
+                        installProgress.stop();
+                    }
+                    catch (error) {
+                        installProgress.clear();
+                        throw error;
+                    }
                     console.log(`Installed ${skill.name}@${effectiveVersion} to ${target}`);
                     return;
                 }
+                case 'update': {
+                    await updateInstalledSkills(client, {
+                        skillRef: options.positionals[0],
+                        target: options.flags.target,
+                        dryRun: isFlagEnabled(options.flags, 'dry-run'),
+                    });
+                    return;
+                }
             }
             return;
         }
@@ -228,8 +266,19 @@ async function runInteractive() {
     const baseUrl = await resolveActiveBaseUrl();
     await ensureInteractiveLogin(baseUrl);
     const client = await createClient(baseUrl);
+    const pendingInstalledUpdates = await collectInstalledSkillUpdateCandidates(client);
+    if (pendingInstalledUpdates.length > 0) {
+        const shouldUpdateInstalled = await promptConfirm(pendingInstalledUpdates.length === 1
+            ? `There is 1 installed skill with a newer version available. Update it now?`
+            : `There are ${pendingInstalledUpdates.length} installed skills with newer versions available. Update all of them now?`, true);
+        if (shouldUpdateInstalled) {
+            await updateInstalledSkills(client, { candidates: pendingInstalledUpdates });
+            outro('Done.');
+            return;
+        }
+    }
     if (existsSync(join(process.cwd(), SKILL_FILE_NAME))) {
-        const localMetadata = await readLocalSkillMetadata(process.cwd());
+        const localMetadata = await readLocalSkillMetadata(process.cwd(), client.baseUrl);
         const shouldUploadCurrent = await promptConfirm(localMetadata
             ? `Current directory contains ${SKILL_FILE_NAME}. Upload a new version of ${localMetadata.skillName || `skill ${localMetadata.skillId}`} now?`
             : `Current directory contains ${SKILL_FILE_NAME}. Upload it now?`, true);
@@ -243,6 +292,7 @@ async function runInteractive() {
         message: 'What do you want to do?',
         options: [
             { value: 'install', label: 'Install a skill', hint: 'Browse registry and install to agents' },
+            { value: 'update', label: 'Update installed skills', hint: 'Refresh recorded installs to the latest registry versions' },
             { value: 'upload', label: 'Upload a skill', hint: 'Create a new skill or publish a version' },
         ],
     });
@@ -253,6 +303,9 @@ async function runInteractive() {
     if (action === 'install') {
         await runInteractiveInstall(client);
     }
+    else if (action === 'update') {
+        await updateInstalledSkills(client);
+    }
     else {
         await runInteractiveUpload(client);
     }
@@ -297,44 +350,71 @@ async function runInteractiveInstall(client, options) {
     await client.post(`/api/skills/${skill.id}/versions/${selectedVersion}/downloads`);
     const installName = createInstalledSkillDirectoryName(skill);
     const installTargets = resolveInstallTargets(selectedAgents, scope, installName);
-    for (const installTarget of installTargets) {
-        await writeSkillVersionToDirectory(client, {
-            skillId: skill.id,
-            skillName: skill.name,
-            skillDescription: skill.description,
-            version: selectedVersion,
-            files: versionDetail.files,
-            targetRoot: installTarget.targetRoot,
-        });
+    const installProgress = createInstallProgressReporter({
+        skillName: skill.name,
+        version: selectedVersion,
+        totalTargets: installTargets.length,
+        ...calculateInstallTotals(versionDetail.files, installTargets.length),
+    });
+    try {
+        for (const installTarget of installTargets) {
+            await writeSkillVersionToDirectory(client, {
+                skillId: skill.id,
+                skillName: skill.name,
+                skillDescription: skill.description,
+                version: selectedVersion,
+                files: versionDetail.files,
+                targetRoot: installTarget.targetRoot,
+            }, installProgress);
+        }
+        installProgress.stop();
+    }
+    catch (error) {
+        installProgress.clear();
+        throw error;
     }
     console.log(`Installed ${skill.name}@${selectedVersion} to ${installTargets.length} location(s) for ${selectedAgents.length} agent(s) in ${scope} scope.`);
 }
 async function runInteractiveUpload(client, initialDirectory) {
     const directory = initialDirectory
         ?? await promptText('Skill directory', '.', `Enter the directory containing ${SKILL_FILE_NAME}`);
-    const localSkill = await loadLocalSkillContext(directory);
-    if (!localSkill.metadata?.skillId) {
+    const localSkill = await loadLocalSkillContext(directory, client.baseUrl);
+    const existingSkill = await resolveExistingUploadSkill(client, localSkill);
+    if (!existingSkill) {
         const version = await promptText('Initial version', '0.1.0');
         const created = await createSkillFromDirectory(client, localSkill, { version });
         console.log(`Created skill ${created.detail.id}: ${created.detail.name}@${version}`);
         return;
     }
-    const skill = await client.get(`/api/skills/${localSkill.metadata.skillId}`);
-    const localVersion = normalizeText(localSkill.metadata.skillVersion);
+    const skill = await client.get(`/api/skills/${existingSkill.id}`);
+    const localVersion = normalizeText(localSkill.metadata?.skillVersion);
     const latestVersion = normalizeText(skill.latestVersion);
     if (latestVersion && localVersion && latestVersion !== localVersion) {
         const shouldDownloadLatest = await promptConfirm(`Local version is ${localVersion}, but the server latest is ${latestVersion}. Download it first? Local file changes will be overwritten.`, false);
         if (shouldDownloadLatest) {
             const latestDetail = await client.get(`/api/skills/${skill.id}/versions/${latestVersion}`);
             await client.post(`/api/skills/${skill.id}/versions/${latestVersion}/downloads`);
-            await writeSkillVersionToDirectory(client, {
-                skillId: skill.id,
+            const installProgress = createInstallProgressReporter({
                 skillName: skill.name,
-                skillDescription: skill.description,
                 version: latestVersion,
-                files: latestDetail.files,
-                targetRoot: localSkill.directory,
+                totalTargets: 1,
+                ...calculateInstallTotals(latestDetail.files, 1),
             });
+            try {
+                await writeSkillVersionToDirectory(client, {
+                    skillId: skill.id,
+                    skillName: skill.name,
+                    skillDescription: skill.description,
+                    version: latestVersion,
+                    files: latestDetail.files,
+                    targetRoot: localSkill.directory,
+                }, installProgress);
+                installProgress.stop();
+            }
+            catch (error) {
+                installProgress.clear();
+                throw error;
+            }
             console.log(`Downloaded ${skill.name}@${latestVersion} to ${localSkill.directory}`);
             return;
         }
@@ -343,10 +423,132 @@ async function runInteractiveUpload(client, initialDirectory) {
     const published = await publishSkillFromDirectory(client, localSkill, {
         skillId: skill.id,
         version,
-        failIfMissing: true,
     });
     console.log(`Published ${published.detail.name}@${published.response.version}`);
 }
+async function updateInstalledSkills(client, options) {
+    const skillRef = normalizeText(options?.skillRef);
+    const targetFilter = normalizeText(options?.target);
+    const normalizedTargetFilter = targetFilter ? resolve(targetFilter) : null;
+    const dryRun = options?.dryRun ?? false;
+    let installedRecords = (await readInstalledSkillRecords())
+        .filter((record) => record.baseUrl === client.baseUrl);
+    if (skillRef) {
+        const normalizedSkillRef = skillRef.toLowerCase();
+        installedRecords = installedRecords.filter((record) => ((record.skillId != null && String(record.skillId) === normalizedSkillRef) ||
+            normalizeText(record.skillName)?.toLowerCase() === normalizedSkillRef ||
+            createNormalizedSkillDirectoryName(record.skillName) === normalizedSkillRef));
+    }
+    if (normalizedTargetFilter) {
+        installedRecords = installedRecords.filter((record) => resolve(record.targetRoot) === normalizedTargetFilter);
+    }
+    if (installedRecords.length === 0) {
+        const selectionDescription = formatUpdateSelectionDescription({
+            skillRef: skillRef ?? undefined,
+            target: targetFilter ?? undefined,
+            dryRun,
+        });
+        console.log(`No installed skills recorded for ${client.baseUrl}${selectionDescription}.`);
+        return;
+    }
+    const candidates = options?.candidates
+        ?? await collectInstalledSkillUpdateCandidates(client, {
+            records: installedRecords,
+            onSkipped(message) {
+                console.log(message);
+            },
+        });
+    const skippedCount = installedRecords.length - candidates.length;
+    if (candidates.length === 0) {
+        if (dryRun) {
+            console.log(`Dry run finished. Would update 0, skipped ${skippedCount}.`);
+        }
+        else {
+            console.log(`Update finished. Updated 0, skipped ${skippedCount}.`);
+        }
+        return;
+    }
+    let updatedCount = 0;
+    let plannedCount = 0;
+    for (const candidate of candidates) {
+        const { record, detail, latestVersion } = candidate;
+        if (dryRun) {
+            plannedCount += 1;
+            console.log(`Would update ${detail.name} from ${record.skillVersion} to ${latestVersion} in ${record.targetRoot}`);
+            continue;
+        }
+        const versionDetail = await client.get(`/api/skills/${record.skillId}/versions/${latestVersion}`);
+        await client.post(`/api/skills/${record.skillId}/versions/${latestVersion}/downloads`);
+        const installProgress = createInstallProgressReporter({
+            skillName: detail.name,
+            version: latestVersion,
+            totalTargets: 1,
+            ...calculateInstallTotals(versionDetail.files, 1),
+        });
+        try {
+            await writeSkillVersionToDirectory(client, {
+                skillId: detail.id,
+                skillName: detail.name,
+                skillDescription: detail.description,
+                version: latestVersion,
+                files: versionDetail.files,
+                targetRoot: record.targetRoot,
+            }, installProgress);
+            installProgress.stop();
+        }
+        catch (error) {
+            installProgress.clear();
+            throw error;
+        }
+        updatedCount += 1;
+        console.log(`Updated ${detail.name} from ${record.skillVersion} to ${latestVersion} in ${record.targetRoot}`);
+    }
+    if (dryRun) {
+        console.log(`Dry run finished. Would update ${plannedCount}, skipped ${skippedCount}.`);
+        return;
+    }
+    console.log(`Update finished. Updated ${updatedCount}, skipped ${skippedCount}.`);
+}
+async function collectInstalledSkillUpdateCandidates(client, options) {
+    const records = options?.records
+        ?? (await readInstalledSkillRecords()).filter((record) => record.baseUrl === client.baseUrl);
+    const candidates = [];
+    for (const record of records) {
+        if (record.skillId == null) {
+            options?.onSkipped?.(`Skipping ${record.skillName}: installed record in ${record.targetRoot} does not contain a skill id.`);
+            continue;
+        }
+        const detail = await client.get(`/api/skills/${record.skillId}`);
+        const latestVersion = normalizeText(detail.latestVersion);
+        if (!latestVersion) {
+            options?.onSkipped?.(`Skipping ${record.skillName}: no latest version is published.`);
+            continue;
+        }
+        if (latestVersion === normalizeText(record.skillVersion)) {
+            options?.onSkipped?.(`Skipping ${record.skillName}: ${latestVersion} is already installed in ${record.targetRoot}.`);
+            continue;
+        }
+        candidates.push({
+            record,
+            detail,
+            latestVersion,
+        });
+    }
+    return candidates;
+}
+function formatUpdateSelectionDescription(options) {
+    const parts = [];
+    if (options.skillRef) {
+        parts.push(`skill '${options.skillRef}'`);
+    }
+    if (options.target) {
+        parts.push(`target '${options.target}'`);
+    }
+    if (parts.length === 0) {
+        return '';
+    }
+    return ` matching ${parts.join(' and ')}`;
+}
 async function promptForSkill(skills) {
     let query = '';
     while (true) {
@@ -494,7 +696,7 @@ async function promptConfirm(message, initialValue = false) {
     }
     return value;
 }
-async function loadLocalSkillContext(directory) {
+async function loadLocalSkillContext(directory, baseUrl) {
     const resolvedDirectory = resolve(directory);
     const scanStatus = spinner({ indicator: 'timer' });
     scanStatus.start(`Scanning ${resolvedDirectory}`);
@@ -530,7 +732,7 @@ async function loadLocalSkillContext(directory) {
         directory: resolvedDirectory,
         files,
         totalBytes,
-        metadata: await readLocalSkillMetadata(resolvedDirectory),
+        metadata: await readLocalSkillMetadata(resolvedDirectory, baseUrl),
         defaults: deriveSkillDefaults(files, resolvedDirectory),
     };
 }
@@ -548,7 +750,7 @@ async function createSkillFromDirectory(client, localSkill, input) {
         });
         uploadStatus.message(`Fetching saved metadata for skill ${response.id}`);
         const detail = await client.get(`/api/skills/${response.id}`);
-        await writeLocalSkillMetadata(localSkill.directory, createLocalSkillMetadata(detail, detail.latestVersion ?? input.version));
+        await upsertUploadedSkillMetadata(client.baseUrl, localSkill.directory, createLocalSkillMetadata(detail, detail.latestVersion ?? input.version));
         uploadStatus.stop(`Uploaded ${localSkill.files.length} file${localSkill.files.length === 1 ? '' : 's'} (${formatByteSize(localSkill.totalBytes)})`);
         return { response, detail };
     }
@@ -558,9 +760,6 @@ async function createSkillFromDirectory(client, localSkill, input) {
     }
 }
 async function publishSkillFromDirectory(client, localSkill, input) {
-    if (input.failIfMissing && !localSkill.metadata?.skillId) {
-        throw new Error(`Missing ${SKILL_METADATA_FILE_NAME}. Create the skill first or restore the metadata file.`);
-    }
     const uploadStatus = spinner({ indicator: 'timer' });
     uploadStatus.start(`Uploading ${localSkill.files.length} file${localSkill.files.length === 1 ? '' : 's'} (${formatByteSize(localSkill.totalBytes)})`);
     try {
@@ -571,7 +770,7 @@ async function publishSkillFromDirectory(client, localSkill, input) {
         });
         uploadStatus.message(`Fetching saved metadata for skill ${input.skillId}`);
         const detail = await client.get(`/api/skills/${input.skillId}`);
-        await writeLocalSkillMetadata(localSkill.directory, createLocalSkillMetadata(detail, response.version));
+        await upsertUploadedSkillMetadata(client.baseUrl, localSkill.directory, createLocalSkillMetadata(detail, response.version));
         uploadStatus.stop(`Uploaded ${localSkill.files.length} file${localSkill.files.length === 1 ? '' : 's'} (${formatByteSize(localSkill.totalBytes)})`);
         return { response, detail };
     }
@@ -580,19 +779,178 @@ async function publishSkillFromDirectory(client, localSkill, input) {
         throw error;
     }
 }
-async function writeSkillVersionToDirectory(client, input) {
+async function writeSkillVersionToDirectory(client, input, installProgress) {
+    installProgress?.onTargetStart(input.targetRoot);
     for (const file of input.files) {
+        installProgress?.onFileStart(input.targetRoot, file.nameWithPath, file.length);
         const response = await client.rawGet(`/api/skills/${input.skillId}/versions/${input.version}/files/${file.nameWithPath}`);
         const destination = join(input.targetRoot, file.nameWithPath);
         await mkdir(dirname(destination), { recursive: true });
-        await writeFile(destination, Buffer.from(await response.arrayBuffer()));
+        await downloadResponseToFile(response, destination, (bytes) => {
+            installProgress?.onBytesTransferred(bytes);
+        });
+        installProgress?.onFileComplete();
     }
-    await writeLocalSkillMetadata(input.targetRoot, {
+    await upsertInstalledSkillRecord(client.baseUrl, input.targetRoot, {
         skillId: input.skillId,
         skillName: input.skillName,
         skillDescription: input.skillDescription,
         skillVersion: input.version,
     });
+    installProgress?.onTargetComplete();
+}
+async function downloadResponseToFile(response, destination, onBytesTransferred) {
+    const body = response.body;
+    if (!body) {
+        const buffer = Buffer.from(await response.arrayBuffer());
+        await writeFile(destination, buffer);
+        onBytesTransferred?.(buffer.length);
+        return;
+    }
+    const fileHandle = await open(destination, 'w');
+    let failed = true;
+    try {
+        const reader = body.getReader();
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) {
+                failed = false;
+                break;
+            }
+            if (!value || value.length === 0) {
+                continue;
+            }
+            await fileHandle.writeFile(value);
+            onBytesTransferred?.(value.length);
+        }
+    }
+    finally {
+        await fileHandle.close();
+        if (failed) {
+            await rm(destination, { force: true });
+        }
+    }
+}
+function createInstallProgressReporter(input) {
+    const installStatus = spinner({ indicator: 'timer' });
+    const state = {
+        completedFiles: 0,
+        completedTargets: 0,
+        currentFileBytes: 0,
+        currentFileExpectedBytes: 0,
+        currentFilePath: null,
+        currentTargetRoot: null,
+        transferredBytes: 0,
+    };
+    let lastRenderAt = 0;
+    let lastRenderedBytes = 0;
+    installStatus.start(formatInstallProgressMessage(input, state));
+    function render(force = false) {
+        const now = Date.now();
+        const bytesDelta = state.transferredBytes - lastRenderedBytes;
+        if (!force && now - lastRenderAt < 100 && bytesDelta < 64 * 1024) {
+            return;
+        }
+        installStatus.message(formatInstallProgressMessage(input, state));
+        lastRenderAt = now;
+        lastRenderedBytes = state.transferredBytes;
+    }
+    return {
+        onTargetStart(targetRoot) {
+            state.currentTargetRoot = targetRoot;
+            render(true);
+        },
+        onFileStart(targetRoot, relativePath, expectedBytes) {
+            state.currentTargetRoot = targetRoot;
+            state.currentFilePath = relativePath;
+            state.currentFileExpectedBytes = Math.max(expectedBytes, 0);
+            state.currentFileBytes = 0;
+            render(true);
+        },
+        onBytesTransferred(bytes) {
+            state.transferredBytes += bytes;
+            state.currentFileBytes += bytes;
+            render();
+        },
+        onFileComplete() {
+            state.completedFiles += 1;
+            if (state.currentFileExpectedBytes > 0) {
+                state.currentFileBytes = state.currentFileExpectedBytes;
+            }
+            render(true);
+        },
+        onTargetComplete() {
+            state.completedTargets += 1;
+            render(true);
+        },
+        stop() {
+            installStatus.stop(formatInstallCompletedMessage(input, state));
+        },
+        clear() {
+            installStatus.clear();
+        },
+    };
+}
+function calculateInstallTotals(files, targetCount) {
+    const totalFiles = files.length * targetCount;
+    const totalBytes = files.reduce((sum, file) => sum + Math.max(file.length, 0), 0) * targetCount;
+    return { totalFiles, totalBytes };
+}
+function formatInstallProgressMessage(input, state) {
+    const parts = [
+        `Installing ${input.skillName}@${input.version}`,
+        `files ${state.completedFiles}/${input.totalFiles}`,
+        input.totalBytes > 0
+            ? `bytes ${formatByteSize(Math.min(state.transferredBytes, input.totalBytes))}/${formatByteSize(input.totalBytes)}`
+            : `bytes ${formatByteSize(state.transferredBytes)}`,
+    ];
+    if (input.totalTargets > 1) {
+        parts.push(`targets ${state.completedTargets}/${input.totalTargets}`);
+    }
+    if (state.currentTargetRoot) {
+        parts.push(`target ${formatInstallTargetRoot(state.currentTargetRoot)}`);
+    }
+    if (state.currentFilePath) {
+        const fileProgress = state.currentFileExpectedBytes > 0
+            ? ` (${formatByteSize(Math.min(state.currentFileBytes, state.currentFileExpectedBytes))}/${formatByteSize(state.currentFileExpectedBytes)})`
+            : state.currentFileBytes > 0
+                ? ` (${formatByteSize(state.currentFileBytes)})`
+                : '';
+        parts.push(`${state.currentFilePath}${fileProgress}`);
+    }
+    return parts.join(' · ');
+}
+function formatInstallCompletedMessage(input, state) {
+    const parts = [
+        `Installed ${input.skillName}@${input.version}`,
+        `files ${state.completedFiles}/${input.totalFiles}`,
+        input.totalBytes > 0
+            ? `bytes ${formatByteSize(Math.min(state.transferredBytes, input.totalBytes))}/${formatByteSize(input.totalBytes)}`
+            : `bytes ${formatByteSize(state.transferredBytes)}`,
+    ];
+    if (input.totalTargets > 1) {
+        parts.push(`targets ${state.completedTargets}/${input.totalTargets}`);
+    }
+    return parts.join(' · ');
+}
+function formatInstallTargetRoot(targetRoot) {
+    const cwd = process.cwd();
+    if (targetRoot === cwd) {
+        return '.';
+    }
+    const relativeToCwd = relative(cwd, targetRoot);
+    if (relativeToCwd && relativeToCwd !== '' && !relativeToCwd.startsWith('..')) {
+        return relativeToCwd.startsWith('.') ? relativeToCwd : `./${relativeToCwd}`;
+    }
+    const home = homedir();
+    if (targetRoot === home) {
+        return '~';
+    }
+    const relativeToHome = relative(home, targetRoot);
+    if (relativeToHome && relativeToHome !== '' && !relativeToHome.startsWith('..')) {
+        return `~/${relativeToHome}`;
+    }
+    return targetRoot;
 }
 function deriveSkillDefaults(files, directory) {
     const skillFile = files.find((file) => file.relativePath === SKILL_FILE_NAME);
@@ -737,6 +1095,61 @@ function normalizeText(value) {
     const trimmed = value?.trim();
     return trimmed ? trimmed : null;
 }
+async function resolveExistingUploadSkill(client, localSkill, options) {
+    const explicitSkillId = normalizeText(options?.explicitSkillId);
+    if (explicitSkillId) {
+        return {
+            id: parsePositiveInteger(explicitSkillId, '--skill-id'),
+            name: '',
+            description: '',
+            ownerUserId: 0,
+            created: '',
+            updated: '',
+            deprecated: false,
+            latestVersion: null,
+        };
+    }
+    if (localSkill.metadata?.skillId) {
+        return {
+            id: localSkill.metadata.skillId,
+            name: localSkill.metadata.skillName,
+            description: localSkill.metadata.skillDescription,
+            ownerUserId: 0,
+            created: '',
+            updated: '',
+            deprecated: false,
+            latestVersion: localSkill.metadata.skillVersion,
+        };
+    }
+    const lookupName = normalizeText(localSkill.metadata?.skillName) ?? localSkill.defaults.name;
+    return resolveUploadSkillByName(client, lookupName);
+}
+async function resolveUploadSkillByName(client, skillName) {
+    const normalizedSkillName = normalizeText(skillName)?.toLowerCase();
+    if (!normalizedSkillName) {
+        return null;
+    }
+    const skills = await client.get('/api/skills');
+    const exactNameMatches = skills.filter((skill) => normalizeText(skill.name)?.toLowerCase() === normalizedSkillName);
+    if (exactNameMatches.length === 0) {
+        return null;
+    }
+    const currentUser = await client.get('/api/auth/me');
+    const authorizedMatches = currentUser.isAdmin
+        ? exactNameMatches
+        : exactNameMatches.filter((skill) => skill.ownerUserId === currentUser.storedUserId);
+    const authorizedMatch = authorizedMatches[0];
+    if (authorizedMatches.length === 1 && authorizedMatch) {
+        return authorizedMatch;
+    }
+    if (authorizedMatches.length > 1) {
+        throw new Error(`Skill name '${skillName}' matches multiple skills you can update: ${formatSkillMatches(authorizedMatches)}. Use --skill-id instead.`);
+    }
+    if (exactNameMatches.length === 1) {
+        throw new Error(`Skill '${skillName}' already exists on the server, but the current user can publish new versions only as the owner or an admin.`);
+    }
+    throw new Error(`Skill name '${skillName}' matches multiple existing skills: ${formatSkillMatches(exactNameMatches)}. Use --skill-id instead.`);
+}
 function resolveSkillReference(skills, reference) {
     const normalizedReference = normalizeText(reference)?.toLowerCase();
     if (!normalizedReference) {
@@ -805,11 +1218,15 @@ function resolveInstallTargets(agents, scope, installName) {
     }
     return [...targets.values()];
 }
-function createInstalledSkillDirectoryName(skill) {
-    const normalized = skill.name
+function createNormalizedSkillDirectoryName(name) {
+    const normalized = name
         .toLowerCase()
         .replace(/[^a-z0-9]+/g, '-')
         .replace(/^-+|-+$/g, '');
+    return normalized;
+}
+function createInstalledSkillDirectoryName(skill) {
+    const normalized = createNormalizedSkillDirectoryName(skill.name);
     return normalized.length > 0 ? normalized : `skill-${skill.id}`;
 }
 async function login(baseUrl) {
@@ -847,6 +1264,7 @@ async function login(baseUrl) {
     console.log(`Logged in as ${response.user.displayName} (${baseUrl})`);
 }
 async function parseOptions(args) {
+    const booleanFlags = new Set(['dry-run']);
     const flags = {};
     const positionals = [];
     for (let index = 0; index < args.length; index += 1) {
@@ -858,6 +1276,10 @@ async function parseOptions(args) {
             const key = current.slice(2);
             const value = args[index + 1];
             if (!value || value.startsWith('--')) {
+                if (booleanFlags.has(key)) {
+                    flags[key] = 'true';
+                    continue;
+                }
                 throw new Error(`Missing value for ${current}`);
             }
             flags[key] = value;
@@ -867,12 +1289,21 @@ async function parseOptions(args) {
             positionals.push(current);
         }
     }
+    const tokenFromFlag = normalizeText(flags.token);
+    const tokenFromEnvironment = normalizeText(process.env.SKILLSHARE_TOKEN);
     return {
-        token: flags.token,
+        token: tokenFromFlag ?? tokenFromEnvironment ?? undefined,
         flags,
         positionals,
     };
 }
+function isFlagEnabled(flags, key) {
+    const value = normalizeText(flags[key]);
+    if (!value) {
+        return false;
+    }
+    return !['0', 'false', 'no', 'off'].includes(value.toLowerCase());
+}
 async function resolveActiveBaseUrl() {
     const session = await loadAnySession();
     if (session?.baseUrl) {
@@ -945,6 +1376,7 @@ async function createClient(baseUrl, explicitToken) {
         });
     }
     return {
+        baseUrl: resolvedBaseUrl,
         async get(path) {
             const response = await sendAuthorized(path);
             return parseJson(response);
@@ -1159,14 +1591,29 @@ async function waitForLoginCallback() {
         },
     };
 }
-async function readLocalSkillMetadata(directory) {
+async function readLocalSkillMetadata(directory, baseUrl) {
+    const resolvedDirectory = resolve(directory);
+    const normalizedBaseUrl = normalizeText(baseUrl) ? normalizeBaseUrl(baseUrl) : null;
+    const uploadedRecords = await readUploadedSkillRecords();
+    const matchingRecord = uploadedRecords
+        .filter((record) => record.directory === resolvedDirectory && (!normalizedBaseUrl || record.baseUrl === normalizedBaseUrl))
+        .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt))[0];
+    if (matchingRecord) {
+        return {
+            skillId: matchingRecord.skillId,
+            skillName: matchingRecord.skillName,
+            skillDescription: matchingRecord.skillDescription,
+            skillVersion: matchingRecord.skillVersion,
+        };
+    }
+    return readLegacyLocalSkillMetadata(resolvedDirectory);
+}
+async function readLegacyLocalSkillMetadata(directory) {
     const metadataPath = join(resolve(directory), SKILL_METADATA_FILE_NAME);
     try {
         const parsed = JSON.parse(await readFile(metadataPath, 'utf8'));
-        const skillId = Number(parsed.skillId);
-        if (!Number.isInteger(skillId) || skillId <= 0) {
-            throw new Error(`Invalid skillId in ${SKILL_METADATA_FILE_NAME}.`);
-        }
+        const parsedSkillId = Number(parsed.skillId);
+        const skillId = Number.isInteger(parsedSkillId) && parsedSkillId > 0 ? parsedSkillId : undefined;
         return {
             skillId,
             skillName: typeof parsed.skillName === 'string' ? parsed.skillName : '',
@@ -1181,9 +1628,102 @@ async function readLocalSkillMetadata(directory) {
         throw new Error(`Failed to read ${metadataPath}: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
-async function writeLocalSkillMetadata(directory, metadata) {
-    await mkdir(directory, { recursive: true });
-    await writeFile(join(directory, SKILL_METADATA_FILE_NAME), `${JSON.stringify(metadata, null, 2)}\n`);
+async function upsertUploadedSkillMetadata(baseUrl, directory, metadata) {
+    const normalizedBaseUrl = normalizeBaseUrl(baseUrl);
+    const resolvedDirectory = resolve(directory);
+    const records = (await readUploadedSkillRecords())
+        .filter((record) => !(record.directory === resolvedDirectory && record.baseUrl === normalizedBaseUrl));
+    records.unshift({
+        ...metadata,
+        directory: resolvedDirectory,
+        baseUrl: normalizedBaseUrl,
+        updatedAt: new Date().toISOString(),
+    });
+    await writeStateFile(UPLOADED_STATE_PATH, records);
+    await removeLegacyLocalSkillMetadata(resolvedDirectory);
+}
+async function upsertInstalledSkillRecord(baseUrl, targetRoot, metadata) {
+    const normalizedBaseUrl = normalizeBaseUrl(baseUrl);
+    const resolvedTargetRoot = resolve(targetRoot);
+    const records = (await readInstalledSkillRecords())
+        .filter((record) => !(record.targetRoot === resolvedTargetRoot && record.baseUrl === normalizedBaseUrl));
+    records.unshift({
+        ...metadata,
+        targetRoot: resolvedTargetRoot,
+        baseUrl: normalizedBaseUrl,
+        updatedAt: new Date().toISOString(),
+    });
+    await writeStateFile(INSTALLED_STATE_PATH, records);
+    await removeLegacyLocalSkillMetadata(resolvedTargetRoot);
+}
+async function readUploadedSkillRecords() {
+    const parsed = await readStateFile(UPLOADED_STATE_PATH);
+    return parsed.flatMap((entry) => {
+        if (!entry || typeof entry !== 'object') {
+            return [];
+        }
+        const skillId = Number(entry.skillId);
+        const normalizedSkillId = Number.isInteger(skillId) && skillId > 0 ? skillId : undefined;
+        return [{
+                directory: typeof entry.directory === 'string' ? resolve(entry.directory) : '',
+                baseUrl: typeof entry.baseUrl === 'string' ? normalizeBaseUrl(entry.baseUrl) : PROD_URL,
+                updatedAt: typeof entry.updatedAt === 'string' ? entry.updatedAt : '',
+                skillId: normalizedSkillId,
+                skillName: typeof entry.skillName === 'string' ? entry.skillName : '',
+                skillDescription: typeof entry.skillDescription === 'string' ? entry.skillDescription : '',
+                skillVersion: typeof entry.skillVersion === 'string' ? entry.skillVersion : '',
+            }].filter((record) => record.directory.length > 0);
+    });
+}
+async function readInstalledSkillRecords() {
+    const parsed = await readStateFile(INSTALLED_STATE_PATH);
+    return parsed.flatMap((entry) => {
+        if (!entry || typeof entry !== 'object') {
+            return [];
+        }
+        const skillId = Number(entry.skillId);
+        if (!Number.isInteger(skillId) || skillId <= 0) {
+            return [];
+        }
+        return [{
+                targetRoot: typeof entry.targetRoot === 'string' ? resolve(entry.targetRoot) : '',
+                baseUrl: typeof entry.baseUrl === 'string' ? normalizeBaseUrl(entry.baseUrl) : PROD_URL,
+                updatedAt: typeof entry.updatedAt === 'string' ? entry.updatedAt : '',
+                skillId,
+                skillName: typeof entry.skillName === 'string' ? entry.skillName : '',
+                skillDescription: typeof entry.skillDescription === 'string' ? entry.skillDescription : '',
+                skillVersion: typeof entry.skillVersion === 'string' ? entry.skillVersion : '',
+            }].filter((record) => record.targetRoot.length > 0);
+    });
+}
+async function readStateFile(path) {
+    try {
+        const parsed = JSON.parse(await readFile(path, 'utf8'));
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT') {
+            return [];
+        }
+        throw new Error(`Failed to read ${path}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+async function writeStateFile(path, value) {
+    await mkdir(APP_DIR, { recursive: true });
+    await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, {
+        mode: process.platform === 'win32' ? undefined : 0o600,
+    });
+}
+async function removeLegacyLocalSkillMetadata(directory) {
+    try {
+        await rm(join(resolve(directory), SKILL_METADATA_FILE_NAME));
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT') {
+            return;
+        }
+        throw error;
+    }
 }
 async function collectFilePlans(root, current = root) {
     const entries = await readdir(current, { withFileTypes: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quadient/skillshare",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Skillshare CLI for installing and publishing Quadient skills",
   "type": "module",
   "bin": {