@quadient/skillshare 1.7.0 → 1.8.0

package/README.md

@@ -50,6 +50,14 @@ permissions, Microsoft session lifetime and file-tool differences in the hosted
 
 ## Behavior
 
+Starting with 1.8.0:
+
+- `install` and `update` download into a staging directory first, so a failed transfer leaves the existing install untouched. Files that a new version no longer contains are removed.
+- `installed.json` records a SHA-256 manifest of installed files. `update` skips installs with local changes and `install` refuses to overwrite them, or a directory that Skillshare did not install, unless you confirm interactively or pass `--force`. Installs recorded by older versions are not checked until they are updated once.
+- Interactive mode shows the signed-in user and server, checks installed skills in parallel, and reports removed skills or failed checks as warnings instead of stopping.
+- `login` prints the sign-in URL in case no browser opens, and stops waiting after 5 minutes.
+- Unknown options are rejected with a suggestion. `skillshare <command> --help`, `skillshare help <command>` and `skillshare --version` are available.
+
 - Starting with 1.6.2, `login`, `git configure` and API commands without a stored session default to `https://skillshare.quadientcloudpreprod.eu`. `login local` and `git configure local` still select `http://localhost:5050`.
 - Existing sessions keep their saved server. After preprod cutover, run `skillshare login` again to replace a UAT session with a preprod session; stored tokens are not reused across hosts.
 - Uploaded/installed records retain their registry URL. Legacy records without a URL still belong to UAT and are not silently reassigned to preprod.

package/dist/cli-args.js

@@ -0,0 +1,86 @@
+import { BOOLEAN_FLAGS, COMMANDS, GLOBAL_FLAGS, findCommand } from './help.js';
+/**
+ * Parses options for a command. With a command name, unknown options are rejected
+ * before a value is read, so a typo gets a suggestion instead of a missing-value error.
+ */
+export function parseCliArgs(args, commandName) {
+    const flags = {};
+    const positionals = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const current = args[index];
+        if (!current)
+            continue;
+        if (current === '-h') {
+            flags.help = 'true';
+            continue;
+        }
+        if (!current.startsWith('--') || current === '--') {
+            positionals.push(current);
+            continue;
+        }
+        const separator = current.indexOf('=');
+        const key = separator > 0 ? current.slice(2, separator) : current.slice(2);
+        if (commandName) {
+            assertKnownFlag(commandName, key);
+        }
+        if (separator > 0) {
+            flags[key] = current.slice(separator + 1);
+            continue;
+        }
+        const value = args[index + 1];
+        if (BOOLEAN_FLAGS.has(key)) {
+            // Booleans never consume a following positional, only an explicit true/false.
+            if (value === 'true' || value === 'false') {
+                flags[key] = value;
+                index += 1;
+            }
+            else {
+                flags[key] = 'true';
+            }
+            continue;
+        }
+        if (value === undefined || value.startsWith('--')) {
+            throw new Error(`Missing value for ${current}.`);
+        }
+        flags[key] = value;
+        index += 1;
+    }
+    return { flags, positionals };
+}
+function assertKnownFlag(commandName, name) {
+    const command = findCommand(commandName);
+    if (!command)
+        return;
+    const allowed = [...GLOBAL_FLAGS, ...command.flags];
+    if (allowed.includes(name))
+        return;
+    const suggestion = suggest(name, allowed);
+    throw new Error(`Unknown option --${name} for "${command.name}".${suggestion ? ` Did you mean --${suggestion}?` : ''} Run "skillshare ${command.name} --help" for options.`);
+}
+export function formatUnknownCommand(name) {
+    const suggestion = suggest(name, COMMANDS.map((command) => command.name));
+    return `Unknown command '${name}'.${suggestion ? ` Did you mean '${suggestion}'?` : ''} Run "skillshare --help" for the list of commands.`;
+}
+export function suggest(input, candidates) {
+    let best = null;
+    for (const candidate of candidates) {
+        const distance = candidate.startsWith(input) || input.startsWith(candidate) ? 1 : levenshtein(input, candidate);
+        if (distance <= 2 && (!best || distance < best.distance)) {
+            best = { candidate, distance };
+        }
+    }
+    return best?.candidate ?? null;
+}
+function levenshtein(left, right) {
+    const previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+    for (let i = 1; i <= left.length; i += 1) {
+        let diagonal = previous[0];
+        previous[0] = i;
+        for (let j = 1; j <= right.length; j += 1) {
+            const above = previous[j];
+            previous[j] = Math.min(above + 1, previous[j - 1] + 1, diagonal + (left[i - 1] === right[j - 1] ? 0 : 1));
+            diagonal = above;
+        }
+    }
+    return previous[right.length];
+}

