@quadient/skillshare 0.1.1 → 1.1.0

package/README.md

@@ -9,6 +9,8 @@ bun run index.ts
 bun run index.ts login
 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 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
@@ -17,11 +19,109 @@ bun run index.ts install --skill-version-id 42 --target ./installed
 Interactive 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.
 
+## 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| 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 or Upload?}
+	Y -->|Install| Z[runInteractiveInstall]
+	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[Write skillshare.metadata.json]
+	Z10 --> END[Done]
+
+	W --> W1[Load local skill context]
+	W1 --> W2{Local metadata has skillId?}
+
+	W2 -- No --> W3[Prompt initial version]
+	W3 --> W4[createSkillFromDirectory]
+	W4 --> W5[POST create skill]
+	W5 --> W6[GET created skill detail]
+	W6 --> W7[Write skillshare.metadata.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 metadata]
+	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 skillshare.metadata.json]
+	W18 --> END
+
+	H --> H1{Non-interactive branch}
+	H1 -->|whoami| H2[GET /api/auth/me]
+	H1 -->|list| H3[GET /api/skills]
+	H1 -->|show| H4[GET skill or version detail]
+	H1 -->|upload| H5[Load local skill context]
+	H1 -->|install without --target| Z
+	H1 -->|install with --target| H6[Resolve skill and version]
+	H6 --> H7[GET version detail]
+	H7 --> H8[POST download audit]
+	H8 --> H9[Write files and metadata to target]
+	H9 --> END
+	H5 --> H10{Known skillId?}
+	H10 -- No --> W4
+	H10 -- Yes --> W15
+```
+
 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.

package/dist/index.js

@@ -71,7 +71,9 @@ Commands:
   list
   show <skillId> [version]
   upload <directory> --version <version> [--skill-id <id>] [--name <name> --description <desc>]
-  install <skillId> [version] --target <directory>
+  install
+  install <skillId|skillName> [version]
+  install <skillId|skillName> [version] --target <directory>
   install --skill-version-id <id> --target <directory>
 
 Options:
@@ -137,10 +139,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,
@@ -150,9 +152,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));
                     }
@@ -160,7 +161,7 @@ async function main() {
                 }
                 case 'install': {
                     const skillVersionId = options.flags['skill-version-id'];
-                    const skillId = options.positionals[0];
+                    const skillRef = options.positionals[0];
                     const version = options.positionals[1];
                     const target = options.flags.target;
                     if (skillVersionId) {
@@ -185,16 +186,24 @@ async function main() {
                         console.log(`Installed skillVersion ${parsedSkillVersionId} (${detail.skillId}@${detail.version}) to ${target}`);
                         return;
                     }
-                    if (!skillId || !target) {
-                        throw new Error('install requires <skillId> [version] --target <directory> or --skill-version-id <id> --target <directory>');
+                    if (!target) {
+                        await runInteractiveInstall(client, {
+                            skillRef,
+                            version,
+                        });
+                        return;
+                    }
+                    if (!skillRef) {
+                        throw new Error('install requires <skillId|skillName> [version] when --target <directory> is provided');
                     }
-                    const skill = await client.get(`/api/skills/${skillId}`);
+                    const skills = await client.get('/api/skills');
+                    const skill = resolveSkillReference(skills, skillRef);
                     const effectiveVersion = version ?? skill.latestVersion;
                     if (!effectiveVersion) {
-                        throw new Error(`Skill '${skillId}' does not have a published version.`);
+                        throw new Error(`Skill '${skill.name}' does not have a published version.`);
                     }
-                    const detail = await client.get(`/api/skills/${skillId}/versions/${effectiveVersion}`);
-                    await client.post(`/api/skills/${skillId}/versions/${effectiveVersion}/downloads`);
+                    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,
                         skillName: skill.name,
@@ -203,7 +212,7 @@ async function main() {
                         files: detail.files,
                         targetRoot: target,
                     });
-                    console.log(`Installed ${skillId}@${effectiveVersion} to ${target}`);
+                    console.log(`Installed ${skill.name}@${effectiveVersion} to ${target}`);
                     return;
                 }
             }
@@ -266,14 +275,18 @@ async function ensureInteractiveLogin(baseUrl) {
         await login(baseUrl);
     }
 }
-async function runInteractiveInstall(client) {
+async function runInteractiveInstall(client, options) {
     const skills = await client.get('/api/skills');
     if (skills.length === 0) {
         throw new Error('No skills available in the registry.');
     }
-    const skill = await promptForSkill(skills);
+    const skill = options?.skillRef
+        ? resolveSkillReference(skills, options.skillRef)
+        : await promptForSkill(skills);
     const detail = await client.get(`/api/skills/${skill.id}`);
-    const selectedVersion = await promptForVersion(detail);
+    const selectedVersion = options?.version
+        ? resolveSkillVersion(detail, options.version)
+        : await promptForVersion(detail);
     const scope = await promptForInstallScope();
     const selectedAgents = await promptForAgents(scope);
     if (selectedAgents.length === 0) {
@@ -299,14 +312,15 @@ 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 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);
@@ -329,7 +343,6 @@ 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}`);
 }
@@ -544,9 +557,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 {
@@ -723,6 +733,102 @@ 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) {
+        throw new Error('Skill reference is required.');
+    }
+    const idMatch = skills.find((skill) => String(skill.id) === normalizedReference);
+    if (idMatch) {
+        return idMatch;
+    }
+    const exactNameMatches = skills.filter((skill) => normalizeText(skill.name)?.toLowerCase() === normalizedReference);
+    const exactNameMatch = exactNameMatches[0];
+    if (exactNameMatches.length === 1 && exactNameMatch) {
+        return exactNameMatch;
+    }
+    if (exactNameMatches.length > 1) {
+        throw new Error(`Skill reference '${reference}' matches multiple skills: ${formatSkillMatches(exactNameMatches)}. Use the numeric skill id instead.`);
+    }
+    const slugMatches = skills.filter((skill) => createInstalledSkillDirectoryName(skill) === normalizedReference);
+    const slugMatch = slugMatches[0];
+    if (slugMatches.length === 1 && slugMatch) {
+        return slugMatch;
+    }
+    if (slugMatches.length > 1) {
+        throw new Error(`Skill reference '${reference}' matches multiple skills: ${formatSkillMatches(slugMatches)}. Use the numeric skill id instead.`);
+    }
+    throw new Error(`Skill '${reference}' was not found. Run "skillshare list" to inspect available skills.`);
+}
+function resolveSkillVersion(detail, version) {
+    const normalizedVersion = normalizeText(version);
+    if (!normalizedVersion) {
+        throw new Error('Version is required.');
+    }
+    const requestedVersion = detail.versions.find((item) => item.version === normalizedVersion);
+    if (!requestedVersion) {
+        throw new Error(`Skill '${detail.name}' does not have version '${normalizedVersion}'.`);
+    }
+    return requestedVersion.version;
+}
+function formatSkillMatches(skills) {
+    return skills.map((skill) => `${skill.id}:${skill.name}`).join(', ');
+}
 function filterSkills(skills, query) {
     const normalized = query.trim().toLowerCase();
     return skills.filter((skill) => skill.name.toLowerCase().includes(normalized) ||
@@ -1108,10 +1214,8 @@ async function readLocalSkillMetadata(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 : '',

package/package.json

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