@quadient/skillshare 1.6.2 → 1.8.0

package/dist/index.js

@@ -1,3 +1,7 @@
+import { assertCredentialDestination, runTeamsCommand } from './teams.js';
+import { formatUnknownCommand, parseCliArgs } from './cli-args.js';
+import { findCommand, readCliVersion, renderCommandHelp, renderUsage } from './help.js';
+import { inspectInstallTarget, installFilesAtomically } from './install-files.js';
 import { preparePageFiles } from './pages.js';
 import { runPageDev } from './pages-dev.js';
 import { createServer } from 'node:http';
@@ -5,9 +9,9 @@ import { createHash, randomBytes } from 'node:crypto';
 import { spawn } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { mkdir, open, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
-import { basename, dirname, join, relative, resolve } from 'node:path';
+import { basename, 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';
+import { cancel, confirm, intro, isCancel, log, multiselect, outro, progress, select, spinner, text } from '@clack/prompts';
 const DEFAULT_URL = 'https://skillshare.quadientcloudpreprod.eu';
 // Records without a registry URL were created against UAT before the preprod migration.
 const LEGACY_UAT_URL = 'https://skillshare.inspireclouduat.net';
@@ -67,36 +71,7 @@ const AGENTS = [
     { value: 'pochi', label: 'Pochi', projectPath: '.pochi/skills', globalPath: '.pochi/skills' },
     { value: 'adal', label: 'AdaL', projectPath: '.adal/skills', globalPath: '.adal/skills' },
 ];
-const usage = `
-skillshare <command> [options]
-
-Commands:
-  login [local]
-  logout
-  whoami
-  list
-  show <skillId> [version]
-  upload <directory> --version <version> [--skill-id <id>] [--name <name> --description <desc>]
-  install
-  install <skillId|skillName> [version]
-  install <skillId|skillName> [version] --target <directory>
-  install --skill-version-id <id> --target <directory>
-  update [skillId|skillName] [--target <directory>] [--dry-run]
-  pages list
-  pages show <slug>
-  pages upload <directory> [--slug <slug>]
-  pages dev [directory] [--slug <slug>] [--port <port>]
-    [--build <command> --watch-dir <sources>] [--celld <executable>]
-    [--user-id <id>] [--user-name <name>] [--user-email <email>]
-  git configure [local]
-  git unconfigure [local]
-
-Options:
-  --token <token>    Bearer token for API requests (overrides SKILLSHARE_TOKEN)
-
-Default server: ${DEFAULT_URL}
-A stored session keeps its server; run "skillshare login" to switch to the default.
-`;
+const LOGIN_TIMEOUT_MS = 5 * 60_000;
 async function main() {
     const args = process.argv.slice(2);
     const command = args[0];
@@ -104,24 +79,52 @@ async function main() {
         await runInteractive();
         return;
     }
-    if (command === '--help' || command === '-h') {
-        console.log(usage.trim());
-        process.exit(0);
+    if (command === '--version' || command === '-v') {
+        console.log(readCliVersion());
+        return;
+    }
+    if (command === '--help' || command === '-h' || command === 'help') {
+        const topic = command === 'help' ? findCommand(args[1]) : undefined;
+        if (command === 'help' && args[1] && !topic) {
+            throw new Error(formatUnknownCommand(args[1]));
+        }
+        console.log(topic ? renderCommandHelp(topic) : renderUsage(DEFAULT_URL));
+        return;
+    }
+    const commandSpec = findCommand(command);
+    if (!commandSpec) {
+        throw new Error(formatUnknownCommand(command));
+    }
+    // pages dev validates its own options.
+    const isPageDev = (command === 'pages' || command === 'page') && args[1] === 'dev';
+    const options = await parseOptions(args.slice(1), isPageDev ? undefined : command);
+    if (isFlagEnabled(options.flags, 'help')) {
+        console.log(renderCommandHelp(commandSpec));
+        return;
     }
-    const options = await parseOptions(args.slice(1));
     if ((command === 'pages' || command === 'page') && options.positionals[0] === 'dev') {
         await runPageDev(options.positionals[1] ?? '.', options.flags);
         return;
     }
     switch (command) {
         case 'login': {
-            await login(options.positionals[0] === 'local' ? LOCAL_URL : DEFAULT_URL);
+            const baseUrl = options.flags.server ?? (options.positionals[0] === 'local' ? LOCAL_URL : DEFAULT_URL);
+            assertCredentialDestination(baseUrl);
+            await login(baseUrl);
             return;
         }
         case 'logout': {
             await logoutSession();
             return;
         }
+        case 'teams': {
+            const baseUrl = options.flags.server ?? (options.positionals[1] === 'local' ? LOCAL_URL : await resolveActiveBaseUrl());
+            assertCredentialDestination(baseUrl);
+            if (!options.token && !await loadSession(baseUrl))
+                await login(baseUrl);
+            await runTeamsCommand(await createClient(baseUrl, options.token), options.positionals, options.flags, APP_DIR);
+            return;
+        }
         case 'git': {
             const action = options.positionals[0];
             const baseUrl = options.positionals[1] === 'local' ? LOCAL_URL : DEFAULT_URL;
@@ -203,6 +206,7 @@ async function main() {
                     const skillRef = options.positionals[0];
                     const version = options.positionals[1];
                     const target = options.flags.target;
+                    const force = isFlagEnabled(options.flags, 'force');
                     if (skillVersionId) {
                         if (!target) {
                             throw new Error('install with --skill-version-id requires --target <directory>');
@@ -213,6 +217,7 @@ async function main() {
                         }
                         const detail = await client.get(`/api/skill-versions/${parsedSkillVersionId}`);
                         const skill = await client.get(`/api/skills/${detail.skillId}`);
+                        await ensureTargetsWritable(client.baseUrl, [target], { force });
                         await client.post(`/api/skills/${detail.skillId}/versions/${detail.version}/downloads`);
                         const installProgress = createInstallProgressReporter({
                             skillName: skill.name,
@@ -242,6 +247,7 @@ async function main() {
                         await runInteractiveInstall(client, {
                             skillRef,
                             version,
+                            force,
                         });
                         return;
                     }
@@ -255,6 +261,7 @@ async function main() {
                         throw new Error(`Skill '${skill.name}' does not have a published version.`);
                     }
                     const detail = await client.get(`/api/skills/${skill.id}/versions/${effectiveVersion}`);
+                    await ensureTargetsWritable(client.baseUrl, [target], { force });
                     await client.post(`/api/skills/${skill.id}/versions/${effectiveVersion}/downloads`);
                     const installProgress = createInstallProgressReporter({
                         skillName: skill.name,
@@ -285,6 +292,7 @@ async function main() {
                         skillRef: options.positionals[0],
                         target: options.flags.target,
                         dryRun: isFlagEnabled(options.flags, 'dry-run'),
+                        force: isFlagEnabled(options.flags, 'force'),
                     });
                     return;
                 }
@@ -331,23 +339,22 @@ async function main() {
             return;
         }
         default:
-            throw new Error(`Unknown command '${command}'`);
+            throw new Error(formatUnknownCommand(command));
     }
 }
 async function runInteractive() {
-    intro('Skillshare');
+    intro(`Skillshare ${readCliVersion()}`);
     const baseUrl = await resolveActiveBaseUrl();
-    await ensureInteractiveLogin(baseUrl);
+    const user = await ensureInteractiveLogin(baseUrl);
     const client = await createClient(baseUrl);
-    const pendingInstalledUpdates = await collectInstalledSkillUpdateCandidates(client);
+    log.info(`Signed in as ${user.displayName}${user.email ? ` <${user.email}>` : ''} · ${new URL(client.baseUrl).host}`);
+    const pendingInstalledUpdates = await checkInstalledSkillsForUpdates(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))) {
@@ -367,12 +374,17 @@ async function runInteractive() {
             { 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' },
+            { value: 'exit', label: 'Exit' },
         ],
     });
     if (isCancel(action)) {
         cancel('Cancelled.');
         process.exit(0);
     }
+    if (action === 'exit') {
+        outro('Bye.');
+        return;
+    }
     if (action === 'install') {
         await runInteractiveInstall(client);
     }
@@ -384,22 +396,53 @@ async function runInteractive() {
     }
     outro('Done.');
 }
+async function checkInstalledSkillsForUpdates(client) {
+    const records = (await readInstalledSkillRecords()).filter((record) => record.baseUrl === client.baseUrl);
+    if (records.length === 0) {
+        return [];
+    }
+    const status = spinner();
+    status.start(`Checking ${records.length} installed skill${records.length === 1 ? '' : 's'} for updates`);
+    const problems = [];
+    try {
+        const candidates = await collectInstalledSkillUpdateCandidates(client, {
+            records,
+            onSkipped(skip) {
+                if (skip.reason === 'removed' || skip.reason === 'error') {
+                    problems.push(skip.message);
+                }
+            },
+        });
+        status.stop(candidates.length > 0
+            ? `${candidates.length} installed skill${candidates.length === 1 ? ' has' : 's have'} a newer version`
+            : 'Installed skills are up to date');
+        if (problems.length > 0) {
+            log.warn(problems.join('\n'));
+        }
+        return candidates;
+    }
+    catch (error) {
+        // The update check is optional; never let it block the main menu.
+        status.stop('Could not check installed skills for updates');
+        log.warn(error instanceof Error ? error.message : String(error));
+        return [];
+    }
+}
 async function ensureInteractiveLogin(baseUrl) {
     const session = await loadSession(baseUrl);
-    if (!session) {
-        await login(baseUrl);
-        return;
-    }
-    if (new Date(session.refreshTokenExpiresAt).getTime() <= Date.now()) {
-        await login(baseUrl);
-        return;
+    if (!session || new Date(session.refreshTokenExpiresAt).getTime() <= Date.now()) {
+        return login(baseUrl);
     }
     try {
         const client = await createClient(baseUrl);
-        await client.get('/api/auth/me');
+        return await client.get('/api/auth/me');
     }
-    catch {
-        await login(baseUrl);
+    catch (error) {
+        // Offline is not an expired session; signing in again would not help.
+        if (error instanceof NetworkError) {
+            throw error;
+        }
+        return login(baseUrl);
     }
 }
 async function runInteractiveInstall(client, options) {
@@ -420,9 +463,13 @@ async function runInteractiveInstall(client, options) {
         throw new Error('Select at least one agent.');
     }
     const versionDetail = await client.get(`/api/skills/${skill.id}/versions/${selectedVersion}`);
-    await client.post(`/api/skills/${skill.id}/versions/${selectedVersion}/downloads`);
     const installName = createInstalledSkillDirectoryName(skill);
     const installTargets = resolveInstallTargets(selectedAgents, scope, installName);
+    await ensureTargetsWritable(client.baseUrl, installTargets.map((target) => target.targetRoot), {
+        force: options?.force,
+        interactive: true,
+    });
+    await client.post(`/api/skills/${skill.id}/versions/${selectedVersion}/downloads`);
     const installProgress = createInstallProgressReporter({
         skillName: skill.name,
         version: selectedVersion,
@@ -446,7 +493,11 @@ async function runInteractiveInstall(client, options) {
         installProgress.clear();
         throw error;
     }
-    console.log(`Installed ${skill.name}@${selectedVersion} to ${installTargets.length} location(s) for ${selectedAgents.length} agent(s) in ${scope} scope.`);
+    log.success([
+        `Installed ${skill.name}@${selectedVersion} for ${selectedAgents.length} agent${selectedAgents.length === 1 ? '' : 's'}:`,
+        ...installTargets.map((target) => `  ${formatInstallTargetRoot(target.targetRoot)}`),
+        'Restart running agents to pick up the skill.',
+    ].join('\n'));
 }
 async function runInteractiveUpload(client, initialDirectory) {
     const directory = initialDirectory
@@ -504,6 +555,7 @@ async function updateInstalledSkills(client, options) {
     const targetFilter = normalizeText(options?.target);
     const normalizedTargetFilter = targetFilter ? resolve(targetFilter) : null;
     const dryRun = options?.dryRun ?? false;
+    const force = options?.force ?? false;
     let installedRecords = (await readInstalledSkillRecords())
         .filter((record) => record.baseUrl === client.baseUrl);
     if (skillRef) {
@@ -527,11 +579,11 @@ async function updateInstalledSkills(client, options) {
     const candidates = options?.candidates
         ?? await collectInstalledSkillUpdateCandidates(client, {
             records: installedRecords,
-            onSkipped(message) {
-                console.log(message);
+            onSkipped(skip) {
+                console.log(skip.message);
             },
         });
-    const skippedCount = installedRecords.length - candidates.length;
+    let skippedCount = installedRecords.length - candidates.length;
     if (candidates.length === 0) {
         if (dryRun) {
             console.log(`Dry run finished. Would update 0, skipped ${skippedCount}.`);
@@ -545,9 +597,16 @@ async function updateInstalledSkills(client, options) {
     let plannedCount = 0;
     for (const candidate of candidates) {
         const { record, detail, latestVersion } = candidate;
+        const targetState = force ? null : await inspectInstallTarget(record.targetRoot, record);
+        if (targetState?.state === 'modified') {
+            skippedCount += 1;
+            console.log(`Skipping ${detail.name} in ${formatInstallTargetRoot(record.targetRoot)}: local changes in ${formatChangedPaths(targetState.paths)}. `
+                + `Run "skillshare update ${record.skillId} --target ${formatCliPath(record.targetRoot)} --force" to overwrite them.`);
+            continue;
+        }
         if (dryRun) {
             plannedCount += 1;
-            console.log(`Would update ${detail.name} from ${record.skillVersion} to ${latestVersion} in ${record.targetRoot}`);
+            console.log(`Would update ${detail.name} from ${record.skillVersion} to ${latestVersion} in ${formatInstallTargetRoot(record.targetRoot)}`);
             continue;
         }
         const versionDetail = await client.get(`/api/skills/${record.skillId}/versions/${latestVersion}`);
@@ -574,7 +633,7 @@ async function updateInstalledSkills(client, options) {
             throw error;
         }
         updatedCount += 1;
-        console.log(`Updated ${detail.name} from ${record.skillVersion} to ${latestVersion} in ${record.targetRoot}`);
+        console.log(`Updated ${detail.name} from ${record.skillVersion} to ${latestVersion} in ${formatInstallTargetRoot(record.targetRoot)}`);
     }
     if (dryRun) {
         console.log(`Dry run finished. Would update ${plannedCount}, skipped ${skippedCount}.`);
@@ -585,30 +644,59 @@ async function updateInstalledSkills(client, options) {
 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 details = new Map();
+    // Each record is checked independently, so one removed skill or failed request does not hide the others.
+    const results = await mapWithConcurrency(records, 6, async (record) => {
+        const skillId = record.skillId;
+        if (skillId == null) {
+            return { record, reason: 'no-id', message: `Skipping ${record.skillName}: installed record in ${record.targetRoot} does not contain a skill id.` };
+        }
+        let detail;
+        try {
+            if (!details.has(skillId)) {
+                details.set(skillId, client.get(`/api/skills/${skillId}`));
+            }
+            detail = await details.get(skillId);
+        }
+        catch (error) {
+            if (error instanceof HttpError && error.status === 404) {
+                return { record, reason: 'removed', message: `${record.skillName || `Skill ${skillId}`} in ${formatInstallTargetRoot(record.targetRoot)} no longer exists in the registry.` };
+            }
+            return { record, reason: 'error', message: `Could not check ${record.skillName || `skill ${skillId}`}: ${error instanceof Error ? error.message : String(error)}` };
         }
-        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;
+            return { record, reason: 'no-version', message: `Skipping ${record.skillName}: no latest version is published.` };
         }
         if (latestVersion === normalizeText(record.skillVersion)) {
-            options?.onSkipped?.(`Skipping ${record.skillName}: ${latestVersion} is already installed in ${record.targetRoot}.`);
-            continue;
+            return { record, reason: 'current', message: `Skipping ${record.skillName}: ${latestVersion} is already installed in ${formatInstallTargetRoot(record.targetRoot)}.` };
+        }
+        return { record, detail, latestVersion };
+    });
+    const candidates = [];
+    for (const result of results) {
+        if ('reason' in result) {
+            options?.onSkipped?.(result);
+        }
+        else {
+            candidates.push(result);
         }
-        candidates.push({
-            record,
-            detail,
-            latestVersion,
-        });
     }
     return candidates;
 }
+async function mapWithConcurrency(items, limit, worker) {
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    async function run() {
+        while (nextIndex < items.length) {
+            const index = nextIndex;
+            nextIndex += 1;
+            results[index] = await worker(items[index]);
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, run));
+    return results;
+}
 function formatUpdateSelectionDescription(options) {
     const parts = [];
     if (options.skillRef) {
@@ -729,7 +817,7 @@ async function promptForAgents(scope) {
             })),
         ],
         initialValues,
-        required: false,
+        required: true,
     });
     if (isCancel(selected)) {
         cancel('Cancelled.');
@@ -865,31 +953,81 @@ async function publishSkillFromDirectory(client, localSkill, 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 downloadResponseToFile(response, destination, (bytes) => {
-            installProgress?.onBytesTransferred(bytes);
-        });
-        installProgress?.onFileComplete();
-    }
+    const previous = await findInstalledSkillRecord(client.baseUrl, input.targetRoot);
+    const expectedSizes = new Map(input.files.map((file) => [file.nameWithPath, file.length]));
+    const manifest = await installFilesAtomically({
+        targetRoot: input.targetRoot,
+        files: input.files.map((file) => ({ relativePath: file.nameWithPath })),
+        previousManifest: previous?.files,
+        async download(relativePath, destination) {
+            installProgress?.onFileStart(input.targetRoot, relativePath, expectedSizes.get(relativePath) ?? 0);
+            const response = await client.rawGet(`/api/skills/${input.skillId}/versions/${input.version}/files/${relativePath}`);
+            const hash = await downloadResponseToFile(response, destination, (bytes) => {
+                installProgress?.onBytesTransferred(bytes);
+            });
+            installProgress?.onFileComplete();
+            return hash;
+        },
+    });
     await upsertInstalledSkillRecord(client.baseUrl, input.targetRoot, {
         skillId: input.skillId,
         skillName: input.skillName,
         skillDescription: input.skillDescription,
         skillVersion: input.version,
-    });
+    }, manifest);
     installProgress?.onTargetComplete();
 }
+async function findInstalledSkillRecord(baseUrl, targetRoot) {
+    const resolvedTargetRoot = resolve(targetRoot);
+    const records = (await readInstalledSkillRecords()).filter((record) => record.targetRoot === resolvedTargetRoot);
+    return records.find((record) => record.baseUrl === normalizeBaseUrl(baseUrl)) ?? records[0] ?? null;
+}
+async function ensureTargetsWritable(baseUrl, targetRoots, options) {
+    if (options.force) {
+        return;
+    }
+    const conflicts = [];
+    for (const targetRoot of targetRoots) {
+        // Directories installed before installed.json existed still carry the legacy metadata file.
+        const record = await findInstalledSkillRecord(baseUrl, targetRoot)
+            ?? (existsSync(join(targetRoot, SKILL_METADATA_FILE_NAME)) ? {} : null);
+        const state = await inspectInstallTarget(targetRoot, record);
+        if (state.state === 'modified') {
+            conflicts.push(`  ${formatInstallTargetRoot(targetRoot)}: local changes in ${formatChangedPaths(state.paths)}`);
+        }
+        else if (state.state === 'untracked') {
+            conflicts.push(`  ${formatInstallTargetRoot(targetRoot)}: contains files not installed by Skillshare`);
+        }
+    }
+    if (conflicts.length === 0) {
+        return;
+    }
+    if (options.interactive) {
+        log.warn(`These install locations would be overwritten:\n${conflicts.join('\n')}`);
+        if (await promptConfirm('Overwrite them?', false)) {
+            return;
+        }
+        cancel('Install cancelled. Nothing was changed.');
+        process.exit(0);
+    }
+    throw new Error(`Refusing to overwrite:\n${conflicts.join('\n')}\nRe-run with --force to overwrite.`);
+}
+function formatChangedPaths(paths) {
+    const shown = paths.slice(0, 3).join(', ');
+    return paths.length > 3 ? `${shown} and ${paths.length - 3} more` : shown;
+}
+function formatCliPath(path) {
+    const display = formatInstallTargetRoot(path);
+    return /^[A-Za-z0-9._/~-]+$/.test(display) ? display : JSON.stringify(display);
+}
 async function downloadResponseToFile(response, destination, onBytesTransferred) {
+    const hash = createHash('sha256');
     const body = response.body;
     if (!body) {
         const buffer = Buffer.from(await response.arrayBuffer());
         await writeFile(destination, buffer);
         onBytesTransferred?.(buffer.length);
-        return;
+        return hash.update(buffer).digest('hex');
     }
     const fileHandle = await open(destination, 'w');
     let failed = true;
@@ -905,6 +1043,7 @@ async function downloadResponseToFile(response, destination, onBytesTransferred)
                 continue;
             }
             await fileHandle.writeFile(value);
+            hash.update(value);
             onBytesTransferred?.(value.length);
         }
     }
@@ -914,6 +1053,7 @@ async function downloadResponseToFile(response, destination, onBytesTransferred)
             await rm(destination, { force: true });
         }
     }
+    return hash.digest('hex');
 }
 function createInstallProgressReporter(input) {
     const installStatus = spinner({ indicator: 'timer' });
@@ -1329,9 +1469,15 @@ async function login(baseUrl) {
     const loginUrl = `${baseUrl}/api/cli/login?redirectUri=${encodeURIComponent(callback.redirectUri)}` +
         `&codeChallenge=${encodeURIComponent(codeChallenge)}` +
         `&state=${encodeURIComponent(state)}`;
-    await openBrowser(loginUrl);
-    console.log(`Opening browser for ${baseUrl}`);
-    const authCode = await callback.wait(state);
+    console.log(`Opening the browser to sign in to ${baseUrl}.`);
+    console.log(`If it does not open, visit this URL on this computer:\n  ${loginUrl}`);
+    try {
+        await openBrowser(loginUrl);
+    }
+    catch {
+        console.log('Could not open a browser automatically. Use the URL above.');
+    }
+    const authCode = await callback.wait(state, LOGIN_TIMEOUT_MS);
     const response = await fetchJson(`${baseUrl}/api/cli/token`, {
         method: 'POST',
         headers: {
@@ -1353,6 +1499,7 @@ async function login(baseUrl) {
         user: response.user,
     });
     console.log(`Logged in as ${response.user.displayName} (${baseUrl})`);
+    return response.user;
 }
 const GCM_MINIMUM_VERSION = [2, 0, 931];
 async function configureGitCredentialManager(baseUrl) {
@@ -1414,32 +1561,8 @@ function compareVersions(left, right) {
 function formatVersion(version) {
     return version.join('.');
 }
-async function parseOptions(args) {
-    const booleanFlags = new Set(['dry-run']);
-    const flags = {};
-    const positionals = [];
-    for (let index = 0; index < args.length; index += 1) {
-        const current = args[index];
-        if (!current) {
-            continue;
-        }
-        if (current.startsWith('--')) {
-            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;
-            index += 1;
-        }
-        else {
-            positionals.push(current);
-        }
-    }
+async function parseOptions(args, commandName) {
+    const { flags, positionals } = parseCliArgs(args, commandName);
     const tokenFromFlag = normalizeText(flags.token);
     const tokenFromEnvironment = normalizeText(process.env.SKILLSHARE_TOKEN);
     return {
@@ -1476,7 +1599,7 @@ async function createClient(baseUrl, explicitToken) {
         if (new Date(currentSession.refreshTokenExpiresAt).getTime() <= Date.now()) {
             throw new Error(`Stored session for ${resolvedBaseUrl} is no longer valid. Run "skillshare login${resolvedBaseUrl === LOCAL_URL ? ' local' : ''}" again.`);
         }
-        const response = await fetch(`${resolvedBaseUrl}/api/cli/refresh`, {
+        const response = await fetchFromServer(`${resolvedBaseUrl}/api/cli/refresh`, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
@@ -1513,7 +1636,7 @@ async function createClient(baseUrl, explicitToken) {
         return refreshedSession.accessToken;
     }
     async function sendAuthorized(path, init, retryUnauthorized = true) {
-        const response = await fetch(`${resolvedBaseUrl}${path}`, {
+        const response = await fetchFromServer(`${resolvedBaseUrl}${path}`, {
             ...init,
             headers: await buildHeaders(() => getAccessToken(), init?.headers),
         });
@@ -1521,7 +1644,7 @@ async function createClient(baseUrl, explicitToken) {
             return response;
         }
         const refreshedToken = await getAccessToken({ forceRefresh: true });
-        return fetch(`${resolvedBaseUrl}${path}`, {
+        return fetchFromServer(`${resolvedBaseUrl}${path}`, {
             ...init,
             headers: await buildHeaders(() => Promise.resolve(refreshedToken), init?.headers),
         });
@@ -1538,10 +1661,14 @@ async function createClient(baseUrl, explicitToken) {
             });
             return parseJson(response);
         },
+        async request(path, init) {
+            // Streaming uploads cannot be replayed on an expired Skillshare access token.
+            return sendAuthorized(path, { ...init, redirect: 'error' }, typeof init.body === 'string' || !init.body);
+        },
         async rawGet(path) {
             const response = await sendAuthorized(path);
             if (!response.ok) {
-                throw new Error(await formatErrorResponse(response));
+                throw new HttpError(response.status, await formatErrorResponse(response));
             }
             return response;
         },
@@ -1596,9 +1723,34 @@ async function buildHeaders(getAccessToken, initialHeaders) {
     headers.set('Authorization', `Bearer ${await getAccessToken()}`);
     return headers;
 }
+class HttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = 'HttpError';
+    }
+}
+class NetworkError extends Error {
+    constructor(origin, cause) {
+        super(`Cannot reach ${origin}. Check your network or VPN connection and try again.`, { cause });
+        this.name = 'NetworkError';
+    }
+}
+async function fetchFromServer(input, init) {
+    try {
+        return await fetch(input, init);
+    }
+    catch (error) {
+        if (init?.signal?.aborted) {
+            throw error;
+        }
+        throw new NetworkError(new URL(input).origin, error);
+    }
+}
 async function parseJson(response) {
     if (!response.ok) {
-        throw new Error(await formatErrorResponse(response));
+        throw new HttpError(response.status, await formatErrorResponse(response));
     }
     return response.json();
 }
@@ -1633,7 +1785,7 @@ async function formatErrorResponse(response) {
         : `${fallbackMessage} ${body}`;
 }
 async function fetchJson(input, init) {
-    const response = await fetch(input, init);
+    const response = await fetchFromServer(input, init);
     return parseJson(response);
 }
 async function loadSession(baseUrl) {
@@ -1739,15 +1891,22 @@ async function waitForLoginCallback() {
     }
     return {
         redirectUri: `http://127.0.0.1:${address.port}/callback`,
-        async wait(expectedState) {
+        async wait(expectedState, timeoutMs) {
+            let timer;
+            const timeout = new Promise((_, reject) => {
+                timer = setTimeout(() => {
+                    reject(new Error(`Sign-in did not complete within ${Math.round(timeoutMs / 60_000)} minutes. Run "skillshare login" again.`));
+                }, timeoutMs);
+            });
             try {
-                const payload = JSON.parse(await statePromise);
+                const payload = JSON.parse(await Promise.race([statePromise, timeout]));
                 if (payload.state !== expectedState) {
                     throw new Error('Login state mismatch.');
                 }
                 return payload.code;
             }
             finally {
+                clearTimeout(timer);
                 server.close();
             }
         },
@@ -1804,7 +1963,7 @@ async function upsertUploadedSkillMetadata(baseUrl, directory, metadata) {
     await writeStateFile(UPLOADED_STATE_PATH, records);
     await removeLegacyLocalSkillMetadata(resolvedDirectory);
 }
-async function upsertInstalledSkillRecord(baseUrl, targetRoot, metadata) {
+async function upsertInstalledSkillRecord(baseUrl, targetRoot, metadata, files) {
     const normalizedBaseUrl = normalizeBaseUrl(baseUrl);
     const resolvedTargetRoot = resolve(targetRoot);
     const records = (await readInstalledSkillRecords())
@@ -1814,6 +1973,7 @@ async function upsertInstalledSkillRecord(baseUrl, targetRoot, metadata) {
         targetRoot: resolvedTargetRoot,
         baseUrl: normalizedBaseUrl,
         updatedAt: new Date().toISOString(),
+        ...(files ? { files } : {}),
     });
     await writeStateFile(INSTALLED_STATE_PATH, records);
     await removeLegacyLocalSkillMetadata(resolvedTargetRoot);
@@ -1855,9 +2015,17 @@ async function readInstalledSkillRecords() {
                 skillName: typeof entry.skillName === 'string' ? entry.skillName : '',
                 skillDescription: typeof entry.skillDescription === 'string' ? entry.skillDescription : '',
                 skillVersion: typeof entry.skillVersion === 'string' ? entry.skillVersion : '',
+                files: readFileManifest(entry.files),
             }].filter((record) => record.targetRoot.length > 0);
     });
 }
+function readFileManifest(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return undefined;
+    }
+    const entries = Object.entries(value).filter((entry) => typeof entry[1] === 'string');
+    return Object.fromEntries(entries);
+}
 async function readStateFile(path) {
     try {
         const parsed = JSON.parse(await readFile(path, 'utf8'));