@quadient/skillshare 1.0.0 → 1.1.0

package/README.md

@@ -25,6 +25,103 @@ Interactive behavior:
 - 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

@@ -139,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,
@@ -152,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));
                     }
@@ -313,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);
@@ -343,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}`);
 }
@@ -558,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 {
@@ -737,6 +733,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) {
@@ -1163,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": "1.0.0",
+  "version": "1.1.0",
   "description": "Skillshare CLI for installing and publishing Quadient skills",
   "type": "module",
   "bin": {