package/dist/help.js

@@ -0,0 +1,167 @@
+import { readFileSync } from 'node:fs';
+export const GLOBAL_FLAGS = ['token', 'server', 'help'];
+export const BOOLEAN_FLAGS = new Set(['dry-run', 'force', 'headless', 'help']);
+export const COMMANDS = [
+    {
+        name: 'login',
+        summary: 'Sign in through the browser and store a CLI session',
+        usage: ['login [local] [--server <url>]'],
+        description: 'Opens the Skillshare sign-in page. If no browser opens, copy the printed URL into one.',
+        examples: ['skillshare login', 'skillshare login local'],
+        flags: [],
+    },
+    {
+        name: 'logout',
+        summary: 'Remove the stored CLI session',
+        usage: ['logout'],
+        flags: [],
+    },
+    {
+        name: 'whoami',
+        summary: 'Show the signed-in user',
+        usage: ['whoami'],
+        flags: [],
+    },
+    {
+        name: 'list',
+        summary: 'List skills in the registry',
+        usage: ['list'],
+        flags: [],
+    },
+    {
+        name: 'show',
+        summary: 'Show a skill or one of its versions',
+        usage: ['show <skillId> [version]'],
+        flags: [],
+    },
+    {
+        name: 'install',
+        summary: 'Install a skill for your coding agents',
+        usage: [
+            'install [skillId|skillName] [version]',
+            'install <skillId|skillName> [version] --target <directory> [--force]',
+            'install --skill-version-id <id> --target <directory> [--force]',
+        ],
+        description: 'Without --target the CLI asks for the version, scope and agents. Files that you changed locally are not overwritten unless you confirm or pass --force.',
+        options: [
+            ['--target <directory>', 'Install into this directory instead of agent skill folders'],
+            ['--skill-version-id <id>', 'Install an exact published skill version'],
+            ['--force', 'Overwrite local changes in the target directory'],
+        ],
+        examples: ['skillshare install', 'skillshare install "Prompt Lint"', 'skillshare install 12 0.1.0 --target ./installed'],
+        flags: ['target', 'skill-version-id', 'force'],
+    },
+    {
+        name: 'update',
+        summary: 'Update installed skills to their latest versions',
+        usage: ['update [skillId|skillName] [--target <directory>] [--dry-run] [--force]'],
+        description: 'Removes files that the new version no longer contains. Installs with local changes are skipped unless you pass --force.',
+        options: [
+            ['--target <directory>', 'Only update the install in this directory'],
+            ['--dry-run', 'Print planned changes without writing files'],
+            ['--force', 'Overwrite local changes'],
+        ],
+        examples: ['skillshare update', 'skillshare update "Prompt Lint" --dry-run'],
+        flags: ['target', 'dry-run', 'force'],
+    },
+    {
+        name: 'upload',
+        summary: 'Create a skill or publish a new version from a directory',
+        usage: ['upload <directory> --version <version> [--skill-id <id>] [--name <name>] [--description <text>]'],
+        options: [
+            ['--version <version>', 'Version to publish'],
+            ['--skill-id <id>', 'Publish to this existing skill'],
+            ['--name <name>', 'Name for a new skill (defaults to SKILL.md)'],
+            ['--description <text>', 'Description for a new skill (defaults to SKILL.md)'],
+        ],
+        examples: ['skillshare upload ./prompt-lint --version 0.2.0'],
+        flags: ['version', 'skill-id', 'name', 'description'],
+    },
+    {
+        name: 'pages',
+        summary: 'Publish and inspect authenticated pages',
+        usage: [
+            'pages list',
+            'pages show <slug>',
+            'pages runtime <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>]',
+        ],
+        examples: ['skillshare pages upload ./site --slug release-notes', 'skillshare pages dev . --slug my-app'],
+        flags: ['slug'],
+    },
+    {
+        name: 'teams',
+        summary: 'Connect Microsoft Teams to the Skillshare Teams MCP',
+        usage: [
+            'teams login [local] [--browser chrome|msedge|chromium] [--headless] [--browser-profile <directory>]',
+            'teams watch [local] [--browser chrome|msedge|chromium]',
+            'teams status | test | logout',
+            'teams access readOnly|fullAccess',
+            'teams upload <file>',
+            'teams download <url> --output <new-file>',
+        ],
+        flags: ['browser', 'headless', 'browser-profile', 'output'],
+    },
+    {
+        name: 'git',
+        summary: 'Register Skillshare in Git Credential Manager',
+        usage: ['git configure [local]', 'git unconfigure [local]'],
+        flags: [],
+    },
+];
+const COMMAND_ALIASES = { page: 'pages' };
+export function findCommand(name) {
+    if (!name)
+        return undefined;
+    const resolved = COMMAND_ALIASES[name] ?? name;
+    return COMMANDS.find((command) => command.name === resolved);
+}
+export function renderUsage(defaultUrl) {
+    const width = Math.max(...COMMANDS.map((command) => command.name.length));
+    return [
+        'Usage: skillshare [command] [options]',
+        '',
+        'Run without a command for the interactive mode.',
+        '',
+        'Commands:',
+        ...COMMANDS.map((command) => `  ${command.name.padEnd(width)}  ${command.summary}`),
+        '',
+        'Options:',
+        '  --token <token>  Bearer token for API requests (overrides SKILLSHARE_TOKEN)',
+        '  --server <url>   Skillshare origin for login and Teams commands',
+        '  -h, --help       Show help for a command',
+        '  -v, --version    Show the CLI version',
+        '',
+        `Default server: ${defaultUrl}`,
+        'A stored session keeps its server; run "skillshare login" to switch to the default.',
+        'Run "skillshare <command> --help" for details.',
+    ].join('\n');
+}
+export function renderCommandHelp(command) {
+    const lines = [`${command.summary}.`, '', 'Usage:', ...command.usage.map((usage) => `  skillshare ${usage}`)];
+    if (command.description)
+        lines.push('', command.description);
+    if (command.options?.length) {
+        const width = Math.max(...command.options.map(([flag]) => flag.length));
+        lines.push('', 'Options:', ...command.options.map(([flag, text]) => `  ${flag.padEnd(width)}  ${text}`));
+    }
+    if (command.examples?.length)
+        lines.push('', 'Examples:', ...command.examples.map((example) => `  ${example}`));
+    return lines.join('\n');
+}
+export function readCliVersion() {
+    // dist/index.js and the source index.ts sit at different depths below package.json.
+    for (const candidate of ['../package.json', './package.json']) {
+        try {
+            const parsed = JSON.parse(readFileSync(new URL(candidate, import.meta.url), 'utf8'));
+            if (parsed.name === '@quadient/skillshare' && parsed.version)
+                return parsed.version;
+        }
+        catch {
+            // Try the next location.
+        }
+    }
+    return 'unknown';
+}

