@quadient/skillshare 1.6.2 → 1.8.0

package/README.md

@@ -19,8 +19,45 @@ bun run index.ts install 12 0.1.0 --target ./installed
 bun run index.ts install --skill-version-id 42 --target ./installed
 ```
 
+## Teams MCP
+
+Starting with 1.7.0, `skillshare teams login` opens a dedicated local browser profile,
+connects your own Teams account to Skillshare and verifies the connection. Sign in with
+the same Microsoft account as Skillshare. The server refreshes captured tokens in the
+background. `teams watch` renews an expired Microsoft grant through local browser SSO.
+Keep that process running for automatic recovery beyond the SPA refresh token lifetime;
+another interactive CLI login is needed only when SSO cannot complete, for example MFA.
+
+```sh
+skillshare login
+skillshare teams login
+skillshare teams status
+skillshare teams test
+skillshare teams watch
+skillshare teams access fullAccess
+skillshare teams upload ./report.pdf
+skillshare teams download '<file-webUrl-or-download-link>' --output ./report.pdf
+skillshare teams access readOnly
+skillshare teams logout
+```
+
+Use `teams login local` for localhost or `--server <https-origin>` for another host.
+`login` accepts `--server` too. Browser options: `--browser chrome|msedge|chromium`,
+`--headless`, and `--browser-profile <dedicated-profile-directory>`.
+Chrome is the default on macOS/Linux, Edge on Windows; bundled Chromium needs
+`npx playwright install chromium` first. See [Teams MCP](../docs/teams-mcp.md) for
+permissions, Microsoft session lifetime and file-tool differences in the hosted server.
+
 ## 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';
+}