@hi-man/himan 0.3.5 → 0.4.1

package/dist/services/index.js

@@ -8,9 +8,13 @@ import { toRepoId } from "../utils/repo-id.js";
 import { HimanError, errorCodes } from "../utils/errors.js";
 import { getGlobalResourcePaths, getProjectResourcePaths, getSupportedAgentNames, normalizeAgents, } from "../utils/agent-configs.js";
 import path from "node:path";
+import { execFile } from "node:child_process";
 import { promises as fs } from "node:fs";
+import { promisify } from "node:util";
 import { VersionResolver } from "../adapters/version/version-resolver.js";
 import YAML from "yaml";
+const execFileAsync = promisify(execFile);
+const RESOURCE_TYPES = ["rule", "command", "skill"];
 export class ServiceFactory {
     stateStore = new StateStore();
     projectConfigStore = new ProjectConfigStore();
@@ -43,9 +47,7 @@ export class ServiceFactory {
         };
     }
     async addSource(name, type, repo) {
-        if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) {
-            throw new HimanError(errorCodes.INVALID_INPUT, `Invalid source name: ${name}`);
-        }
+        this.validateSourceName(name);
         await this.stateStore.ensureBaseDirs();
         const sourceConfig = this.buildSourceConfig(type, repo);
         const source = this.createSource(type);
@@ -105,6 +107,47 @@ export class ServiceFactory {
         const source = await this.loadSourceFromConfig();
         return source.initDocs(options);
     }
