@quadient/skillshare 1.8.1 → 1.10.0

package/dist/agents.js

@@ -0,0 +1,230 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { hostname, platform } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { createClaudeDriver } from './agents-claude.js';
+import { createCodexDriver } from './agents-codex.js';
+import { detectAgents, profilesPath } from './agents-detect.js';
+import { SessionRunner } from './agents-session.js';
+import { readCliVersion } from './help.js';
+const root = '/api/agents';
+const PROFILE_HINT = 'Declare named profiles in ' + profilesPath() + ' to set a working directory or extra arguments.';
+export class AgentsHttpError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+async function send(client, method, path, body, signal) {
+    const response = await client.request(path, { method, headers: { 'Content-Type': 'application/json', Accept: 'application/json' }, body: JSON.stringify(body), signal });
+    if (!response.ok) {
+        let message = `Skillshare returned HTTP ${response.status}.`;
+        try {
+            message = (await response.json()).error ?? message;
+        }
+        catch { }
+        throw new AgentsHttpError(response.status, message);
+    }
+    return response.status === 204 ? undefined : await response.json();
+}
+/** One stable listener id per Skillshare server and account, so the web keeps routes across restarts. */
+export async function loadListenerId(appDirectory, baseUrl, userId) {
+    const key = createHash('sha256').update(baseUrl + '\0' + userId).digest('hex').slice(0, 24);
+    const file = join(appDirectory, 'agents', `listener-${key}.json`);
+    try {
+        const stored = JSON.parse(await readFile(file, 'utf8'));
+        if (typeof stored.id === 'string' && /^[A-Za-z0-9_-]{8,64}$/.test(stored.id))
+            return stored.id;
+    }
+    catch { }
+    const id = randomBytes(12).toString('base64url');
+    await mkdir(dirname(file), { recursive: true, mode: 0o700 });
+    await writeFile(file, JSON.stringify({ id }, null, 2), { mode: 0o600 });
+    return id;
+}
+export async function runAgentsCommand(client, args, flags, appDirectory) {
+    const action = args[0];
+    if (action === 'status') {
+        const detected = await detectAgents();
+        const user = await client.get('/api/auth/me');
+        const listenerId = await loadListenerId(appDirectory, client.baseUrl, user.id);
+        if (flags.json === 'true') {
+            console.log(JSON.stringify({ listenerId, server: client.baseUrl, ...detected.capabilities, problems: detected.problems }, null, 2));
+            return;
+        }
+        console.log(renderDetected(listenerId, client.baseUrl, detected));
+        return;
+    }
+    if (action !== 'listen')
+        throw new Error('agents requires listen or status.');
+    const max = flags['max-concurrency'] === undefined ? undefined : Number(flags['max-concurrency']);
+    if (max !== undefined && (!Number.isInteger(max) || max < 1 || max > 4))
+        throw new Error('--max-concurrency must be between 1 and 4.');
+    const workdir = resolve(flags.workdir ?? process.cwd());
+    const sandbox = flags.sandbox === 'true';
+    const user = await client.get('/api/auth/me');
+    const listenerId = await loadListenerId(appDirectory, client.baseUrl, user.id);
+    const abort = new AbortController();
+    const stop = () => abort.abort();
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+    console.log(sandbox
+        ? 'Sandboxed: agents may read files, search and use the Skillshare MCP tools, but cannot change files or run commands that modify anything.'
+        : 'Agents run with your full local permissions and configuration, without permission prompts. Use --sandbox to keep them read-only.');
+    console.log('Sessions keep their agent running between messages and close it after 15 quiet minutes; the next message resumes it.');
+    try {
+        await listen({ client, listenerId, name: flags.name, workdir, maxConcurrency: max, sandbox, signal: abort.signal, onProgress: console.log });
+    }
+    finally {
+        process.removeListener('SIGINT', stop);
+        process.removeListener('SIGTERM', stop);
+    }
+}
+export function renderDetected(listenerId, server, detected) {
+    const lines = [`Listener ${listenerId} on ${server}`];
+    if (detected.capabilities.agents.length === 0)
+        lines.push('No supported agent found. Install Claude Code (claude) or Codex (codex) and make sure it is on PATH.');
+    for (const agent of detected.capabilities.agents) {
+        lines.push(`${agent.kind === 'claude' ? 'Claude Code' : 'Codex'} ${agent.version ?? ''}`.trimEnd());
+        for (const model of agent.models)
+            lines.push(`  ${model.id}${model.reasoningLevels.length ? `  (${model.reasoningLevels.join(', ')})` : ''}`);
+        for (const warning of agent.warnings)
+            lines.push(`  ! ${warning}`);
+    }
+    if (detected.profiles.length === 0)
+        lines.push(PROFILE_HINT);
+    for (const profile of detected.profiles)
+        lines.push(`Profile ${profile.name}: ${profile.agent}${profile.model ? ' ' + profile.model : ''}${profile.reasoning ? ' ' + profile.reasoning : ''}${profile.workdir ? ' in ' + profile.workdir : ''}${profile.sandbox ? ' (sandbox)' : ''}`);
+    for (const problem of detected.problems)
+        lines.push(`! ${problem}`);
+    return lines.join('\n');
+}
+export async function listen(options) {
+    const detect = options.detect ?? (() => detectAgents());
+    const codex = createCodexDriver({ clientVersion: readCliVersion() });
+    const claude = createClaudeDriver();
+    const driver = options.driver ?? (start => start.configuration.agent === 'codex' ? codex : claude);
+    const wait = options.wait ?? (async (ms, signal) => { await delay(ms, undefined, { signal }); });
+    const now = options.now ?? Date.now;
+    const log = options.onProgress ?? (() => { });
+    const sessions = new Map();
+    let detected = await detect();
+    let registeredFingerprint = '';
+    let detectedAt = now();
+    let failures = 0;
+    const capabilities = () => options.sandbox ? { ...detected.capabilities, sandbox: true } : detected.capabilities;
+    async function register() {
+        const fingerprint = JSON.stringify(capabilities());
+        const registered = await send(options.client, 'PUT', `${root}/listeners/${options.listenerId}`, {
+            name: options.name ?? hostname(), host: hostname(), os: platform(), cliVersion: readCliVersion(), maxConcurrency: options.maxConcurrency,
+            capabilities: capabilities(),
+        }, options.signal);
+        registeredFingerprint = fingerprint;
+        for (const problem of detected.problems)
+            log(`! ${problem}`);
+        log(`Listening as "${registered.name}" with ${registered.effectiveConcurrency} slot(s): ${describe(detected)}. Start sessions and choose routes under Connected agents on ${options.client.baseUrl}.`);
+    }
+    /** Posts a batch of session events: a rejected lease means the server moved on and the agent must stop. */
+    function uploader(sessionId, leaseToken) {
+        return async (events) => {
+            try {
+                await send(options.client, 'POST', `${root}/sessions/${sessionId}/events`, { leaseToken, events });
+                return 'ok';
+            }
+            catch (error) {
+                if (error instanceof AgentsHttpError && error.status >= 400 && error.status < 500)
+                    return 'gone';
+                return 'retry';
+            }
+        };
+    }
+    function start(command) {
+        if (!command.start || !command.leaseToken)
+            return;
+        // A start for a session already held replaces its agent, for example to hand it fresh credentials.
+        const previous = sessions.get(command.sessionId);
+        if (previous)
+            void previous.stop();
+        const profile = command.start.configuration.profile ? detected.profiles.find(p => p.name === command.start.configuration.profile) : undefined;
+        const runner = new SessionRunner({
+            sessionId: command.sessionId, leaseToken: command.leaseToken, start: command.start, workdir: options.workdir, profile, sandbox: options.sandbox === true,
+            driver: driver(command.start), upload: uploader(command.sessionId, command.leaseToken), idleMs: options.idleMs, flushIntervalMs: options.flushIntervalMs,
+            now,
+        });
+        sessions.set(command.sessionId, runner);
+        log(`${command.start.resumeThreadId ? 'Resumed' : 'Started'} session ${command.sessionId} "${command.start.title}" with ${label(command.start)}.`);
+        void runner.done.then(() => {
+            if (sessions.get(command.sessionId) === runner)
+                sessions.delete(command.sessionId);
+            log(`Closed session ${command.sessionId}.`);
+        });
+        runner.send(command.messages ?? []);
+    }
+    function handle(command) {
+        const runner = sessions.get(command.sessionId);
+        switch (command.type) {
+            case 'start': return start(command);
+            case 'send': return runner?.send(command.messages ?? []);
+            case 'interrupt': return void runner?.interrupt();
+            case 'close': return void runner?.close();
+        }
+    }
+    try {
+        while (!options.signal.aborted) {
+            try {
+                if (now() - detectedAt > (options.redetectMs ?? 5 * 60_000)) {
+                    detected = await detect();
+                    detectedAt = now();
+                }
+                if (registeredFingerprint !== JSON.stringify(capabilities()))
+                    await register();
+                const polledAt = now();
+                const response = await send(options.client, 'POST', `${root}/listeners/${options.listenerId}/poll`, {
+                    // A session that is already closing is not reported, so the server treats its agent as gone.
+                    sessions: [...sessions.values()].filter(r => !r.stopping).map(r => ({ sessionId: r.sessionId, leaseToken: r.leaseToken })),
+                    waitSeconds: options.pollWaitSeconds ?? 25,
+                }, options.signal);
+                failures = 0;
+                for (const command of response.commands)
+                    handle(command);
+                if (response.commands.length === 0 && now() - polledAt < 1000)
+                    await wait(1000, options.signal).catch(() => { });
+            }
+            catch (error) {
+                if (options.signal.aborted)
+                    break;
+                if (error instanceof AgentsHttpError && error.status === 404) {
+                    registeredFingerprint = '';
+                    continue;
+                }
+                failures++;
+                if (failures === 1)
+                    log(`Skillshare is unreachable or rejected the listener (${error instanceof Error ? error.message : String(error)}). Retrying.`);
+                try {
+                    await wait(Math.min(60_000, 2000 * 2 ** Math.min(failures, 5)), options.signal);
+                }
+                catch {
+                    break;
+                }
+            }
+        }
+    }
+    finally {
+        // Closing reports each session as closed, so the server knows at once that the next message must resume it.
+        await Promise.all([...sessions.values()].map(runner => runner.close()));
+    }
+}
+function label(start) {
+    const { configuration } = start;
+    if (configuration.profile)
+        return `profile ${configuration.profile}`;
+    return [configuration.agent === 'claude' ? 'Claude Code' : 'Codex', configuration.model, configuration.reasoning]
+        .filter(part => part !== 'default').join(' ');
+}
+function describe(detected) {
+    const agents = detected.capabilities.agents.map(a => `${a.kind === 'claude' ? 'Claude Code' : 'Codex'} ${a.version ?? ''}`.trim());
+    const profiles = detected.profiles.length ? `, profiles ${detected.profiles.map(p => p.name).join(', ')}` : '';
+    return (agents.length ? agents.join(', ') : 'no supported agent found') + profiles;
+}

