@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.17

package/dist/src/packages/adapters/clawhub.js

@@ -0,0 +1,113 @@
+/**
+ * ClawHub Package Adapter
+ *
+ * Implements PackageRegistryAdapter for the `clawhub:` and `openclaw:` URI
+ * schemes, routing `aiwg install clawhub:<owner>/<name>` through the
+ * ClawHub REST API at clawhub.ai.
+ *
+ * The adapter fetches the package manifest and skill content via the API,
+ * writes the result into the standard AIWG cache layout, and returns the
+ * local cache path — matching the contract of all other adapters.
+ *
+ * Cache layout (shared with GitAdapter):
+ *   ~/.cache/aiwg/packages/<owner>/<name>@<version>/
+ *
+ * @implements #803
+ * @see https://clawhub.ai
+ * @see https://docs.openclaw.ai/tools/clawhub
+ */
+import { mkdir, writeFile } from 'fs/promises';
+import { join } from 'path';
+import { existsSync } from 'fs';
+import { buildCachePath } from './git.js';
+const CLAWHUB_API_BASE = 'https://clawhub.ai/api/v1';
+/**
+ * Attempt a ClawHub API request, returning parsed JSON or null on failure.
+ */
+async function clawHubFetch(endpoint) {
+    try {
+        const response = await fetch(`${CLAWHUB_API_BASE}${endpoint}`, {
+            headers: { Accept: 'application/json' },
+            signal: AbortSignal.timeout(30_000),
+        });
+        if (!response.ok)
+            return null;
+        return await response.json();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * ClawHubPackageAdapter
+ *
+ * Handles "clawhub:owner/name[@version]" and "openclaw:owner/name[@version]"
+ * references in the install pipeline.
+ */
+export class ClawHubPackageAdapter {
+    id = 'clawhub';
+    name = 'ClawHub Registry';
+    /**
+     * Matches the `clawhub:` and `openclaw:` URI schemes.
+     */
+    canResolve(ref) {
+        return ref.startsWith('clawhub:') || ref.startsWith('openclaw:');
+    }
+    /**
+     * Resolve a parsed PackageRef to a PackageSource.
+     *
+     * The `gitUrl` field is a canonical API URL (not a git remote) so the
+     * caller can store it in packages.yaml for display and re-install.
+     */
+    async resolve(ref) {
+        if (!ref.owner || !ref.name)
+            return null;
+        const apiUrl = `${CLAWHUB_API_BASE}/skills/${encodeURIComponent(ref.owner)}/${encodeURIComponent(ref.name)}`;
+        return {
+            gitUrl: apiUrl,
+            ref: ref.version,
+            label: `clawhub.ai/${ref.owner}/${ref.name}${ref.version ? `@${ref.version}` : ''}`,
+        };
+    }
+    /**
+     * Fetch the package from ClawHub and write it to the local cache.
+     *
+     * Skips the network request if the cache directory already exists and
+     * `options.refresh` is not set.
+     */
+    async fetch(source, options = {}) {
+        // Extract owner/name from the API URL stored in source.gitUrl
+        const urlMatch = source.gitUrl.match(/\/skills\/([^/]+)\/([^/]+)$/);
+        const owner = urlMatch ? decodeURIComponent(urlMatch[1]) : 'clawhub';
+        const name = urlMatch ? decodeURIComponent(urlMatch[2]) : 'package';
+        const version = source.ref ?? 'latest';
+        const cachePath = buildCachePath(owner, name, version);
+        // Return cached version unless refresh is requested
+        if (!options.refresh && existsSync(cachePath)) {
+            return cachePath;
+        }
+        // Fetch package content from ClawHub API
+        const downloadEndpoint = `/skills/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/download`;
+        const apiResult = await clawHubFetch(downloadEndpoint);
+        if (!apiResult || !apiResult.content) {
+            throw new Error(`Could not fetch '${owner}/${name}' from ClawHub. ` +
+                `Ensure the package exists at https://clawhub.ai and the API is reachable. ` +
+                `(URL: ${CLAWHUB_API_BASE}${downloadEndpoint})`);
+        }
+        // Write content to cache
+        await mkdir(cachePath, { recursive: true });
+        const skillMdPath = join(cachePath, 'SKILL.md');
+        await writeFile(skillMdPath, apiResult.content, 'utf-8');
+        // Write a minimal manifest so detectManifestType can classify it
+        if (apiResult.manifest) {
+            const manifestPath = join(cachePath, 'manifest.json');
+            await writeFile(manifestPath, JSON.stringify(apiResult.manifest, null, 2) + '\n', 'utf-8');
+        }
+        return cachePath;
+    }
+    /** ClawHubPackageAdapter does not enumerate packages */
+    async list() {
+        return [];
+    }
+}
+//# sourceMappingURL=clawhub.js.map

package/dist/src/packages/adapters/git.js

@@ -0,0 +1,153 @@
+/**
+ * Git Adapter
+ *
+ * Base adapter for fetching packages from any Git URL.
+ * Handles clone to cache, pull for refresh, and version tag checkout.
+ *
+ * Cache layout:
+ *   ~/.cache/aiwg/packages/<owner>/<name>@<version>/
+ *
+ * @implements #557
+ */
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { mkdir, readFile } from 'fs/promises';
+import { join } from 'path';
+import { homedir } from 'os';
+import { existsSync } from 'fs';
+const execFileAsync = promisify(execFile);
+/**
+ * Default cache root
+ */
+function getCacheRoot() {
+    const xdgCache = process.env.XDG_CACHE_HOME;
+    const base = xdgCache ? xdgCache : join(homedir(), '.cache');
+    return join(base, 'aiwg', 'packages');
+}
+/**
+ * Build cache path for a package at a specific version
+ */
+export function buildCachePath(owner, name, version) {
+    const safe = version.replace(/[^a-zA-Z0-9._-]/g, '_');
+    return join(getCacheRoot(), owner, `${name}@${safe}`);
+}
+/**
+ * Run a git command, returning stdout
+ */
+async function git(args, cwd) {
+    const env = { ...process.env };
+    // Suppress interactive prompts
+    env.GIT_TERMINAL_PROMPT = '0';
+    const { stdout } = await execFileAsync('git', args, {
+        cwd,
+        env,
+        timeout: 120_000,
+    });
+    return stdout.trim();
+}
+/**
+ * Detect the manifest type from a cloned package directory
+ */
+async function detectManifestType(cachePath) {
+    const manifestPath = join(cachePath, 'manifest.json');
+    try {
+        const content = await readFile(manifestPath, 'utf-8');
+        const manifest = JSON.parse(content);
+        const t = manifest.type?.toLowerCase() ?? '';
+        if (t === 'framework')
+            return 'framework';
+        if (t === 'addon')
+            return 'addon';
+        if (t === 'extension')
+            return 'extension';
+        return 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/**
+ * Resolve the latest tag from a remote git repo
+ */
+async function resolveLatestTag(gitUrl) {
+    try {
+        const output = await git(['ls-remote', '--tags', '--sort=-v:refname', gitUrl]);
+        const firstLine = output.split('\n')[0] ?? '';
+        const match = firstLine.match(/refs\/tags\/(.+)/);
+        if (match && match[1])
+            return match[1].replace(/\^{}$/, '');
+    }
+    catch {
+        // fall through
+    }
+    return 'latest';
+}
+/**
+ * GitAdapter
+ *
+ * Handles any https:// or git@... URL directly.
+ * Also serves as the base class for Gitea/GitHub shorthand adapters.
+ */
+export class GitAdapter {
+    id = 'git';
+    name = 'Git (direct URL)';
+    /**
+     * Returns true for https:// or git@/ssh:// URLs, or git+https:// URLs
+     */
+    canResolve(ref) {
+        return (ref.startsWith('https://') ||
+            ref.startsWith('http://') ||
+            ref.startsWith('git@') ||
+            ref.startsWith('ssh://') ||
+            ref.startsWith('git+https://'));
+    }
+    async resolve(ref) {
+        if (!ref.rawUrl)
+            return null;
+        return {
+            gitUrl: ref.rawUrl,
+            ref: ref.version,
+            label: ref.rawUrl,
+        };
+    }
+    async fetch(source, options = {}) {
+        // Determine version
+        let version = source.ref;
+        if (!version) {
+            version = await resolveLatestTag(source.gitUrl);
+        }
+        // Build cache key from URL
+        const urlKey = source.gitUrl
+            .replace(/^https?:\/\//, '')
+            .replace(/^git@/, '')
+            .replace(/\.git$/, '')
+            .replace(/[:/]/g, '_');
+        const parts = urlKey.split('_');
+        const name = parts[parts.length - 1] ?? 'package';
+        const owner = parts[parts.length - 2] ?? 'unknown';
+        const cachePath = buildCachePath(owner, name, version);
+        if (!options.refresh && existsSync(cachePath)) {
+            return cachePath;
+        }
+        await mkdir(cachePath, { recursive: true });
+        if (existsSync(join(cachePath, '.git'))) {
+            // Update existing clone
+            await git(['fetch', '--tags', '--prune'], cachePath);
+        }
+        else {
+            // Fresh clone (no --depth to get tags)
+            await git(['clone', source.gitUrl, cachePath]);
+        }
+        // Checkout requested ref
+        if (version && version !== 'latest') {
+            await git(['checkout', version], cachePath);
+        }
+        return cachePath;
+    }
+    /** GitAdapter does not list packages */
+    async list() {
+        return [];
+    }
+}
+export { detectManifestType };
+//# sourceMappingURL=git.js.map

package/dist/src/packages/adapters/gitea.js

@@ -0,0 +1,93 @@
+/**
+ * Gitea Adapter
+ *
+ * Resolves "owner/name[@version]" shorthands against the configured Gitea host.
+ * Falls back to git.integrolabs.net (the default self-hosted instance).
+ *
+ * Resolution priority:
+ *   1. AIWG_GITEA_HOST env var
+ *   2. ~/.aiwg/config.yaml → defaults.giteaHost
+ *   3. git.integrolabs.net (hardcoded fallback)
+ *
+ * Authentication:
+ *   - SSH clone: uses default SSH agent (recommended for teams)
+ *   - HTTPS clone: reads token from GITEA_TOKEN env or ~/.config/gitea/token
+ *
+ * @implements #557
+ */
+import { existsSync } from 'fs';
+import { readFile } from 'fs/promises';
+import { join } from 'path';
+import { homedir } from 'os';
+import { GitAdapter } from './git.js';
+/**
+ * Regex for "owner/name" or "owner/name@version" (no scheme prefix)
+ */
+const GITEA_SHORTHAND = /^[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+(@[a-zA-Z0-9._/-]+)?$/;
+/**
+ * Read Gitea token from standard file path (same as global CLAUDE.md convention)
+ */
+async function readGiteaToken() {
+    if (process.env.GITEA_TOKEN)
+        return process.env.GITEA_TOKEN;
+    const tokenPaths = [
+        join(homedir(), '.config', 'gitea', 'token'),
+        join(homedir(), '.aiwg', 'credentials', 'gitea'),
+    ];
+    for (const p of tokenPaths) {
+        if (existsSync(p)) {
+            return (await readFile(p, 'utf-8')).trim();
+        }
+    }
+    return undefined;
+}
+/**
+ * Resolve the Gitea host
+ */
+function resolveGiteaHost() {
+    if (process.env.AIWG_GITEA_HOST)
+        return process.env.AIWG_GITEA_HOST;
+    return 'git.integrolabs.net';
+}
+/**
+ * GiteaAdapter
+ *
+ * Handles "owner/repo[@version]" shorthands for the configured Gitea host.
+ */
+export class GiteaAdapter extends GitAdapter {
+    id = 'gitea';
+    name = 'Gitea (shorthand)';
+    /**
+     * Matches "owner/repo" and "owner/repo@version" without a scheme prefix.
+     * Does not match "github:owner/repo" (handled by GitHubAdapter).
+     */
+    canResolve(ref) {
+        if (ref.includes(':'))
+            return false; // has scheme prefix → not gitea shorthand
+        return GITEA_SHORTHAND.test(ref);
+    }
+    async resolve(ref) {
+        if (!ref.owner || !ref.name)
+            return null;
+        const host = resolveGiteaHost();
+        const token = await readGiteaToken();
+        let gitUrl;
+        if (token) {
+            // HTTPS with token
+            gitUrl = `https://${token}@${host}/${ref.owner}/${ref.name}.git`;
+        }
+        else {
+            // SSH (relies on SSH agent)
+            gitUrl = `git@${host}:${ref.owner}/${ref.name}.git`;
+        }
+        return {
+            gitUrl,
+            ref: ref.version,
+            label: `${host}/${ref.owner}/${ref.name}${ref.version ? `@${ref.version}` : ''}`,
+        };
+    }
+    async fetch(source, options = {}) {
+        return super.fetch(source, options);
+    }
+}
+//# sourceMappingURL=gitea.js.map

package/dist/src/packages/adapters/github.js

@@ -0,0 +1,69 @@
+/**
+ * GitHub Adapter
+ *
+ * Resolves "github:owner/name[@version]" shorthands against github.com.
+ *
+ * Authentication:
+ *   - SSH clone: uses default SSH agent
+ *   - HTTPS clone: reads token from GITHUB_TOKEN env or ~/.aiwg/credentials/github
+ *
+ * @implements #557
+ */
+import { existsSync } from 'fs';
+import { readFile } from 'fs/promises';
+import { join } from 'path';
+import { homedir } from 'os';
+import { GitAdapter } from './git.js';
+const GITHUB_HOST = 'github.com';
+/**
+ * Read GitHub token from standard locations
+ */
+async function readGitHubToken() {
+    if (process.env.GITHUB_TOKEN)
+        return process.env.GITHUB_TOKEN;
+    const tokenPaths = [
+        join(homedir(), '.aiwg', 'credentials', 'github'),
+    ];
+    for (const p of tokenPaths) {
+        if (existsSync(p)) {
+            return (await readFile(p, 'utf-8')).trim();
+        }
+    }
+    return undefined;
+}
+/**
+ * GitHubAdapter
+ *
+ * Handles "github:owner/repo[@version]" shorthands.
+ */
+export class GitHubAdapter extends GitAdapter {
+    id = 'github';
+    name = 'GitHub (shorthand)';
+    /**
+     * Matches "github:owner/repo" and "github:owner/repo@version"
+     */
+    canResolve(ref) {
+        return ref.startsWith('github:');
+    }
+    async resolve(ref) {
+        if (!ref.owner || !ref.name)
+            return null;
+        const token = await readGitHubToken();
+        let gitUrl;
+        if (token) {
+            gitUrl = `https://${token}@${GITHUB_HOST}/${ref.owner}/${ref.name}.git`;
+        }
+        else {
+            gitUrl = `git@${GITHUB_HOST}:${ref.owner}/${ref.name}.git`;
+        }
+        return {
+            gitUrl,
+            ref: ref.version,
+            label: `github.com/${ref.owner}/${ref.name}${ref.version ? `@${ref.version}` : ''}`,
+        };
+    }
+    async fetch(source, options = {}) {
+        return super.fetch(source, options);
+    }
+}
+//# sourceMappingURL=github.js.map

package/dist/src/packages/adapters/local-cache.js

@@ -0,0 +1,89 @@
+/**
+ * Local Cache Adapter
+ *
+ * Lists and resolves packages already present in the local package cache
+ * (~/.cache/aiwg/packages/) and registered in ~/.aiwg/packages.yaml.
+ *
+ * Used by `aiwg use <name>` to check installed packages before falling back
+ * to the bundled npm package.
+ *
+ * @implements #557
+ */
+import { existsSync } from 'fs';
+import { listPackages } from '../package-registry.js';
+/**
+ * LocalCacheAdapter
+ *
+ * Does not fetch — only resolves already-cached packages.
+ */
+export class LocalCacheAdapter {
+    id = 'local-cache';
+    name = 'Local Package Cache';
+    /**
+     * Can resolve any ref that matches a key in the local registry.
+     * This is checked by the registry coordinator after parsing the ref,
+     * so canResolve is always false (resolution happens via list()).
+     */
+    canResolve(_ref) {
+        return false; // Only used via explicit lookup, not auto-resolution
+    }
+    async resolve(_ref) {
+        return null;
+    }
+    /**
+     * No-op — local cache adapter never fetches
+     */
+    async fetch(_source, _options) {
+        throw new Error('LocalCacheAdapter does not support fetch — use GitAdapter instead');
+    }
+    /**
+     * List all packages in the local registry
+     */
+    async list() {
+        return listPackages();
+    }
+    /**
+     * Look up a package by name (partial match on key or name component)
+     * Returns the PackageInfo if found and the cache path still exists.
+     */
+    async lookupByName(name) {
+        const packages = await listPackages();
+        // Exact key match first ("owner/name")
+        const exactKey = packages.find((p) => p.key === name);
+        if (exactKey)
+            return exactKey;
+        // Match by name component only
+        const byName = packages.find((p) => p.name === name);
+        if (byName)
+            return byName;
+        return undefined;
+    }
+    /**
+     * Look up cache path for a package by name.
+     * Returns the cache path if installed and present on disk.
+     */
+    async resolveCachePath(name) {
+        const { getPackageEntry } = await import('../package-registry.js');
+        const packages = await listPackages();
+        let key;
+        // Exact key match
+        if (packages.some((p) => p.key === name)) {
+            key = name;
+        }
+        else {
+            // Match by name component
+            const byName = packages.find((p) => p.name === name);
+            if (byName)
+                key = byName.key;
+        }
+        if (!key)
+            return undefined;
+        const entry = await getPackageEntry(key);
+        if (!entry)
+            return undefined;
+        if (!existsSync(entry.cachePath))
+            return undefined;
+        return entry.cachePath;
+    }
+}
+//# sourceMappingURL=local-cache.js.map

package/dist/src/packages/package-registry.js

@@ -0,0 +1,143 @@
+/**
+ * Package Registry
+ *
+ * Manages ~/.aiwg/packages.yaml — the local registry of installed remote
+ * packages (frameworks, addons, extensions installed via `aiwg install`).
+ *
+ * @implements #557
+ */
+import { readFile, writeFile, mkdir, access } from 'fs/promises';
+import { resolve, join } from 'path';
+import { homedir } from 'os';
+import { existsSync } from 'fs';
+import { stringify, parse } from 'yaml';
+const PACKAGES_FILENAME = 'packages.yaml';
+/**
+ * Empty registry template
+ */
+function emptyRegistry() {
+    return {
+        apiVersion: 'aiwg.io/v1',
+        kind: 'PackageRegistry',
+        packages: {},
+    };
+}
+/**
+ * Resolve ~/.aiwg directory path using the same resolution logic as user-config
+ */
+function resolveAiwgDir() {
+    // Respect explicit override
+    if (process.env.AIWG_CONFIG)
+        return process.env.AIWG_CONFIG;
+    const primary = join(homedir(), '.aiwg');
+    const xdg = join(homedir(), '.config', 'aiwg');
+    if (existsSync(primary))
+        return primary;
+    if (existsSync(xdg))
+        return xdg;
+    return primary; // default
+}
+/**
+ * Get the path to packages.yaml
+ */
+export function getPackagesFilePath(configDir) {
+    const dir = configDir || resolveAiwgDir();
+    return resolve(dir, PACKAGES_FILENAME);
+}
+/**
+ * Read packages.yaml, returning an empty registry if the file does not exist
+ */
+export async function readPackageRegistry(configDir) {
+    const filePath = getPackagesFilePath(configDir);
+    try {
+        await access(filePath);
+    }
+    catch {
+        return emptyRegistry();
+    }
+    const content = await readFile(filePath, 'utf-8');
+    const parsed = parse(content);
+    if (!parsed || typeof parsed !== 'object')
+        return emptyRegistry();
+    // Ensure packages map exists
+    if (!parsed.packages)
+        parsed.packages = {};
+    return parsed;
+}
+/**
+ * Write packages.yaml, creating ~/.aiwg/ if needed
+ */
+export async function writePackageRegistry(registry, configDir) {
+    const dir = configDir || resolveAiwgDir();
+    await mkdir(dir, { recursive: true });
+    const filePath = resolve(dir, PACKAGES_FILENAME);
+    const content = stringify(registry, { lineWidth: 0 });
+    await writeFile(filePath, content, 'utf-8');
+}
+/**
+ * Get a single package entry by key (e.g. "roko/ring-methodology")
+ */
+export async function getPackageEntry(key, configDir) {
+    const registry = await readPackageRegistry(configDir);
+    return registry.packages[key];
+}
+/**
+ * Upsert a package entry
+ */
+export async function setPackageEntry(key, entry, configDir) {
+    const registry = await readPackageRegistry(configDir);
+    registry.packages[key] = entry;
+    await writePackageRegistry(registry, configDir);
+}
+/**
+ * Remove a package entry
+ */
+export async function removePackageEntry(key, configDir) {
+    const registry = await readPackageRegistry(configDir);
+    if (!registry.packages[key])
+        return false;
+    delete registry.packages[key];
+    await writePackageRegistry(registry, configDir);
+    return true;
+}
+/**
+ * Record a deployment against an existing package entry
+ */
+export async function recordDeployment(key, record, configDir) {
+    const registry = await readPackageRegistry(configDir);
+    const entry = registry.packages[key];
+    if (!entry)
+        return;
+    if (!entry.deployedTo)
+        entry.deployedTo = [];
+    // Replace existing record for the same project+provider
+    const idx = entry.deployedTo.findIndex((d) => d.projectPath === record.projectPath && d.provider === record.provider);
+    if (idx >= 0) {
+        entry.deployedTo[idx] = record;
+    }
+    else {
+        entry.deployedTo.push(record);
+    }
+    registry.packages[key] = entry;
+    await writePackageRegistry(registry, configDir);
+}
+/**
+ * List all installed packages as PackageInfo summaries
+ */
+export async function listPackages(configDir) {
+    const registry = await readPackageRegistry(configDir);
+    return Object.entries(registry.packages).map(([key, entry]) => {
+        const parts = key.split('/');
+        return {
+            key,
+            name: parts.length > 1 ? parts.slice(1).join('/') : key,
+            owner: parts.length > 1 ? parts[0] : undefined,
+            version: entry.version,
+            type: entry.type,
+            source: entry.source,
+            installedAt: entry.installedAt,
+            deployCount: entry.deployedTo?.length ?? 0,
+        };
+    });
+}
+//# sourceMappingURL=package-registry.js.map