@hi-man/himan 0.4.0 → 0.5.0

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();
@@ -176,6 +180,46 @@ 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.checkProjectArchiveStatus(lockCheck.lock));
+        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);
@@ -188,14 +232,231 @@ export class ServiceFactory {
         });
         return { scope };
     }
-    async list(type, agents) {
+    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 checkProjectArchiveStatus(lock) {
+        if (!lock || lock.resources.length === 0) {
+            return {
+                name: "archive",
+                status: "ok",
+                message: "No locked resources to check for archive status.",
+            };
+        }
+        try {
+            const source = await this.loadSourceFromLock(this.normalizeLockSourceInfo(lock.source));
+            const archived = [];
+            for (const resource of lock.resources) {
+                if (await source.isArchived(resource.type, resource.name)) {
+                    archived.push(`${resource.type}/${resource.name}@${resource.version}`);
+                }
+            }
+            if (archived.length > 0) {
+                return {
+                    name: "archive",
+                    status: "warn",
+                    message: `${archived.length} locked resources are archived in the current source.`,
+                    details: { resources: archived },
+                };
+            }
+            return {
+                name: "archive",
+                status: "ok",
+                message: "No locked resources are archived in the current source.",
+            };
+        }
+        catch (error) {
+            return {
+                name: "archive",
+                status: "warn",
+                message: `Cannot check archived resources. ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    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, options = {}) {
         const source = await this.loadSourceFromConfig();
-        const resources = await source.list(type);
+        const resources = await source.list(type, options);
         if (!agents?.length)
             return resources;
         const selected = normalizeAgents(agents);
         return resources.filter((resource) => normalizeAgents(resource.agents).some((agent) => selected.includes(agent)));
     }
+    async archive(type, name, options = {}) {
+        this.validateResourceIdentity(type, name, "archive");
+        const source = await this.loadSourceFromConfig();
+        return source.archive(type, name, {
+            ...options,
+            reason: options.reason?.trim(),
+        });
+    }
+    async restore(type, name, options = {}) {
+        this.validateResourceIdentity(type, name, "restore");
+        const source = await this.loadSourceFromConfig();
+        return source.restore(type, name, options);
+    }
     async listInstalled(projectDir, type, agents) {
         const { lock, state } = await this.lockStore.loadWithState(projectDir);
         if (state === "invalid") {
@@ -222,31 +483,42 @@ export class ServiceFactory {
         const source = await this.loadSourceFromConfig();
         return source.history(type, name);
     }
-    async install(type, name, version, projectDir, agents, mode = "copy") {
+    async install(type, name, version, projectDir, agents, mode = "copy", options = {}) {
         const { source, sourceInfo } = await this.loadSourceWithInfoFromConfig();
-        return this.installWithSource(source, sourceInfo, type, name, version, projectDir, agents, mode);
+        return this.installWithSource(source, sourceInfo, type, name, version, projectDir, agents, mode, "project", options);
     }
-    async installGlobal(type, name, version, projectDir, agents, mode = "copy") {
+    async installGlobal(type, name, version, projectDir, agents, mode = "copy", options = {}) {
         const source = await this.loadSourceFromConfig();
-        return this.installWithSource(source, undefined, type, name, version, projectDir, agents, mode, "global");
+        return this.installWithSource(source, undefined, type, name, version, projectDir, agents, mode, "global", options);
     }
     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) {
@@ -260,58 +532,120 @@ 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();
+        if (await source.isArchived(type, name)) {
+            throw new HimanError(errorCodes.RESOURCE_ARCHIVED, `Resource is archived: ${type}/${name}. Restore it before publishing a new version.`);
+        }
         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);
-        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,
-            dryRun: options.dryRun,
-        });
+        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);
@@ -353,12 +687,16 @@ export class ServiceFactory {
         const lockSourceInfo = this.normalizeLockSourceInfo(lock.source);
         const lockedSource = await this.loadSourceFromLock(lockSourceInfo);
         for (const item of lock.resources) {
-            const result = await this.installWithSource(lockedSource, lockSourceInfo, item.type, item.name, item.version, projectDir, agents ?? item.agents, mode ?? this.resolveInstallMode(item.mode), "project");
+            const result = await this.installWithSource(lockedSource, lockSourceInfo, item.type, item.name, item.version, projectDir, agents ?? item.agents, mode ?? this.resolveInstallMode(item.mode), "project", { includeArchived: true });
             results.push(result);
         }
         return results;
     }
-    async installWithSource(source, sourceInfo, type, name, version, projectDir, agents, mode, scope = "project") {
+    async installWithSource(source, sourceInfo, type, name, version, projectDir, agents, mode, scope = "project", options = {}) {
+        const archived = await source.isArchived(type, name);
+        if (archived && !options.includeArchived) {
+            throw new HimanError(errorCodes.RESOURCE_ARCHIVED, `Resource is archived: ${type}/${name}. Use --include-archived to install an archived version explicitly.`);
+        }
         const history = await source.history(type, name);
         if (history.length === 0) {
             throw new HimanError(errorCodes.RESOURCE_NOT_FOUND, `Resource not found: ${type}/${name}`);
@@ -636,6 +974,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);
@@ -816,6 +1228,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);
@@ -830,6 +1249,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;
@@ -857,6 +1280,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}`);
@@ -868,6 +1300,14 @@ export class ServiceFactory {
             throw new HimanError(errorCodes.TEMPLATE_NOT_FOUND, `Template not found: ${options.template}`);
         }
     }
+    validateResourceIdentity(type, name, action) {
+        if (!["rule", "command", "skill"].includes(type)) {
+            throw new HimanError(errorCodes.UNSUPPORTED_RESOURCE_TYPE, `Unsupported resource type for ${action}: ${type}`);
+        }
+        if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) {
+            throw new HimanError(errorCodes.INVALID_RESOURCE_NAME, `Invalid resource name: ${name}. Use kebab-case only.`);
+        }
+    }
     validateRenameInput(type, oldName, newName) {
         if (!["rule", "command", "skill"].includes(type)) {
             throw new HimanError(errorCodes.UNSUPPORTED_RESOURCE_TYPE, `Unsupported resource type for rename: ${type}`);

package/dist/utils/errors.js

@@ -13,6 +13,7 @@ export const errorCodes = {
     NOT_IMPLEMENTED: "E_NOT_IMPLEMENTED",
     INVALID_INPUT: "E_INVALID_INPUT",
     RESOURCE_NOT_FOUND: "E_RESOURCE_NOT_FOUND",
+    RESOURCE_ARCHIVED: "E_RESOURCE_ARCHIVED",
     VERSION_NOT_FOUND: "E_VERSION_NOT_FOUND",
     INSTALL_NOT_FOUND: "E_INSTALL_NOT_FOUND",
     LOCK_NOT_FOUND: "E_LOCK_NOT_FOUND",

package/docs/error-codes.md

@@ -58,6 +58,12 @@
 - **常见触发**：安装不存在的资源、切换到不存在的 source 名称、发布目标资源不存在。
 - **建议处理**：先执行 `himan list <type>` / `himan source list` 确认名称。
 
+### `E_RESOURCE_ARCHIVED`
+
+- **含义**：资源已归档，默认不允许作为 active 资源继续使用。
+- **常见触发**：直接安装或发布已归档资源，或重复归档已经在 `archive/<plural>/<name>` 下的资源。
+- **建议处理**：如需继续维护，先执行 `himan resource restore <type> <name>`；如只需安装历史版本，显式传 `--include-archived`。
+
 ### `E_VERSION_NOT_FOUND`
 
 - **含义**：指定版本不存在。