package/dist/help.js

@@ -1,6 +1,6 @@
 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 BOOLEAN_FLAGS = new Set(['dry-run', 'force', 'headless', 'help', 'json', 'sandbox']);
 export const COMMANDS = [
     {
         name: 'login',
@@ -19,20 +19,21 @@ export const COMMANDS = [
     {
         name: 'whoami',
         summary: 'Show the signed-in user',
-        usage: ['whoami'],
-        flags: [],
+        usage: ['whoami [--json]'],
+        flags: ['json'],
     },
     {
         name: 'list',
         summary: 'List skills in the registry',
-        usage: ['list'],
-        flags: [],
+        usage: ['list [--json]'],
+        flags: ['json'],
     },
     {
         name: 'show',
         summary: 'Show a skill or one of its versions',
-        usage: ['show <skillId> [version]'],
-        flags: [],
+        usage: ['show <skillId|skillName> [version] [--json]'],
+        examples: ['skillshare show "Prompt Lint"', 'skillshare show 12 0.1.0 --json'],
+        flags: ['json'],
     },
     {
         name: 'install',
@@ -73,23 +74,25 @@ export const COMMANDS = [
             ['--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)'],
+            ['--json', 'Print the server response as JSON'],
         ],
         examples: ['skillshare upload ./prompt-lint --version 0.2.0'],
-        flags: ['version', 'skill-id', 'name', 'description'],
+        flags: ['version', 'skill-id', 'name', 'description', 'json'],
     },
     {
         name: 'pages',
         summary: 'Publish and inspect authenticated pages',
         usage: [
-            'pages list',
-            'pages show <slug>',
-            'pages runtime <slug>',
-            'pages upload <directory> [--slug <slug>]',
+            'pages list [--json]',
+            'pages show <slug> [--json]',
+            'pages runtime <slug> [--json]',
+            'pages upload <directory> [--slug <slug>] [--json]',
             'pages dev [directory] [--slug <slug>] [--port <port>] [--build <command> --watch-dir <sources>]',
             '  [--celld <executable>] [--user-id <id>] [--user-name <name>] [--user-email <email>]',
         ],
+        description: 'An upload replaces all content of the page. Without --slug the directory name is used; build output folders such as dist need an explicit --slug. Pages owned by someone else are refused unless you are an admin.',
         examples: ['skillshare pages upload ./site --slug release-notes', 'skillshare pages dev . --slug my-app'],
-        flags: ['slug'],
+        flags: ['slug', 'json'],
     },
     {
         name: 'teams',
@@ -97,12 +100,24 @@ export const COMMANDS = [
         usage: [
             'teams login [local] [--browser chrome|msedge|chromium] [--headless] [--browser-profile <directory>]',
             'teams watch [local] [--browser chrome|msedge|chromium]',
-            'teams status | test | logout',
+            'teams status | test [--json]',
+            'teams logout',
             'teams access readOnly|fullAccess',
             'teams upload <file>',
             'teams download <url> --output <new-file>',
         ],
-        flags: ['browser', 'headless', 'browser-profile', 'output'],
+        flags: ['browser', 'headless', 'browser-profile', 'output', 'json'],
+    },
+    {
+        name: 'agents',
+        summary: 'Run Claude Code or Codex tasks from Skillshare on this computer',
+        usage: [
+            'agents listen [local] [--name <name>] [--workdir <directory>] [--max-concurrency <1-4>] [--sandbox]',
+            'agents status [local] [--json]',
+        ],
+        description: 'A listener reports the installed agents, their models and reasoning levels, and the local profiles from ~/.config/skillshare/agents.json. It runs Claude Code and Codex sessions that you start and continue under Sessions in Skillshare; under Connected agents you choose which listener and configuration runs Teams 👀 sessions. Agents use your own login and run with your full local permissions, without permission prompts, unless --sandbox (or "sandbox": true in a profile) keeps them read-only. An idle agent is stopped after 15 minutes and resumed by the next message.',
+        examples: ['skillshare agents status', 'skillshare agents listen --workdir ~/Research'],
+        flags: ['name', 'workdir', 'max-concurrency', 'sandbox', 'json'],
     },
     {
         name: 'git',
@@ -131,6 +146,7 @@ export function renderUsage(defaultUrl) {
         'Options:',
         '  --token <token>  Bearer token for API requests (overrides SKILLSHARE_TOKEN)',
         '  --server <url>   Skillshare origin for login and Teams commands',
+        '  --json           Print machine-readable JSON (whoami, list, show, upload, pages, teams, agents)',
         '  -h, --help       Show help for a command',
         '  -v, --version    Show the CLI version',
         '',

package/dist/index.js

@@ -1,8 +1,10 @@
 import { assertCredentialDestination, resolveTeamsObjectId, runTeamsCommand } from './teams.js';
+import { runAgentsCommand } from './agents.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 { preparePageFiles, resolvePageSlug } from './pages.js';
+import { formatByteSize, formatDateTime, pageUrl, plural, renderPageDetail, renderPageList, renderPageRuntime, renderSkillDetail, renderSkillList, renderSkillVersion, renderUser, } from './output.js';
 import { runPageDev } from './pages-dev.js';
 import { createServer } from 'node:http';
 import { createHash, randomBytes } from 'node:crypto';
@@ -72,6 +74,8 @@ const AGENTS = [
     { value: 'adal', label: 'AdaL', projectPath: '.adal/skills', globalPath: '.adal/skills' },
 ];
 const LOGIN_TIMEOUT_MS = 5 * 60_000;
+// Progress goes to stderr with --json so stdout stays machine-readable.
+let statusOutput = process.stdout;
 async function main() {
     const args = process.argv.slice(2);
     const command = args[0];
@@ -102,6 +106,13 @@ async function main() {
         console.log(renderCommandHelp(commandSpec));
         return;
     }
+    const json = isFlagEnabled(options.flags, 'json');
+    if (json) {
+        statusOutput = process.stderr;
+    }
+    const print = (value, human) => {
+        console.log(json ? JSON.stringify(value, null, 2) : human());
+    };
     if ((command === 'pages' || command === 'page') && options.positionals[0] === 'dev') {
         await runPageDev(options.positionals[1] ?? '.', options.flags);
         return;
@@ -133,6 +144,14 @@ async function main() {
             await runTeamsCommand(teamsClient, options.positionals, options.flags, APP_DIR);
             return;
         }
+        case 'agents': {
+            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 runAgentsCommand(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;
@@ -159,27 +178,28 @@ async function main() {
             switch (command) {
                 case 'whoami': {
                     const user = await client.get('/api/auth/me');
-                    console.log(JSON.stringify(user, null, 2));
+                    print(user, () => renderUser(user, client.baseUrl));
                     return;
                 }
                 case 'list': {
                     const skills = await client.get('/api/skills');
-                    for (const skill of skills) {
-                        console.log(`${skill.id}\t${skill.latestVersion}\t${skill.name}`);
-                    }
+                    print(skills, () => renderSkillList(skills));
                     return;
                 }
                 case 'show': {
-                    const skillId = options.positionals[0];
+                    const skillRef = options.positionals[0];
                     const version = options.positionals[1];
-                    if (!skillId) {
-                        throw new Error('show requires <skillId>');
+                    if (!skillRef) {
+                        throw new Error('show requires <skillId|skillName>');
                     }
-                    const resource = version
-                        ? `/api/skills/${skillId}/versions/${version}`
-                        : `/api/skills/${skillId}`;
-                    const data = await client.get(resource);
-                    console.log(JSON.stringify(data, null, 2));
+                    const skill = resolveSkillReference(await client.get('/api/skills'), skillRef);
+                    if (version) {
+                        const detail = await client.get(`/api/skills/${skill.id}/versions/${encodeURIComponent(version)}`);
+                        print(detail, () => renderSkillVersion(skill.name, detail));
+                        return;
+                    }
+                    const detail = await client.get(`/api/skills/${skill.id}`);
+                    print(detail, () => renderSkillDetail(detail));
                     return;
                 }
                 case 'upload': {
@@ -198,14 +218,14 @@ async function main() {
                             description: options.flags.description,
                             version,
                         });
-                        console.log(JSON.stringify(created.response, null, 2));
+                        print(created.response, () => `Created skill #${created.detail.id} "${created.detail.name}" with version ${version}.`);
                     }
                     else {
                         const published = await publishSkillFromDirectory(client, localSkill, {
                             skillId: existingSkill.id,
                             version,
                         });
-                        console.log(JSON.stringify(published.response, null, 2));
+                        print(published.response, () => `Published ${published.detail.name}@${published.response.version} (skill #${published.detail.id}).`);
                     }
                     return;
                 }
@@ -309,16 +329,21 @@ async function main() {
                     const action = options.positionals[0] ?? 'list';
                     if (action === 'list') {
                         const pages = await client.get('/api/pages');
-                        for (const page of pages) {
-                            console.log(`${page.slug}\t${page.kind}\t${page.fileCount}\t${page.ownerDisplayName}`);
-                        }
+                        print(pages, () => renderPageList(pages));
                         return;
                     }
                     if (action === 'show' || action === 'runtime') {
                         const slug = options.positionals[1];
                         if (!slug)
                             throw new Error(`pages ${action} requires <slug>`);
-                        console.log(JSON.stringify(await client.get(`/api/pages/${encodeURIComponent(slug)}${action === 'runtime' ? '/runtime' : ''}`), null, 2));
+                        if (action === 'show') {
+                            const page = await client.get(`/api/pages/${encodeURIComponent(slug)}`);
+                            print(page, () => renderPageDetail(page, client.baseUrl));
+                        }
+                        else {
+                            const runtime = await client.get(`/api/pages/${encodeURIComponent(slug)}/runtime`);
+                            print(runtime, () => renderPageRuntime(slug, runtime));
+                        }
                         return;
                     }
                     if (action === 'upload') {
@@ -326,14 +351,15 @@ async function main() {
                         if (!directory)
                             throw new Error('pages upload requires <directory>');
                         const resolvedDirectory = resolve(directory);
-                        const slug = normalizePageSlug(options.flags.slug ?? basename(resolvedDirectory));
+                        const slug = resolvePageSlug(resolvedDirectory, options.flags.slug);
+                        const existing = await describePageUploadTarget(client, slug);
                         const pageFiles = await loadLocalPageFiles(resolvedDirectory);
-                        const uploadStatus = spinner({ indicator: 'timer' });
-                        uploadStatus.start(`Uploading ${pageFiles.files.length} files (${formatByteSize(pageFiles.totalBytes)}) to /p/${slug}/`);
+                        const uploadStatus = spinner({ indicator: 'timer', output: statusOutput });
+                        uploadStatus.start(`${existing ? 'Replacing' : 'Creating'} /p/${slug}/ with ${plural(pageFiles.files.length, 'file')} (${formatByteSize(pageFiles.totalBytes)})`);
                         try {
                             const detail = await client.replacePageContent(slug, pageFiles.files);
-                            uploadStatus.stop(`Published /p/${detail.slug}/ with ${detail.files.length} files`);
-                            console.log(JSON.stringify(detail, null, 2));
+                            uploadStatus.stop(`Published /p/${detail.slug}/ as revision ${detail.contentRevision} with ${plural(detail.files.length, 'file')}`);
+                            print(detail, () => `Open ${pageUrl(client.baseUrl, detail.slug)}`);
                         }
                         catch (error) {
                             uploadStatus.clear();
@@ -409,7 +435,7 @@ async function checkInstalledSkillsForUpdates(client) {
     if (records.length === 0) {
         return [];
     }
-    const status = spinner();
+    const status = spinner({ output: statusOutput });
     status.start(`Checking ${records.length} installed skill${records.length === 1 ? '' : 's'} for updates`);
     const problems = [];
     try {
@@ -867,7 +893,7 @@ async function promptConfirm(message, initialValue = false) {
 }
 async function loadLocalSkillContext(directory, baseUrl) {
     const resolvedDirectory = resolve(directory);
-    const scanStatus = spinner({ indicator: 'timer' });
+    const scanStatus = spinner({ indicator: 'timer', output: statusOutput });
     scanStatus.start(`Scanning ${resolvedDirectory}`);
     let filePlans;
     try {
@@ -879,7 +905,7 @@ async function loadLocalSkillContext(directory, baseUrl) {
     }
     scanStatus.stop(`Found ${filePlans.length} file${filePlans.length === 1 ? '' : 's'} in ${resolvedDirectory}`);
     const totalBytes = filePlans.reduce((sum, file) => sum + file.size, 0);
-    const readProgress = progress({ max: Math.max(filePlans.length, 1), size: 32 });
+    const readProgress = progress({ max: Math.max(filePlans.length, 1), size: 32, output: statusOutput });
     if (filePlans.length > 0) {
         readProgress.start(`Reading files 0/${filePlans.length}`);
     }
@@ -919,7 +945,7 @@ async function loadLocalPageFiles(directory) {
 async function createSkillFromDirectory(client, localSkill, input) {
     const name = normalizeText(input.name) ?? localSkill.defaults.name;
     const description = normalizeText(input.description) ?? localSkill.defaults.description;
-    const uploadStatus = spinner({ indicator: 'timer' });
+    const uploadStatus = spinner({ indicator: 'timer', output: statusOutput });
     uploadStatus.start(`Uploading ${localSkill.files.length} file${localSkill.files.length === 1 ? '' : 's'} (${formatByteSize(localSkill.totalBytes)})`);
     try {
         const response = await client.createSkill({
@@ -940,7 +966,7 @@ async function createSkillFromDirectory(client, localSkill, input) {
     }
 }
 async function publishSkillFromDirectory(client, localSkill, input) {
-    const uploadStatus = spinner({ indicator: 'timer' });
+    const uploadStatus = spinner({ indicator: 'timer', output: statusOutput });
     uploadStatus.start(`Uploading ${localSkill.files.length} file${localSkill.files.length === 1 ? '' : 's'} (${formatByteSize(localSkill.totalBytes)})`);
     try {
         const response = await client.publishVersion({
@@ -1064,7 +1090,7 @@ async function downloadResponseToFile(response, destination, onBytesTransferred)
     return hash.digest('hex');
 }
 function createInstallProgressReporter(input) {
-    const installStatus = spinner({ indicator: 'timer' });
+    const installStatus = spinner({ indicator: 'timer', output: statusOutput });
     const state = {
         completedFiles: 0,
         completedTargets: 0,
@@ -1327,12 +1353,30 @@ function normalizeText(value) {
     const trimmed = value?.trim();
     return trimmed ? trimmed : null;
 }
-function normalizePageSlug(value) {
-    const normalized = value.trim().toLowerCase();
-    if (!/^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/.test(normalized)) {
-        throw new Error('Page slug must be 1-64 lowercase letters, numbers, or hyphens, and cannot start or end with a hyphen.');
+/**
+ * Reports whether an upload replaces an existing page and stops before uploading when the
+ * page belongs to someone else, so a reused slug is noticed before any files are sent.
+ */
+async function describePageUploadTarget(client, slug) {
+    let page;
+    try {
+        page = await client.get(`/api/pages/${encodeURIComponent(slug)}`);
     }
-    return normalized;
+    catch (error) {
+        if (error instanceof HttpError && error.status === 404) {
+            statusOutput.write(`Creating a new page /p/${slug}/.\n`);
+            return null;
+        }
+        throw error;
+    }
+    const me = await client.get('/api/auth/me');
+    const isOwner = me.storedUserId != null && me.storedUserId === page.ownerUserId;
+    if (!isOwner && !me.isAdmin) {
+        throw new Error(`Page /p/${slug}/ belongs to ${page.ownerDisplayName}. Choose another --slug.`);
+    }
+    statusOutput.write(`Replacing all content of /p/${slug}/ (revision ${page.contentRevision}, ${plural(page.files.length, 'file')}, updated ${formatDateTime(page.updated)}).\n`
+        + (isOwner ? '' : `Warning: this page belongs to ${page.ownerDisplayName}; you are replacing it as an admin.\n`));
+    return page;
 }
 async function resolveExistingUploadSkill(client, localSkill, options) {
     const explicitSkillId = normalizeText(options?.explicitSkillId);
@@ -2162,20 +2206,6 @@ function guessContentType(path) {
         return 'font/woff2';
     return 'application/octet-stream';
 }
-function formatByteSize(bytes) {
-    if (!Number.isFinite(bytes) || bytes <= 0) {
-        return '0 B';
-    }
-    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
-    let value = bytes;
-    let unitIndex = 0;
-    while (value >= 1024 && unitIndex < units.length - 1) {
-        value /= 1024;
-        unitIndex += 1;
-    }
-    const decimals = value >= 10 || unitIndex === 0 ? 0 : 1;
-    return `${value.toFixed(decimals)} ${units[unitIndex]}`;
-}
 function normalizeBaseUrl(url) {
     return url.replace(/\/+$/, '');
 }