+    async cloneSource(from, to, options = {}) {
+        await this.stateStore.ensureBaseDirs();
+        this.validateSourceTransferOptions(to, options);
+        const sourceEndpoint = await this.resolveGitSourceEndpoint(from);
+        const targetEndpoint = await this.resolveGitSourceEndpoint(to);
+        this.validateSourceTransferUseTarget(targetEndpoint, options);
+        this.ensureDifferentGitSources(sourceEndpoint, targetEndpoint);
+        const source = await this.loadGitSourceFromEndpoint(sourceEndpoint);
+        const result = await source.cloneTo(targetEndpoint.repo, {
+            branch: options.branch,
+            targetBranch: options.targetBranch,
+            dryRun: options.dryRun,
+        });
+        const configUpdates = await this.applySourceTransferConfigUpdates(targetEndpoint, options);
+        return {
+            source: sourceEndpoint,
+            target: targetEndpoint,
+            ...result,
+            ...configUpdates,
+        };
+    }
+    async syncSource(from, to, options = {}) {
+        await this.stateStore.ensureBaseDirs();
+        this.validateSourceTransferOptions(to, options);
+        const sourceEndpoint = await this.resolveGitSourceEndpoint(from);
+        const targetEndpoint = await this.resolveGitSourceEndpoint(to);
+        this.validateSourceTransferUseTarget(targetEndpoint, options);
+        this.ensureDifferentGitSources(sourceEndpoint, targetEndpoint);
+        const source = await this.loadGitSourceFromEndpoint(sourceEndpoint);
+        const result = await source.syncLatestTo(targetEndpoint.repo, {
+            targetBranch: options.targetBranch,
+            dryRun: options.dryRun,
+        });
+        const configUpdates = await this.applySourceTransferConfigUpdates(targetEndpoint, options);
+        return {
+            source: sourceEndpoint,
+            target: targetEndpoint,
+            ...result,
+            ...configUpdates,
+        };
+    }
     async setAgents(agents, scope, projectDir) {
         const normalized = normalizeAgents(agents);
         if (scope === "project") {
@@ -137,6 +180,45 @@ export class ServiceFactory {
             supported: getSupportedAgentNames(),
         };
     }
+    async doctor(projectDir) {
+        const checks = [];
+        checks.push(this.checkNodeVersion());
+        checks.push(await this.checkGit());
+        checks.push(await this.checkHomeState());
+        const config = await this.stateStore.loadConfig();
+        if (!config?.source) {
+            checks.push({
+                name: "source",
+                status: "error",
+                message: "No source configured. Run `himan init <git_repo>` first.",
+                details: { configPath: this.stateStore.getConfigPath() },
+            });
+        }
+        else {
+            const currentName = config.sources?.default ?? "default";
+            const currentSource = config.sources?.items[currentName] ?? config.source;
+            checks.push({
+                name: "source",
+                status: "ok",
+                message: `Using ${currentSource.type} source ${currentName}.`,
+                details: {
+                    name: currentName,
+                    type: currentSource.type,
+                    repo: currentSource.repo,
+                    repoId: currentSource.repoId,
+                },
+            });
+            checks.push(await this.checkSourceResources());
+        }
+        checks.push(await this.checkAgents(projectDir));
+        const lockCheck = await this.checkProjectLock(projectDir);
+        checks.push(lockCheck.check);
+        checks.push(await this.checkProjectTargets(projectDir, lockCheck.lock));
+        return {
+            ok: !checks.some((check) => check.status === "error"),
+            checks,
+        };
+    }
     async clearAgents(scope, projectDir) {
         if (scope === "project") {
             await this.projectConfigStore.clearAgents(projectDir);
@@ -149,6 +231,172 @@ export class ServiceFactory {
         });
         return { scope };
     }
+    checkNodeVersion() {
+        const version = process.versions.node;
+        const major = Number(version.split(".")[0]);
+        if (major === 22) {
+            return {
+                name: "node",
+                status: "ok",
+                message: `Node.js ${version}.`,
+            };
+        }
+        return {
+            name: "node",
+            status: "error",
+            message: `Node.js ${version} is unsupported. Use Node.js 22.x.`,
+        };
+    }
+    async checkGit() {
+        try {
+            const result = await execFileAsync("git", ["--version"]);
+            return {
+                name: "git",
+                status: "ok",
+                message: result.stdout.trim() || "Git is available.",
+            };
+        }
+        catch (error) {
+            return this.errorCheck("git", "Git is not available on PATH.", error);
+        }
+    }
+    async checkHomeState() {
+        const root = this.paths.getHimanRoot();
+        const reposDir = this.paths.getReposDir();
+        const storeDir = this.paths.getStoreDir();
+        const missing = [];
+        if (!(await this.exists(root)))
+            missing.push(root);
+        if (!(await this.exists(reposDir)))
+            missing.push(reposDir);
+        if (!(await this.exists(storeDir)))
+            missing.push(storeDir);
+        if (missing.length > 0) {
+            return {
+                name: "home",
+                status: "warn",
+                message: "Himan home directories are not fully initialized yet.",
+                details: { root, reposDir, storeDir, missing },
+            };
+        }
+        return {
+            name: "home",
+            status: "ok",
+            message: `Himan home is initialized at ${root}.`,
+            details: { root, reposDir, storeDir },
+        };
+    }
+    async checkSourceResources() {
+        try {
+            const source = await this.loadSourceFromConfig();
+            const entries = await Promise.all(RESOURCE_TYPES.map(async (type) => [type, await source.list(type)]));
+            const counts = Object.fromEntries(entries.map(([type, resources]) => [type, resources.length]));
+            const total = RESOURCE_TYPES.reduce((sum, type) => sum + counts[type], 0);
+            return {
+                name: "resources",
+                status: "ok",
+                message: `Scanned ${total} resources from current source.`,
+                details: { counts },
+            };
+        }
+        catch (error) {
+            return this.errorCheck("resources", "Cannot scan current source resources.", error);
+        }
+    }
+    async checkAgents(projectDir) {
+        try {
+            const settings = await this.getAgentSettings(projectDir);
+            const scope = settings.project ? "project" : settings.global ? "global" : "default";
+            return {
+                name: "agents",
+                status: "ok",
+                message: `Effective agents: ${settings.effective.join(", ")} (${scope}).`,
+                details: settings,
+            };
+        }
+        catch (error) {
+            return this.errorCheck("agents", "Cannot resolve effective agents.", error);
+        }
+    }
+    async checkProjectLock(projectDir) {
+        const lockPath = this.lockStore.getLockPath(projectDir);
+        const { lock, state } = await this.lockStore.loadWithState(projectDir);
+        if (state === "missing") {
+            return {
+                check: {
+                    name: "lock",
+                    status: "ok",
+                    message: "No himan.lock found for this project yet.",
+                    details: { lockPath },
+                },
+            };
+        }
+        if (state === "invalid" || !lock) {
+            return {
+                check: {
+                    name: "lock",
+                    status: "error",
+                    message: `Lock file is invalid: ${lockPath}`,
+                    details: { lockPath },
+                },
+            };
+        }
+        if (lock.resources.length === 0) {
+            return {
+                check: {
+                    name: "lock",
+                    status: "warn",
+                    message: "himan.lock has no resources.",
+                    details: { lockPath },
+                },
+                lock,
+            };
+        }
+        return {
+            check: {
+                name: "lock",
+                status: "ok",
+                message: `himan.lock tracks ${lock.resources.length} resources.`,
+                details: { lockPath, source: lock.source },
+            },
+            lock,
+        };
+    }
+    async checkProjectTargets(projectDir, lock) {
+        if (!lock || lock.resources.length === 0) {
+            return {
+                name: "targets",
+                status: "ok",
+                message: "No locked project targets to verify.",
+            };
+        }
+        const missing = [];
+        for (const resource of lock.resources) {
+            const agents = normalizeAgents(resource.agents);
+            const targets = getProjectResourcePaths(projectDir, resource.type, resource.name, agents);
+            for (const targetPath of targets) {
+                if (!(await this.exists(targetPath))) {
+                    missing.push({
+                        resource: `${resource.type}/${resource.name}@${resource.version}`,
+                        path: targetPath,
+                    });
+                }
+            }
+        }
+        if (missing.length > 0) {
+            return {
+                name: "targets",
+                status: "warn",
+                message: `Missing ${missing.length} installed targets. Run \`himan install\` to restore them.`,
+                details: { missing },
+            };
+        }
+        return {
+            name: "targets",
+            status: "ok",
+            message: "All locked project targets exist.",
+        };
+    }
     async list(type, agents) {
         const source = await this.loadSourceFromConfig();
         const resources = await source.list(type);
@@ -192,22 +440,33 @@ export class ServiceFactory {
         return this.installWithSource(source, undefined, type, name, version, projectDir, agents, mode, "global");
     }
     async dev(type, name, projectDir) {
-        const installInfo = await this.resolveInstalledResource(projectDir, type, name);
-        const installedPath = installInfo.installedPath;
-        const devPath = this.getProjectDevPath(projectDir, type, name);
-        if (!(await this.exists(devPath))) {
-            await fs.mkdir(path.dirname(devPath), { recursive: true });
-            await fs.cp(installedPath, devPath, { recursive: true });
+        const projectTarget = await this.tryResolveProjectResourceTarget(projectDir, type, name);
+        if (projectTarget) {
+            return {
+                type,
+                name,
+                devPath: projectTarget.resourcePath,
+                linkPath: projectTarget.linkPaths[0],
+                mode: projectTarget.mode,
+                sourceScope: "project",
+            };
         }
-        for (const linkPath of installInfo.linkPaths) {
-            await this.materializeResource(devPath, linkPath, installInfo.mode);
+        const globalTarget = await this.tryResolveGlobalResourceTarget(projectDir, type, name);
+        if (!globalTarget) {
+            throw new HimanError(errorCodes.INSTALL_NOT_FOUND, `Installed resource link not found for ${type}/${name}. Run install first.`);
+        }
+        const projectLinkPaths = getProjectResourcePaths(projectDir, type, name, globalTarget.agents);
+        for (const [index, linkPath] of projectLinkPaths.entries()) {
+            const sourcePath = globalTarget.linkPaths[index] ?? globalTarget.resourcePath;
+            await this.materializeResource(sourcePath, linkPath, "copy");
         }
         return {
             type,
             name,
-            devPath,
-            linkPath: installInfo.linkPaths[0],
-            mode: installInfo.mode,
+            devPath: projectLinkPaths[0],
+            linkPath: projectLinkPaths[0],
+            mode: "copy",
+            sourceScope: "global",
         };
     }
     async uninstall(type, name, projectDir) {
@@ -221,58 +480,142 @@ export class ServiceFactory {
         await this.lockStore.removeResource(projectDir, { type, name });
         return { type, name, linkPath: installInfo.linkPaths[0] };
     }
-    async publish(type, name, releaseType, projectDir) {
+    async publish(type, name, releaseType, projectDir, options = {}) {
+        const installScope = options.installScope ?? "project";
+        this.reportPublishProgress(options, "prepare", `Preparing ${type}/${name}.`);
         const source = await this.loadSourceFromConfig();
         const sourceDir = await this.resolvePublishSourceDir(type, name, projectDir);
         const existingInstallInfo = await this.tryResolveInstalledResource(projectDir, type, name);
+        const existingGlobalInstallInfo = await this.tryResolveGlobalResourceTarget(projectDir, type, name);
         const history = await source.history(type, name);
         const latest = history[0]?.version ?? "0.0.0";
         const nextVersion = this.versions.nextVersion(latest, releaseType);
+        this.reportPublishProgress(options, "resolve-version", `Resolved ${releaseType} version ${nextVersion}.`);
+        this.reportPublishProgress(options, "publish-source", `Publishing ${type}/${name}@${nextVersion} to the Git source.`);
         const result = await source.publish(type, name, nextVersion, sourceDir, {
             releaseType,
         });
         const storePath = this.getStorePath(type, name, nextVersion);
+        this.reportPublishProgress(options, "sync-store", `Syncing ${type}/${name}@${nextVersion} into the local store.`);
         if (!(await this.exists(storePath))) {
             await source.pull(type, name, nextVersion, storePath);
         }
         const locked = await this.getLockedResource(projectDir, type, name);
         const resourceMeta = await this.readResourceMetaFromDir(storePath, type);
         const configuredAgents = await this.getConfiguredAgents(projectDir);
-        const nextAgents = locked?.agents?.length
-            ? normalizeAgents(locked.agents)
-            : existingInstallInfo?.agents.length
-                ? normalizeAgents(existingInstallInfo.agents)
-                : configuredAgents ?? normalizeAgents(resourceMeta?.agents);
         const installMode = "copy";
-        const linkPaths = getProjectResourcePaths(projectDir, type, name, nextAgents);
+        const nextAgents = installScope === "global"
+            ? existingGlobalInstallInfo?.agents.length
+                ? normalizeAgents(existingGlobalInstallInfo.agents)
+                : existingInstallInfo?.agents.length
+                    ? normalizeAgents(existingInstallInfo.agents)
+                    : locked?.agents?.length
+                        ? normalizeAgents(locked.agents)
+                        : configuredAgents ?? normalizeAgents(resourceMeta?.agents)
+            : locked?.agents?.length
+                ? normalizeAgents(locked.agents)
+                : existingInstallInfo?.agents.length
+                    ? normalizeAgents(existingInstallInfo.agents)
+                    : configuredAgents ?? normalizeAgents(resourceMeta?.agents);
+        const linkPaths = installScope === "global"
+            ? getGlobalResourcePaths(this.paths.getHomeDir(), type, name, nextAgents)
+            : getProjectResourcePaths(projectDir, type, name, nextAgents);
+        this.reportPublishProgress(options, "install", installScope === "global"
+            ? `Installing published version globally for ${nextAgents.join(", ")}.`
+            : `Installing published version into the current project for ${nextAgents.join(", ")}.`);
         for (const linkPath of linkPaths) {
             await this.materializeResource(storePath, linkPath, installMode);
         }
-        const sourceInfo = await this.getLockSourceInfo();
-        await this.lockStore.upsertResource(projectDir, sourceInfo, {
-            type,
-            name,
-            version: nextVersion,
-            agents: nextAgents,
-            mode: installMode,
-        });
+        if (installScope === "project") {
+            const sourceInfo = await this.getLockSourceInfo();
+            await this.lockStore.upsertResource(projectDir, sourceInfo, {
+                type,
+                name,
+                version: nextVersion,
+                agents: nextAgents,
+                mode: installMode,
+            });
+        }
+        this.reportPublishProgress(options, "cleanup", `Cleaning up legacy dev copy if present.`);
         await fs.rm(this.getProjectDevPath(projectDir, type, name), {
             recursive: true,
             force: true,
         });
-        return { type, name, version: result.version, tag: result.tag };
+        this.reportPublishProgress(options, "done", `Published ${type}/${name}@${result.version}.`);
+        return {
+            type,
+            name,
+            version: result.version,
+            tag: result.tag,
+            installScope,
+            linkPath: linkPaths[0],
+        };
     }
     async create(type, name, options, projectDir) {
         this.validateCreateInput(type, name, options);
+        await this.loadSourceFromConfig();
+        const agents = await this.resolveEffectiveAgents(projectDir, options.agents);
+        const resourcePaths = getProjectResourcePaths(projectDir, type, name, agents);
+        const entry = options.entry ?? this.getDefaultEntry(type);
+        const files = resourcePaths.flatMap((resourcePath) => [
+            path.join(resourcePath, "himan.yaml"),
+            path.join(resourcePath, entry),
+        ]);
+        const existingPaths = [];
+        for (const resourcePath of resourcePaths) {
+            if (await this.exists(resourcePath))
+                existingPaths.push(resourcePath);
+        }
+        if (existingPaths.length > 0 && !options.force) {
+            throw new HimanError(errorCodes.RESOURCE_EXISTS, `Resource already exists: ${type}/${name}`, { paths: existingPaths });
+        }
+        if (!options.dryRun) {
+            for (const resourcePath of resourcePaths) {
+                await fs.rm(resourcePath, { recursive: true, force: true });
+                await fs.mkdir(resourcePath, { recursive: true });
+                await fs.writeFile(path.join(resourcePath, "himan.yaml"), YAML.stringify({
+                    name,
+                    type,
+                    version: "0.1.0",
+                    entry,
+                    description: options.description ?? `${type} resource ${name}`,
+                    agents,
+                }), "utf8");
+                await fs.writeFile(path.join(resourcePath, entry), this.getDefaultContent(type, name), "utf8");
+            }
+        }
+        return {
+            type,
+            name,
+            resourceDir: resourcePaths[0],
+            files,
+            dryRun: Boolean(options.dryRun),
+        };
+    }
+    async rename(type, oldName, newName, projectDir, options = {}) {
+        this.validateRenameInput(type, oldName, newName);
         const source = await this.loadSourceFromConfig();
-        return source.create(type, name, {
-            description: options.description,
-            agents: await this.resolveEffectiveAgents(projectDir, options.agents),
-            entry: options.entry,
-            template: options.template ?? "basic",
-            force: options.force,
+        const shouldMigrateProject = options.migrateProject !== false && !options.dryRun;
+        const locked = shouldMigrateProject
+            ? await this.getLockedResource(projectDir, type, oldName)
+            : undefined;
+        const installInfo = shouldMigrateProject
+            ? await this.tryResolveInstalledResource(projectDir, type, oldName)
+            : undefined;
+        const hasDevPath = shouldMigrateProject &&
+            (await this.exists(this.getProjectDevPath(projectDir, type, oldName)));
+        if (shouldMigrateProject && (locked || installInfo || hasDevPath)) {
+            await this.ensureRenamedProjectResourceAvailable(projectDir, type, oldName, newName, locked, installInfo);
+        }
+        const result = await source.rename(type, oldName, newName, {
             dryRun: options.dryRun,
         });
+        const projectMigrated = shouldMigrateProject &&
+            (await this.migrateRenamedProjectResource(source, type, oldName, newName, projectDir, result, locked, installInfo));
+        return {
+            ...result,
+            projectMigrated,
+        };
     }
     async installFromLock(projectDir, agents, mode) {
         const { lock, state } = await this.lockStore.loadWithState(projectDir);
@@ -331,6 +674,76 @@ export class ServiceFactory {
     async loadSourceFromConfig() {
         return (await this.loadSourceWithInfoFromConfig()).source;
     }
+    async resolveGitSourceEndpoint(ref) {
+        const config = await this.stateStore.loadConfig();
+        const configured = config?.sources?.items[ref];
+        if (configured) {
+            if (configured.type !== "git" || !configured.repo) {
+                throw new HimanError(errorCodes.INVALID_INPUT, `Source is not a git source: ${ref}`);
+            }
+            return {
+                name: ref,
+                repo: configured.repo,
+                repoId: configured.repoId ?? toRepoId(configured.repo),
+            };
+        }
+        if (!ref.trim()) {
+            throw new HimanError(errorCodes.INVALID_INPUT, "Git repo is required.");
+        }
+        return {
+            repo: ref,
+            repoId: toRepoId(ref),
+        };
+    }
+    async loadGitSourceFromEndpoint(endpoint) {
+        const sourceConfig = this.buildSourceConfig("git", endpoint.repo, endpoint.repoId);
+        const source = new GitSourceAdapter();
+        await source.init(sourceConfig);
+        return source;
+    }
+    validateSourceTransferOptions(targetRef, options) {
+        if (options.addSource) {
+            this.validateSourceName(options.addSource);
+        }
+        if (!options.use || options.addSource) {
+            return;
+        }
+        if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(targetRef)) {
+            throw new HimanError(errorCodes.INVALID_INPUT, "`--use` requires the target to be a configured source name or `--add-source <name>`.");
+        }
+    }
+    validateSourceTransferUseTarget(target, options) {
+        if (options.use && !options.addSource && !target.name) {
+            throw new HimanError(errorCodes.INVALID_INPUT, "`--use` requires the target to be a configured source name or `--add-source <name>`.");
+        }
+    }
+    ensureDifferentGitSources(source, target) {
+        if (source.repo === target.repo) {
+            throw new HimanError(errorCodes.INVALID_INPUT, "Source and target repositories must be different.");
+        }
+    }
+    async applySourceTransferConfigUpdates(target, options) {
+        if (options.dryRun)
+            return {};
+        let addedSource;
+        if (options.addSource) {
+            await this.addSource(options.addSource, "git", target.repo);
+            addedSource = options.addSource;
+        }
+        const sourceToUse = options.use ? options.addSource ?? target.name : undefined;
+        if (sourceToUse) {
+            await this.useSource(sourceToUse);
+        }
+        return {
+            addedSource,
+            usedSource: sourceToUse,
+        };
+    }
+    validateSourceName(name) {
+        if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) {
+            throw new HimanError(errorCodes.INVALID_INPUT, `Invalid source name: ${name}`);
+        }
+    }
     async loadSourceWithInfoFromConfig() {
         const { name, source: stateSource } = await this.getCurrentSourceState();
         const sourceInfo = this.toLockSourceInfo(stateSource, name);
@@ -391,6 +804,75 @@ export class ServiceFactory {
             return undefined;
         return lock.resources.find((item) => item.type === type && item.name === name);
     }
+    async ensureRenamedProjectResourceAvailable(projectDir, type, oldName, newName, locked, installInfo) {
+        const lockedNewName = await this.getLockedResource(projectDir, type, newName);
+        if (lockedNewName) {
+            throw new HimanError(errorCodes.RESOURCE_EXISTS, `Installed resource already exists: ${type}/${newName}`);
+        }
+        const newDevPath = this.getProjectDevPath(projectDir, type, newName);
+        if (await this.exists(newDevPath)) {
+            throw new HimanError(errorCodes.RESOURCE_EXISTS, `Development resource already exists: ${type}/${newName}`);
+        }
+        const agents = locked?.agents?.length
+            ? normalizeAgents(locked.agents)
+            : installInfo?.agents;
+        if (!agents?.length)
+            return;
+        for (const linkPath of getProjectResourcePaths(projectDir, type, newName, agents)) {
+            if (await this.exists(linkPath)) {
+                throw new HimanError(errorCodes.RESOURCE_EXISTS, `Installed resource already exists: ${type}/${newName}`);
+            }
+        }
+    }
+    async migrateRenamedProjectResource(source, type, oldName, newName, projectDir, result, locked, installInfo) {
+        const oldDevPath = this.getProjectDevPath(projectDir, type, oldName);
+        const newDevPath = this.getProjectDevPath(projectDir, type, newName);
+        const hasDevPath = await this.exists(oldDevPath);
+        if (!locked && !installInfo && !hasDevPath) {
+            return false;
+        }
+        let sourcePath;
+        if (hasDevPath) {
+            await fs.mkdir(path.dirname(newDevPath), { recursive: true });
+            await fs.rename(oldDevPath, newDevPath);
+            await this.updateRenamedResourceMetadata(newDevPath, type, oldName, newName);
+            sourcePath = newDevPath;
+        }
+        else if (result.latestVersion) {
+            const storePath = this.getStorePath(type, newName, result.latestVersion);
+            if (!(await this.exists(storePath))) {
+                await source.pull(type, newName, result.latestVersion, storePath);
+            }
+            sourcePath = storePath;
+        }
+        else if (installInfo) {
+            sourcePath = installInfo.installedPath;
+        }
+        else {
+            sourcePath = result.resourceDir;
+        }
+        const agents = locked?.agents?.length
+            ? normalizeAgents(locked.agents)
+            : installInfo?.agents ?? normalizeAgents();
+        const mode = installInfo?.mode ?? this.resolveInstallMode(locked?.mode);
+        const oldLinkPaths = installInfo?.linkPaths ?? getProjectResourcePaths(projectDir, type, oldName, agents);
+        const newLinkPaths = getProjectResourcePaths(projectDir, type, newName, agents);
+        for (const linkPath of newLinkPaths) {
+            await this.materializeResource(sourcePath, linkPath, mode);
+        }
+        for (const linkPath of oldLinkPaths) {
+            await fs.rm(linkPath, { recursive: true, force: true });
+        }
+        if (locked) {
+            await this.lockStore.renameResource(projectDir, {
+                type,
+                oldName,
+                newName,
+                version: result.latestVersion ?? locked.version,
+            });
+        }
+        return true;
+    }
     buildSourceConfig(type, repo, repoId) {
         if (type === "registry") {
             return { type };
@@ -433,6 +915,80 @@ export class ServiceFactory {
     resolveInstallMode(mode) {
         return mode === "link" ? "link" : "copy";
     }
+    reportPublishProgress(options, stage, message) {
+        options.onProgress?.({ stage, message });
+    }
+    async tryResolveProjectResourceTarget(projectDir, type, name) {
+        const locked = await this.getLockedResource(projectDir, type, name);
+        const configuredAgents = await this.getConfiguredAgents(projectDir);
+        if (locked?.agents?.length || configuredAgents?.length) {
+            const agents = locked?.agents?.length
+                ? normalizeAgents(locked.agents)
+                : (configuredAgents ?? normalizeAgents());
+            const linkPaths = getProjectResourcePaths(projectDir, type, name, agents);
+            const existingLinkPath = await this.findFirstExistingPath(linkPaths);
+            if (existingLinkPath) {
+                return {
+                    resourcePath: existingLinkPath,
+                    linkPaths,
+                    agents,
+                    mode: this.resolveInstallMode(locked?.mode ?? (await this.readPathMode(existingLinkPath))),
+                };
+            }
+        }
+        const existingCandidates = await this.findExistingAgentPaths(projectDir, type, name, "project");
+        if (existingCandidates.length === 0) {
+            return undefined;
+        }
+        const existingAgents = normalizeAgents(existingCandidates.map((candidate) => candidate.agent));
+        const linkPaths = getProjectResourcePaths(projectDir, type, name, existingAgents);
+        return {
+            resourcePath: existingCandidates[0].path,
+            linkPaths,
+            agents: existingAgents,
+            mode: await this.readPathMode(existingCandidates[0].path),
+        };
+    }
+    async tryResolveGlobalResourceTarget(projectDir, type, name) {
+        const existingCandidates = await this.findExistingAgentPaths(projectDir, type, name, "global");
+        if (existingCandidates.length === 0) {
+            return undefined;
+        }
+        const agents = normalizeAgents(existingCandidates.map((candidate) => candidate.agent));
+        const linkPaths = getGlobalResourcePaths(this.paths.getHomeDir(), type, name, agents);
+        return {
+            resourcePath: existingCandidates[0].path,
+            linkPaths,
+            agents,
+            mode: await this.readPathMode(existingCandidates[0].path),
+        };
+    }
+    async findExistingAgentPaths(projectDir, type, name, scope) {
+        const rootDir = scope === "global" ? this.paths.getHomeDir() : projectDir;
+        const candidates = getSupportedAgentNames().map((agent) => ({
+            agent,
+            path: scope === "global"
+                ? getGlobalResourcePaths(rootDir, type, name, [agent])[0]
+                : getProjectResourcePaths(rootDir, type, name, [agent])[0],
+        }));
+        const existingCandidates = [];
+        for (const candidate of candidates) {
+            if (await this.exists(candidate.path))
+                existingCandidates.push(candidate);
+        }
+        return existingCandidates;
+    }
+    async findFirstExistingPath(paths) {
+        for (const targetPath of paths) {
+            if (await this.exists(targetPath))
+                return targetPath;
+        }
+        return undefined;
+    }
+    async readPathMode(targetPath) {
+        const stat = await fs.lstat(targetPath);
+        return stat.isSymbolicLink() ? "link" : "copy";
+    }
     async resolveInstalledResource(projectDir, type, name) {
         const locked = await this.getLockedResource(projectDir, type, name);
         const configuredAgents = await this.getConfiguredAgents(projectDir);
@@ -546,6 +1102,48 @@ export class ServiceFactory {
                 this.readStringArrayMetadata(metadata, "targets"),
         };
     }
+    async updateRenamedResourceMetadata(resourceDir, type, oldName, newName) {
+        const yamlPath = path.join(resourceDir, "himan.yaml");
+        if (await this.exists(yamlPath)) {
+            const raw = await fs.readFile(yamlPath, "utf8");
+            const parsed = YAML.parse(raw);
+            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+                return;
+            }
+            await fs.writeFile(yamlPath, YAML.stringify({
+                ...parsed,
+                name: newName,
+            }), "utf8");
+            return;
+        }
+        if (type !== "skill")
+            return;
+        const entryPath = path.join(resourceDir, this.getDefaultEntry(type));
+        if (!(await this.exists(entryPath)))
+            return;
+        const raw = await fs.readFile(entryPath, "utf8");
+        const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(raw);
+        if (!match)
+            return;
+        let parsed;
+        try {
+            parsed = YAML.parse(match[1]);
+        }
+        catch {
+            return;
+        }
+        if (typeof parsed !== "object" ||
+            parsed === null ||
+            Array.isArray(parsed) ||
+            parsed.name !== oldName) {
+            return;
+        }
+        const frontMatter = YAML.stringify({
+            ...parsed,
+            name: newName,
+        }).trimEnd();
+        await fs.writeFile(entryPath, `---\n${frontMatter}\n---\n${raw.slice(match[0].length)}`, "utf8");
+    }
     async readFrontMatter(filePath) {
         const raw = await fs.readFile(filePath, "utf8");
         const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(raw.trimStart());
@@ -571,6 +1169,13 @@ export class ServiceFactory {
             .filter(Boolean);
         return items.length > 0 ? items : undefined;
     }
+    errorCheck(name, message, error) {
+        return {
+            name,
+            status: "error",
+            message: `${message} ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
     async exists(targetPath) {
         try {
             await fs.access(targetPath);
@@ -585,6 +1190,10 @@ export class ServiceFactory {
         if (await this.exists(devPath)) {
             return devPath;
         }
+        const projectTarget = await this.tryResolveProjectResourceTarget(projectDir, type, name);
+        if (projectTarget) {
+            return projectTarget.resourcePath;
+        }
         const repoResourceDir = await this.getRepoResourceDir(type, name);
         if (await this.exists(repoResourceDir)) {
             return repoResourceDir;
@@ -612,6 +1221,15 @@ export class ServiceFactory {
     getDefaultEntry(type) {
         return type === "skill" ? "SKILL.md" : "content.md";
     }
+    getDefaultContent(type, name) {
+        if (type === "rule") {
+            return `# ${name}\n\nDescribe rule instructions here.\n`;
+        }
+        if (type === "command") {
+            return `# ${name}\n\nDescribe command behavior here.\n`;
+        }
+        return `# ${name}\n\nDescribe skill workflow here.\n`;
+    }
     validateCreateInput(type, name, options) {
         if (!["rule", "command", "skill"].includes(type)) {
             throw new HimanError(errorCodes.UNSUPPORTED_RESOURCE_TYPE, `Unsupported resource type for create: ${type}`);
@@ -623,4 +1241,15 @@ export class ServiceFactory {
             throw new HimanError(errorCodes.TEMPLATE_NOT_FOUND, `Template not found: ${options.template}`);
         }
     }
+    validateRenameInput(type, oldName, newName) {
+        if (!["rule", "command", "skill"].includes(type)) {
+            throw new HimanError(errorCodes.UNSUPPORTED_RESOURCE_TYPE, `Unsupported resource type for rename: ${type}`);
+        }
+        if (oldName === newName) {
+            throw new HimanError(errorCodes.INVALID_INPUT, "Old and new resource names must be different.");
+        }
+        if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(newName)) {
+            throw new HimanError(errorCodes.INVALID_RESOURCE_NAME, `Invalid resource name: ${newName}. Use kebab-case only.`);
+        }
+    }
 }