brainclaw 0.19.11 → 0.19.14

package/dist/core/brainclaw-version.js

@@ -1,11 +1,20 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { BrainclawLocalReleaseManifestSchema, } from './schema.js';
 export const DEFAULT_LOCAL_RELEASES_DIR = '.releases';
 export const DEFAULT_LOCAL_RELEASE_MANIFEST_PATH = `${DEFAULT_LOCAL_RELEASES_DIR}/brainclaw-local.json`;
+export const DEFAULT_NPM_UPDATE_PACKAGE = 'brainclaw';
+export const DEFAULT_NPM_UPDATE_DIST_TAG = 'latest';
+export const DEFAULT_INSTALLABLE_UPDATE_CACHE_TTL_MS = 6 * 60 * 60 * 1000;
 const SEMVER_RE = /^v?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+const DEFAULT_NPM_UPDATE_SOURCE = {
+    type: 'npm',
+    package_name: DEFAULT_NPM_UPDATE_PACKAGE,
+    dist_tag: DEFAULT_NPM_UPDATE_DIST_TAG,
+};
 let cachedCliVersion;
 export function getInstalledBrainclawVersion() {
     if (cachedCliVersion) {
@@ -87,8 +96,10 @@ export function assessBrainclawVersion(config) {
         message,
     };
 }
-export function checkBrainclawInstallableUpdate(config, cwd) {
-    const source = config?.brainclaw_update_source;
+export function checkBrainclawInstallableUpdate(config, cwd, options = {}) {
+    const source = config?.brainclaw_update_source
+        ?? (options.useDefaultNpmSource ? DEFAULT_NPM_UPDATE_SOURCE : undefined);
+    const defaultSource = !config?.brainclaw_update_source && source?.type === 'npm';
     if (!source) {
         return {
             checked: false,
@@ -103,22 +114,181 @@ export function checkBrainclawInstallableUpdate(config, cwd) {
         };
     }
     if (source.type === 'npm') {
-        const packageName = source.package_name?.trim() || 'brainclaw';
-        const distTag = source.dist_tag?.trim() || 'latest';
+        return checkNpmInstallableUpdate(source, config, cwd, options, defaultSource);
+    }
+    return checkLocalPackInstallableUpdate(source.manifest_path, config, cwd);
+}
+export function renderBrainclawInstallableUpdateNotice(updateCheck) {
+    if (!updateCheck || updateCheck.status !== 'update_available') {
+        return null;
+    }
+    const lines = [updateCheck.message];
+    if (updateCheck.install_command) {
+        lines.push(`Install: ${updateCheck.install_command}`);
+    }
+    if (updateCheck.release_notes) {
+        lines.push(`Why update: ${updateCheck.release_notes}`);
+    }
+    return lines.join('\n');
+}
+export function publishLocalBrainclawRelease(cwd, options = {}) {
+    const workspacePackage = readWorkspaceBrainclawPackage(cwd);
+    const outputDir = path.resolve(cwd, options.outputDir ?? DEFAULT_LOCAL_RELEASES_DIR);
+    const manifestPath = path.resolve(cwd, options.manifestPath ?? DEFAULT_LOCAL_RELEASE_MANIFEST_PATH);
+    fs.mkdirSync(outputDir, { recursive: true });
+    fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+    const packResult = spawnSync(resolveNpmCommand(), resolveNpmPackArgs(outputDir), {
+        cwd,
+        encoding: 'utf-8',
+        timeout: 120000,
+    });
+    if (packResult.error) {
+        throw new Error(`Failed to run npm pack: ${packResult.error.message}`);
+    }
+    if (packResult.status !== 0) {
+        throw new Error(firstNonEmptyLine(packResult.stderr) ?? firstNonEmptyLine(packResult.stdout) ?? 'npm pack failed');
+    }
+    const artifactFilename = parsePackedFilename(packResult.stdout);
+    if (!artifactFilename) {
+        throw new Error('npm pack did not report the generated tarball filename.');
+    }
+    const artifactAbsolutePath = path.join(outputDir, artifactFilename);
+    if (!fs.existsSync(artifactAbsolutePath)) {
+        throw new Error(`npm pack reported ${artifactFilename}, but the tarball was not found in ${outputDir}.`);
+    }
+    const manifestArtifactPath = toManifestRelativePath(path.relative(path.dirname(manifestPath), artifactAbsolutePath));
+    const projectArtifactPath = toManifestRelativePath(path.relative(cwd, artifactAbsolutePath));
+    const projectManifestPath = toPortablePath(path.relative(cwd, manifestPath));
+    const installCommand = `npm install -g "${projectArtifactPath}"`;
+    const releaseNotes = options.releaseNotes?.trim() || null;
+    const manifest = BrainclawLocalReleaseManifestSchema.parse({
+        version: 1,
+        channel: 'local-pack',
+        package_name: workspacePackage.name,
+        latest_installable_version: workspacePackage.version,
+        published_at: new Date().toISOString(),
+        artifact_path: manifestArtifactPath,
+        install_command: installCommand,
+        release_notes: releaseNotes ?? undefined,
+    });
+    fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf-8');
+    return {
+        package_name: workspacePackage.name,
+        workspace_version: workspacePackage.version,
+        manifest_path: projectManifestPath,
+        artifact_path: projectArtifactPath,
+        install_command: installCommand,
+        release_notes: releaseNotes,
+    };
+}
+function checkNpmInstallableUpdate(source, config, cwd, options, defaultSource) {
+    const packageName = source.package_name?.trim() || DEFAULT_NPM_UPDATE_PACKAGE;
+    const distTag = source.dist_tag?.trim() || DEFAULT_NPM_UPDATE_DIST_TAG;
+    if (packageName.length === 0) {
         return {
             checked: false,
             source_type: 'npm',
-            source_description: `${packageName}@${distTag}`,
+            source_description: null,
             latest_installable_version: null,
             artifact_path: null,
             install_command: null,
             release_notes: null,
-            status: 'unsupported_source',
-            message: 'The npm update source is modeled in config but is not implemented yet in this build.',
+            status: 'invalid_config',
+            message: 'brainclaw_update_source.package_name must not be empty.',
+            default_source: defaultSource,
         };
     }
-    const manifestPath = source.manifest_path.trim();
-    if (manifestPath.length === 0) {
+    if (distTag.length === 0) {
+        return {
+            checked: false,
+            source_type: 'npm',
+            source_description: packageName,
+            latest_installable_version: null,
+            artifact_path: null,
+            install_command: null,
+            release_notes: null,
+            status: 'invalid_config',
+            message: 'brainclaw_update_source.dist_tag must not be empty.',
+            default_source: defaultSource,
+        };
+    }
+    try {
+        const lookup = (options.npmLookup ?? lookupNpmDistTags)(packageName, {
+            cwd,
+            now: options.now,
+            cacheTtlMs: options.cacheTtlMs,
+        });
+        const latestVersion = normalizeConfiguredVersion(lookup.dist_tags[distTag]);
+        if (!latestVersion) {
+            return {
+                checked: true,
+                source_type: 'npm',
+                source_description: formatNpmSourceDescription(packageName, distTag, defaultSource),
+                latest_installable_version: null,
+                artifact_path: null,
+                install_command: null,
+                release_notes: config?.brainclaw_upgrade_message?.trim() || null,
+                status: 'check_failed',
+                message: `The npm channel ${packageName}@${distTag} did not resolve to a valid semver release.`,
+                checked_at: lookup.checked_at,
+                cached: lookup.cached,
+                default_source: defaultSource,
+            };
+        }
+        const installCommand = config?.brainclaw_upgrade_command?.trim()
+            || `npm install -g ${packageName}@${latestVersion}`;
+        const releaseNotes = config?.brainclaw_upgrade_message?.trim() || null;
+        const installedVersion = getInstalledBrainclawVersion();
+        if (compareVersions(installedVersion, latestVersion) < 0) {
+            return {
+                checked: true,
+                source_type: 'npm',
+                source_description: formatNpmSourceDescription(packageName, distTag, defaultSource),
+                latest_installable_version: latestVersion,
+                artifact_path: null,
+                install_command: installCommand,
+                release_notes: releaseNotes,
+                status: 'update_available',
+                message: `A newer installable brainclaw build is available from npm: ${latestVersion} (installed ${installedVersion}).`,
+                checked_at: lookup.checked_at,
+                cached: lookup.cached,
+                default_source: defaultSource,
+            };
+        }
+        return {
+            checked: true,
+            source_type: 'npm',
+            source_description: formatNpmSourceDescription(packageName, distTag, defaultSource),
+            latest_installable_version: latestVersion,
+            artifact_path: null,
+            install_command: installCommand,
+            release_notes: releaseNotes,
+            status: 'up_to_date',
+            message: `Installed brainclaw ${installedVersion} is up to date for npm channel ${packageName}@${distTag}.`,
+            checked_at: lookup.checked_at,
+            cached: lookup.cached,
+            default_source: defaultSource,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            checked: true,
+            source_type: 'npm',
+            source_description: formatNpmSourceDescription(packageName, distTag, defaultSource),
+            latest_installable_version: null,
+            artifact_path: null,
+            install_command: null,
+            release_notes: config?.brainclaw_upgrade_message?.trim() || null,
+            status: 'check_failed',
+            message: `Failed to check npm installable updates: ${message}`,
+            default_source: defaultSource,
+        };
+    }
+}
+function checkLocalPackInstallableUpdate(manifestPath, config, cwd) {
+    const trimmedManifestPath = manifestPath.trim();
+    if (trimmedManifestPath.length === 0) {
         return {
             checked: false,
             source_type: 'local-pack',
@@ -129,11 +299,12 @@ export function checkBrainclawInstallableUpdate(config, cwd) {
             release_notes: null,
             status: 'invalid_config',
             message: 'brainclaw_update_source.manifest_path must not be empty.',
+            default_source: false,
         };
     }
-    const resolvedManifestPath = path.isAbsolute(manifestPath)
-        ? manifestPath
-        : path.resolve(cwd, manifestPath);
+    const resolvedManifestPath = path.isAbsolute(trimmedManifestPath)
+        ? trimmedManifestPath
+        : path.resolve(cwd, trimmedManifestPath);
     if (!fs.existsSync(resolvedManifestPath)) {
         return {
             checked: true,
@@ -145,6 +316,7 @@ export function checkBrainclawInstallableUpdate(config, cwd) {
             release_notes: null,
             status: 'check_failed',
             message: `The configured local-pack manifest was not found: ${resolvedManifestPath}`,
+            default_source: false,
         };
     }
     try {
@@ -162,6 +334,7 @@ export function checkBrainclawInstallableUpdate(config, cwd) {
                 release_notes: manifest.release_notes?.trim() || config?.brainclaw_upgrade_message?.trim() || null,
                 status: 'check_failed',
                 message: `The local-pack manifest has an invalid latest_installable_version: ${manifest.latest_installable_version}`,
+                default_source: false,
             };
         }
         const artifactPath = manifest.artifact_path
@@ -182,6 +355,7 @@ export function checkBrainclawInstallableUpdate(config, cwd) {
                 release_notes: releaseNotes,
                 status: 'update_available',
                 message: `A newer installable brainclaw build is available: ${latestVersion} (installed ${installedVersion}).`,
+                default_source: false,
             };
         }
         return {
@@ -194,6 +368,7 @@ export function checkBrainclawInstallableUpdate(config, cwd) {
             release_notes: releaseNotes,
             status: 'up_to_date',
             message: `Installed brainclaw ${installedVersion} is up to date for the configured local-pack channel.`,
+            default_source: false,
         };
     }
     catch (error) {
@@ -208,59 +383,10 @@ export function checkBrainclawInstallableUpdate(config, cwd) {
             release_notes: null,
             status: 'check_failed',
             message: `Failed to read the configured local-pack manifest: ${message}`,
+            default_source: false,
         };
     }
 }
-export function publishLocalBrainclawRelease(cwd, options = {}) {
-    const workspacePackage = readWorkspaceBrainclawPackage(cwd);
-    const outputDir = path.resolve(cwd, options.outputDir ?? DEFAULT_LOCAL_RELEASES_DIR);
-    const manifestPath = path.resolve(cwd, options.manifestPath ?? DEFAULT_LOCAL_RELEASE_MANIFEST_PATH);
-    fs.mkdirSync(outputDir, { recursive: true });
-    fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
-    const packResult = spawnSync(resolveNpmCommand(), resolveNpmPackArgs(outputDir), {
-        cwd,
-        encoding: 'utf-8',
-        timeout: 120000,
-    });
-    if (packResult.error) {
-        throw new Error(`Failed to run npm pack: ${packResult.error.message}`);
-    }
-    if (packResult.status !== 0) {
-        throw new Error(firstNonEmptyLine(packResult.stderr) ?? firstNonEmptyLine(packResult.stdout) ?? 'npm pack failed');
-    }
-    const artifactFilename = parsePackedFilename(packResult.stdout);
-    if (!artifactFilename) {
-        throw new Error('npm pack did not report the generated tarball filename.');
-    }
-    const artifactAbsolutePath = path.join(outputDir, artifactFilename);
-    if (!fs.existsSync(artifactAbsolutePath)) {
-        throw new Error(`npm pack reported ${artifactFilename}, but the tarball was not found in ${outputDir}.`);
-    }
-    const manifestArtifactPath = toManifestRelativePath(path.relative(path.dirname(manifestPath), artifactAbsolutePath));
-    const projectArtifactPath = toManifestRelativePath(path.relative(cwd, artifactAbsolutePath));
-    const projectManifestPath = toPortablePath(path.relative(cwd, manifestPath));
-    const installCommand = `npm install -g "${projectArtifactPath}"`;
-    const releaseNotes = options.releaseNotes?.trim() || null;
-    const manifest = BrainclawLocalReleaseManifestSchema.parse({
-        version: 1,
-        channel: 'local-pack',
-        package_name: workspacePackage.name,
-        latest_installable_version: workspacePackage.version,
-        published_at: new Date().toISOString(),
-        artifact_path: manifestArtifactPath,
-        install_command: installCommand,
-        release_notes: releaseNotes ?? undefined,
-    });
-    fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf-8');
-    return {
-        package_name: workspacePackage.name,
-        workspace_version: workspacePackage.version,
-        manifest_path: projectManifestPath,
-        artifact_path: projectArtifactPath,
-        install_command: installCommand,
-        release_notes: releaseNotes,
-    };
-}
 function resolveNpmCommand() {
     return process.platform === 'win32' ? (process.env.ComSpec?.trim() || 'cmd.exe') : 'npm';
 }
@@ -270,6 +396,12 @@ function resolveNpmPackArgs(outputDir) {
     }
     return ['pack', '--json', '--pack-destination', outputDir];
 }
+function resolveNpmViewArgs(packageName) {
+    if (process.platform === 'win32') {
+        return ['/d', '/s', '/c', 'npm', 'view', packageName, 'dist-tags', '--json'];
+    }
+    return ['view', packageName, 'dist-tags', '--json'];
+}
 function findOwnPackageJson() {
     let currentDir = path.dirname(fileURLToPath(import.meta.url));
     while (true) {
@@ -331,6 +463,115 @@ function parsePackedFilename(stdout) {
         return firstNonEmptyLine(stdout);
     }
 }
+function lookupNpmDistTags(packageName, options) {
+    const now = options.now ?? new Date();
+    const cachePath = resolveNpmUpdateCachePath(packageName);
+    const ttlMs = options.cacheTtlMs ?? DEFAULT_INSTALLABLE_UPDATE_CACHE_TTL_MS;
+    const cached = readCachedNpmDistTags(cachePath, packageName, now, ttlMs);
+    if (cached) {
+        return cached;
+    }
+    const viewResult = spawnSync(resolveNpmCommand(), resolveNpmViewArgs(packageName), {
+        cwd: options.cwd,
+        encoding: 'utf-8',
+        timeout: 15000,
+    });
+    if (viewResult.error) {
+        throw new Error(`npm view failed: ${viewResult.error.message}`);
+    }
+    if (viewResult.status !== 0) {
+        throw new Error(firstNonEmptyLine(viewResult.stderr) ?? firstNonEmptyLine(viewResult.stdout) ?? 'npm view failed');
+    }
+    const distTags = parseNpmDistTags(viewResult.stdout);
+    const result = {
+        dist_tags: distTags,
+        checked_at: now.toISOString(),
+        cached: false,
+    };
+    writeCachedNpmDistTags(cachePath, {
+        version: 1,
+        package_name: packageName,
+        fetched_at: result.checked_at,
+        dist_tags: distTags,
+    });
+    return result;
+}
+function parseNpmDistTags(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`npm view returned invalid JSON: ${message}`);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('npm view did not return a dist-tag object.');
+    }
+    const distTags = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        if (typeof value === 'string' && value.trim().length > 0) {
+            distTags[key] = value.trim();
+        }
+    }
+    if (Object.keys(distTags).length === 0) {
+        throw new Error('npm view returned an empty dist-tag object.');
+    }
+    return distTags;
+}
+function resolveNpmUpdateCachePath(packageName) {
+    const safeName = packageName.replace(/[^a-z0-9._-]+/gi, '_').replace(/^_+|_+$/g, '') || DEFAULT_NPM_UPDATE_PACKAGE;
+    return path.join(os.homedir(), '.brainclaw', 'cache', 'installable-updates', `${safeName}.json`);
+}
+function readCachedNpmDistTags(cachePath, packageName, now, ttlMs) {
+    if (!fs.existsSync(cachePath)) {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(fs.readFileSync(cachePath, 'utf-8'));
+        if (parsed.version !== 1
+            || parsed.package_name !== packageName
+            || typeof parsed.fetched_at !== 'string'
+            || !parsed.dist_tags
+            || typeof parsed.dist_tags !== 'object'
+            || Array.isArray(parsed.dist_tags)) {
+            return undefined;
+        }
+        const fetchedAt = Date.parse(parsed.fetched_at);
+        if (!Number.isFinite(fetchedAt) || now.getTime() - fetchedAt > ttlMs) {
+            return undefined;
+        }
+        const distTags = {};
+        for (const [key, value] of Object.entries(parsed.dist_tags)) {
+            if (typeof value === 'string' && value.trim().length > 0) {
+                distTags[key] = value.trim();
+            }
+        }
+        if (Object.keys(distTags).length === 0) {
+            return undefined;
+        }
+        return {
+            dist_tags: distTags,
+            checked_at: parsed.fetched_at,
+            cached: true,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeCachedNpmDistTags(cachePath, document) {
+    try {
+        fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+        fs.writeFileSync(cachePath, `${JSON.stringify(document, null, 2)}\n`, 'utf-8');
+    }
+    catch {
+        // Cache writes are best-effort only.
+    }
+}
+function formatNpmSourceDescription(packageName, distTag, defaultSource) {
+    return defaultSource ? `${packageName}@${distTag} (default npm channel)` : `${packageName}@${distTag}`;
+}
 function firstNonEmptyLine(value) {
     return value
         .split(/\r?\n/)

package/dist/core/claude-desktop-extension.js

@@ -0,0 +1,224 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { memoryExists } from './io.js';
+const CLAUDE_DESKTOP_TOOLS = [
+    { name: 'bclaw_session_start', description: 'Open a Brainclaw session and surface Claude-targeted tasks plus compact execution context.' },
+    { name: 'bclaw_get_context', description: 'Retrieve ranked Brainclaw project context for the current task or path.' },
+    { name: 'bclaw_list_surface_tasks', description: 'List queued or completed Brainclaw tasks delegated to Claude Desktop.' },
+    { name: 'bclaw_update_surface_task', description: 'Mark a delegated Claude Desktop task as in progress or completed.' },
+];
+export function buildClaudeDesktopExtension(options = {}) {
+    const cwd = path.resolve(options.cwd ?? process.cwd());
+    if (!memoryExists(cwd)) {
+        throw new Error('Project memory not initialized. Run `brainclaw init` first.');
+    }
+    const workspaceDir = path.resolve(options.workspaceDir ?? path.join(cwd, 'internal-docs', 'desktop-extensions', 'claude-desktop-brainclaw'));
+    const outputFile = path.resolve(options.outputFile ?? path.join(cwd, 'internal-docs', 'desktop-extensions', 'brainclaw-claude-desktop.mcpb'));
+    if (outputFile.startsWith(`${workspaceDir}${path.sep}`) || outputFile === workspaceDir) {
+        throw new Error('The .mcpb output file must live outside the extension workspace directory.');
+    }
+    const projectRoot = path.resolve(options.projectRoot ?? cwd);
+    const runtimeRoot = path.resolve(options.runtimeRootOverride ?? resolveRuntimeRoot());
+    const packageRoot = path.resolve(options.packageRootOverride ?? findPackageRoot(runtimeRoot));
+    const metadata = readPackageMetadata(packageRoot);
+    const copiedDependencies = options.dependenciesOverride ?? resolveRuntimeDependencies(packageRoot);
+    fs.rmSync(workspaceDir, { recursive: true, force: true });
+    fs.mkdirSync(workspaceDir, { recursive: true });
+    fs.cpSync(runtimeRoot, path.join(workspaceDir, 'runtime'), { recursive: true });
+    fs.mkdirSync(path.join(workspaceDir, 'server'), { recursive: true });
+    fs.mkdirSync(path.dirname(outputFile), { recursive: true });
+    for (const dep of copiedDependencies) {
+        const sourceDir = path.join(packageRoot, 'node_modules', dep);
+        if (!fs.existsSync(sourceDir)) {
+            throw new Error(`Missing runtime dependency for Claude Desktop extension: ${dep}`);
+        }
+        fs.cpSync(sourceDir, path.join(workspaceDir, 'node_modules', dep), { recursive: true });
+    }
+    const version = metadata.version ?? '0.0.0';
+    const manifestPath = path.join(workspaceDir, 'manifest.json');
+    const entryPointPath = path.join(workspaceDir, 'server', 'index.js');
+    const packageJsonPath = path.join(workspaceDir, 'package.json');
+    fs.writeFileSync(entryPointPath, buildServerEntryPoint(), 'utf-8');
+    fs.writeFileSync(packageJsonPath, `${JSON.stringify({
+        name: 'brainclaw-claude-desktop-extension',
+        private: true,
+        type: 'module',
+        version,
+    }, null, 2)}\n`, 'utf-8');
+    fs.writeFileSync(manifestPath, `${JSON.stringify(buildManifest(metadata, version, projectRoot), null, 2)}\n`, 'utf-8');
+    const packed = options.pack !== false ? packClaudeDesktopExtension(workspaceDir, outputFile) : false;
+    return {
+        workspaceDir,
+        outputFile,
+        packed,
+        manifestPath,
+        entryPointPath,
+        packageRoot,
+        runtimeRoot,
+        projectRoot,
+        copiedDependencies,
+    };
+}
+function buildServerEntryPoint() {
+    return `import process from 'node:process';
+
+const projectRoot = process.env.BRAINCLAW_PROJECT_ROOT?.trim();
+if (projectRoot) {
+  process.chdir(projectRoot);
+}
+
+const { runMcp } = await import('../runtime/commands/mcp.js');
+runMcp();
+`;
+}
+function buildManifest(metadata, version, projectRoot) {
+    return {
+        manifest_version: '0.3',
+        name: 'brainclaw-claude-desktop',
+        display_name: 'Brainclaw Project Memory',
+        version,
+        description: 'Brainclaw local project memory and delegated task inbox for Claude Desktop.',
+        author: {
+            name: 'Brainclaw',
+            ...(metadata.homepage ? { url: metadata.homepage } : {}),
+        },
+        ...(typeof metadata.repository === 'string'
+            ? { repository: { type: 'git', url: metadata.repository } }
+            : metadata.repository
+                ? { repository: metadata.repository }
+                : {}),
+        ...(metadata.homepage ? { homepage: metadata.homepage } : {}),
+        server: {
+            type: 'node',
+            entry_point: 'server/index.js',
+            mcp_config: {
+                command: 'node',
+                args: ['${__dirname}/server/index.js'],
+                env: {
+                    BRAINCLAW_PROJECT_ROOT: '${user_config.project_root}',
+                    BRAINCLAW_SKIP_SETUP_REQUIREMENT: '1',
+                },
+            },
+        },
+        tools: CLAUDE_DESKTOP_TOOLS,
+        compatibility: {
+            platforms: ['win32', 'darwin'],
+            runtimes: {
+                node: '>=20.0.0',
+            },
+        },
+        user_config: {
+            project_root: {
+                type: 'directory',
+                title: 'Project Root',
+                description: 'Brainclaw project root that Claude Desktop should operate on.',
+                required: true,
+                default: projectRoot,
+            },
+        },
+    };
+}
+function resolveRuntimeRoot() {
+    return path.resolve(fileURLToPath(new URL('..', import.meta.url)));
+}
+function findPackageRoot(startDir) {
+    let current = startDir;
+    while (true) {
+        const candidate = path.join(current, 'package.json');
+        if (fs.existsSync(candidate)) {
+            return current;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            throw new Error(`Could not locate package.json from ${startDir}`);
+        }
+        current = parent;
+    }
+}
+function readPackageMetadata(packageRoot) {
+    const packageJsonPath = path.join(packageRoot, 'package.json');
+    return JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+}
+function resolveRuntimeDependencies(packageRoot) {
+    const metadata = readPackageMetadata(packageRoot);
+    return Object.keys(metadata.dependencies ?? {});
+}
+function packClaudeDesktopExtension(workspaceDir, outputFile) {
+    fs.rmSync(outputFile, { force: true });
+    const pythonCommand = resolveAvailableCommand(process.platform === 'win32'
+        ? ['python', 'py', 'python3']
+        : ['python3', 'python', 'py']);
+    if (pythonCommand) {
+        const script = [
+            'import os, sys, zipfile',
+            'src, dest = sys.argv[1], sys.argv[2]',
+            'with zipfile.ZipFile(dest, "w", zipfile.ZIP_DEFLATED) as zf:',
+            '  for root, _, files in os.walk(src):',
+            '    for name in files:',
+            '      full = os.path.join(root, name)',
+            '      rel = os.path.relpath(full, src)',
+            '      zf.write(full, rel)',
+        ].join('; ');
+        const result = spawnSync(pythonCommand, ['-c', script, workspaceDir, outputFile], {
+            encoding: 'utf-8',
+        });
+        if (result.status === 0) {
+            return true;
+        }
+    }
+    if (process.platform === 'win32') {
+        const shell = resolveAvailableCommand(['pwsh', 'powershell']);
+        if (!shell) {
+            throw new Error('Could not find Python or PowerShell to create the Claude Desktop .mcpb archive.');
+        }
+        const command = `Compress-Archive -Path (Join-Path '${escapePowerShellPath(workspaceDir)}' '*') -DestinationPath '${escapePowerShellPath(outputFile)}' -Force`;
+        const result = spawnSync(shell, ['-NoProfile', '-Command', command], {
+            encoding: 'utf-8',
+        });
+        if (result.status === 0) {
+            return true;
+        }
+    }
+    const zipCommand = resolveAvailableCommand(['zip']);
+    if (zipCommand) {
+        const result = spawnSync(zipCommand, ['-qr', outputFile, '.'], {
+            cwd: workspaceDir,
+            encoding: 'utf-8',
+        });
+        if (result.status === 0) {
+            return true;
+        }
+    }
+    throw new Error('Failed to create a .mcpb archive. Install Python 3, PowerShell, or zip.');
+}
+function resolveAvailableCommand(candidates) {
+    for (const candidate of candidates) {
+        const result = spawnSync(candidate, ['--version'], { encoding: 'utf-8' });
+        if (result.status === 0) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+function escapePowerShellPath(value) {
+    return value.replace(/'/g, "''");
+}
+export function renderClaudeDesktopExtensionSummary(result) {
+    const lines = [
+        'Claude Desktop extension scaffold ready.',
+        `Workspace: ${path.relative(process.cwd(), result.workspaceDir) || result.workspaceDir}`,
+        `Manifest: ${path.relative(process.cwd(), result.manifestPath) || result.manifestPath}`,
+        `Server entry: ${path.relative(process.cwd(), result.entryPointPath) || result.entryPointPath}`,
+    ];
+    if (result.packed) {
+        lines.push(`Package: ${path.relative(process.cwd(), result.outputFile) || result.outputFile}`);
+        lines.push('Install in Claude Desktop via Developer -> Extensions -> Install Extension.');
+    }
+    else {
+        lines.push('Archive packing skipped (--no-pack).');
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=claude-desktop-extension.js.map

package/dist/core/ids.js

@@ -11,6 +11,7 @@ const PREFIXES = {
     plan_items: 'pln',
     plan_steps: 'stp',
     instruction_entries: 'ins',
+    ai_surface_tasks: 'ast',
 };
 const ID_COUNTER_FILE = '.id-counter.json';
 function counterPath(cwd) {