package/dist/index.js

@@ -1,4 +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';
@@ -6,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';
@@ -68,45 +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>]
-  teams login [local] [--browser chrome|msedge|chromium] [--headless]
-  teams watch [local] [--browser chrome|msedge|chromium]
-  teams logout
-  teams status
-  teams test
-  teams access readOnly|fullAccess
-  teams upload <file>
-  teams download <url> --output <new-file>
-  git configure [local]
-  git unconfigure [local]
-
-Options:
-  --token <token>    Bearer token for API requests (overrides SKILLSHARE_TOKEN)
-  --server <url>     Skillshare origin for login and Teams commands
-
-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];
@@ -114,11 +79,29 @@ 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;
@@ -223,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>');
@@ -233,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,
@@ -262,6 +247,7 @@ async function main() {
                         await runInteractiveInstall(client, {
                             skillRef,
                             version,
+                            force,
                         });
                         return;
                     }
@@ -275,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,
@@ -305,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;
                 }
@@ -351,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))) {
@@ -387,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);
     }
@@ -404,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) {
@@ -440,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,
@@ -466,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
@@ -524,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) {
@@ -547,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}.`);
@@ -565,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}`);
@@ -594,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}.`);
@@ -605,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) {
@@ -749,7 +817,7 @@ async function promptForAgents(scope) {
             })),
         ],
         initialValues,
-        required: false,
+        required: true,
     });
     if (isCancel(selected)) {
         cancel('Cancelled.');
@@ -885,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;
@@ -925,6 +1043,7 @@ async function downloadResponseToFile(response, destination, onBytesTransferred)
                 continue;
             }
             await fileHandle.writeFile(value);
+            hash.update(value);
             onBytesTransferred?.(value.length);
         }
     }
@@ -934,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' });
@@ -1349,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: {
@@ -1373,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) {
@@ -1434,36 +1561,8 @@ function compareVersions(left, right) {
 function formatVersion(version) {
     return version.join('.');
 }
-async function parseOptions(args) {
-    const booleanFlags = new Set(['dry-run', 'headless']);
-    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 (key === 'headless' && value !== 'true' && value !== 'false') {
-                flags[key] = 'true';
-                continue;
-            }
-            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 {
@@ -1500,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',
@@ -1537,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),
         });
@@ -1545,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),
         });
@@ -1569,7 +1668,7 @@ async function createClient(baseUrl, explicitToken) {
         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;
         },
@@ -1624,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();
 }
@@ -1661,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) {
@@ -1767,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();
             }
         },
@@ -1832,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())
@@ -1842,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);
@@ -1883,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'));

package/dist/install-files.js

@@ -0,0 +1,111 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { mkdir, readdir, rename, rm, rmdir, stat } from 'node:fs/promises';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+export function resolveInsideRoot(root, relativePath) {
+    const resolvedRoot = resolve(root);
+    const destination = resolve(resolvedRoot, relativePath);
+    if (destination === resolvedRoot || !destination.startsWith(resolvedRoot + sep)) {
+        throw new Error(`Refusing to write '${relativePath}' outside ${resolvedRoot}.`);
+    }
+    return destination;
+}
+export async function hashFile(path) {
+    const hash = createHash('sha256');
+    for await (const chunk of createReadStream(path)) {
+        hash.update(chunk);
+    }
+    return hash.digest('hex');
+}
+/**
+ * Compares a target directory with the manifest recorded at install time.
+ * A record without a manifest predates change tracking and cannot be verified.
+ */
+export async function inspectInstallTarget(targetRoot, record) {
+    if (!await isNonEmptyDirectory(targetRoot)) {
+        return { state: 'missing' };
+    }
+    if (!record) {
+        return { state: 'untracked' };
+    }
+    if (!record.files) {
+        return { state: 'legacy' };
+    }
+    const modified = [];
+    for (const [relativePath, expectedHash] of Object.entries(record.files)) {
+        const path = resolveInsideRoot(targetRoot, relativePath);
+        try {
+            if (await hashFile(path) !== expectedHash)
+                modified.push(relativePath);
+        }
+        catch (error) {
+            if (error?.code !== 'ENOENT')
+                throw error;
+            modified.push(relativePath);
+        }
+    }
+    return modified.length > 0 ? { state: 'modified', paths: modified } : { state: 'clean' };
+}
+/**
+ * Downloads every file into a sibling staging directory first, so a failed transfer
+ * leaves the existing install untouched. Files from the previous manifest that the
+ * new version no longer contains are removed afterwards.
+ */
+export async function installFilesAtomically(input) {
+    const targetRoot = resolve(input.targetRoot);
+    const stagingRoot = join(dirname(targetRoot), `.${basename(targetRoot)}.skillshare-${randomBytes(4).toString('hex')}`);
+    const manifest = {};
+    await mkdir(stagingRoot, { recursive: true });
+    try {
+        for (const file of input.files) {
+            const stagedPath = resolveInsideRoot(stagingRoot, file.relativePath);
+            resolveInsideRoot(targetRoot, file.relativePath);
+            await mkdir(dirname(stagedPath), { recursive: true });
+            manifest[normalizeRelativePath(file.relativePath)] = await input.download(file.relativePath, stagedPath);
+        }
+        await mkdir(targetRoot, { recursive: true });
+        for (const relativePath of Object.keys(manifest)) {
+            const destination = resolveInsideRoot(targetRoot, relativePath);
+            await mkdir(dirname(destination), { recursive: true });
+            await rename(resolveInsideRoot(stagingRoot, relativePath), destination);
+        }
+        for (const relativePath of Object.keys(input.previousManifest ?? {})) {
+            if (relativePath in manifest)
+                continue;
+            const stalePath = resolveInsideRoot(targetRoot, relativePath);
+            await rm(stalePath, { force: true });
+            await removeEmptyParents(dirname(stalePath), targetRoot);
+        }
+    }
+    finally {
+        await rm(stagingRoot, { recursive: true, force: true });
+    }
+    return manifest;
+}
+function normalizeRelativePath(path) {
+    return relative('.', join('.', path)).replaceAll('\\', '/');
+}
+async function isNonEmptyDirectory(path) {
+    try {
+        if (!(await stat(path)).isDirectory())
+            return true;
+        return (await readdir(path)).length > 0;
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+async function removeEmptyParents(directory, root) {
+    let current = resolve(directory);
+    while (current !== root && current.startsWith(root + sep)) {
+        try {
+            await rmdir(current);
+        }
+        catch {
+            return;
+        }
+        current = dirname(current);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quadient/skillshare",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Skillshare CLI for installing and publishing Quadient skills",
   "type": "module",
   "bin": {
@@ -16,7 +16,7 @@
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
     "start": "node ./dist/index.js",
     "prepublishOnly": "npm run build",
-    "test": "tsx --test pages.test.ts pages-dev.test.ts teams-auth.test.ts teams-watch.test.ts teams-browser.test.ts"
+    "test": "tsx --test cli-args.test.ts install-files.test.ts pages.test.ts pages-dev.test.ts teams-auth.test.ts teams-watch.test.ts teams-browser.test.ts"
   },
   "publishConfig": {
     "access": "public"