@hi-man/himan 0.2.0 → 0.3.0

package/dist/adapters/source/git-source-adapter.js

@@ -3,9 +3,13 @@ import { ResourceScanner } from "../resource/resource-scanner.js";
 import semver from "semver";
 import { HimanError, errorCodes } from "../../utils/errors.js";
 import { promises as fs } from "node:fs";
+import { createHash } from "node:crypto";
 import path from "node:path";
 import YAML from "yaml";
 import { IndexCacheStore } from "../../state/index-cache-store.js";
+const RESOURCE_TYPES = ["rule", "command", "skill"];
+const README_RESOURCES_START = "<!-- himan:resources:start -->";
+const README_RESOURCES_END = "<!-- himan:resources:end -->";
 export class GitSourceAdapter {
     repoManager = new RepoManager();
     scanner = new ResourceScanner();
@@ -23,13 +27,13 @@ export class GitSourceAdapter {
         const repoId = this.sourceConfig?.repoId ?? "default";
         const typeDir = this.getTypeDir(type);
         const baseDir = path.join(repoDir, typeDir);
-        const baseDirMtimeMs = await this.getMtimeMs(baseDir);
+        const metadataHash = await this.getResourceMetadataHash(baseDir);
         const cached = await this.indexStore.get(repoId, type);
-        if (cached && cached.baseDirMtimeMs === baseDirMtimeMs) {
+        if (cached && cached.metadataHash === metadataHash) {
             return cached.resources;
         }
         const scanned = await this.scanner.scanByType(repoDir, type);
-        await this.indexStore.upsert(repoId, type, baseDirMtimeMs, scanned);
+        await this.indexStore.upsert(repoId, type, metadataHash, scanned);
         return scanned;
     }
     async history(type, name) {
@@ -47,6 +51,7 @@ export class GitSourceAdapter {
     async publish(type, name, version, sourceDir) {
         const repoDir = this.getRepoDir();
         const targetDir = path.join(repoDir, `${type}s`, name);
+        const metadata = await this.validatePublishResource(type, name, sourceDir);
         const sameDir = await this.isSameDirectory(sourceDir, targetDir);
         if (!sameDir) {
             await fs.rm(targetDir, { recursive: true, force: true });
@@ -54,14 +59,17 @@ export class GitSourceAdapter {
             await fs.cp(sourceDir, targetDir, { recursive: true });
         }
         const yamlPath = path.join(targetDir, "himan.yaml");
-        if (await this.exists(yamlPath)) {
-            const raw = await fs.readFile(yamlPath, "utf8");
-            const parsed = YAML.parse(raw);
-            parsed.version = version;
-            await fs.writeFile(yamlPath, YAML.stringify(parsed), "utf8");
-        }
+        metadata.version = version;
+        await fs.writeFile(yamlPath, YAML.stringify(metadata), "utf8");
+        const docsPaths = await this.maintainSourceDocs(repoDir, {
+            section: "Changed",
+            line: `- Published \`${type}/${name}@${version}\`.`,
+        });
         const tag = `${type}/${name}@${version}`;
-        await this.repoManager.commitTagAndPush(repoDir, `publish ${type}/${name}@${version}`, tag);
+        await this.repoManager.commitTagAndPush(repoDir, `publish ${type}/${name}@${version}`, tag, undefined, [
+            path.relative(repoDir, targetDir),
+            ...docsPaths.map((docPath) => path.relative(repoDir, docPath)),
+        ]);
         return { version, tag };
     }
     async create(type, name, options) {
@@ -69,7 +77,8 @@ export class GitSourceAdapter {
         const resourceDir = path.join(repoDir, this.getTypeDir(type), name);
         const entry = options.entry ?? this.getDefaultEntry(type);
         const agents = options.agents?.length ? options.agents : ["cursor"];
-        if ((await this.exists(resourceDir)) && !options.force) {
+        const resourceExists = await this.exists(resourceDir);
+        if (resourceExists && !options.force) {
             throw new HimanError(errorCodes.RESOURCE_EXISTS, `Resource already exists: ${type}/${name}`);
         }
         const files = [path.join(resourceDir, "himan.yaml"), path.join(resourceDir, entry)];
@@ -85,6 +94,12 @@ export class GitSourceAdapter {
                 agents,
             }), "utf8");
             await fs.writeFile(path.join(resourceDir, entry), this.getDefaultContent(type, name), "utf8");
+            await this.maintainSourceDocs(repoDir, {
+                section: resourceExists ? "Changed" : "Added",
+                line: resourceExists
+                    ? `- Updated \`${type}/${name}\`.`
+                    : `- Added \`${type}/${name}\`.`,
+            });
         }
         return {
             type,
@@ -94,6 +109,34 @@ export class GitSourceAdapter {
             dryRun: Boolean(options.dryRun),
         };
     }
+    async initDocs(options = {}) {
+        const repoDir = this.getRepoDir();
+        const files = [
+            {
+                path: path.join(repoDir, "README.md"),
+                content: await this.buildReadmeContent(repoDir),
+            },
+            {
+                path: path.join(repoDir, "CHANGELOG.md"),
+                content: this.buildChangelogContent(),
+            },
+        ];
+        const results = [];
+        for (const file of files) {
+            const exists = await this.exists(file.path);
+            const action = exists ? (options.force ? "updated" : "skipped") : "created";
+            const reason = action === "skipped" ? "file already exists" : undefined;
+            results.push({ path: file.path, action, reason });
+            if (!options.dryRun && action !== "skipped") {
+                await fs.writeFile(file.path, file.content, "utf8");
+            }
+        }
+        return {
+            sourceDir: repoDir,
+            files: results,
+            dryRun: Boolean(options.dryRun),
+        };
+    }
     getRepoDir() {
         if (!this.sourceConfig?.repoDir) {
             throw new HimanError(errorCodes.CONFIG_NOT_FOUND, "Git source is not initialized.");
@@ -118,14 +161,66 @@ export class GitSourceAdapter {
             return false;
         }
     }
-    async getMtimeMs(targetPath) {
+    async validatePublishResource(type, name, resourceDir) {
+        const yamlPath = path.join(resourceDir, "himan.yaml");
+        if (!(await this.exists(yamlPath))) {
+            throw this.invalidResourceMetadata(type, name, "Missing himan.yaml for publish.", { yamlPath });
+        }
+        const raw = await fs.readFile(yamlPath, "utf8");
+        let parsed;
         try {
-            const stat = await fs.stat(targetPath);
-            return stat.mtimeMs;
+            parsed = YAML.parse(raw);
         }
-        catch {
-            return 0;
+        catch (error) {
+            throw this.invalidResourceMetadata(type, name, "himan.yaml is not valid YAML.", { yamlPath, reason: error instanceof Error ? error.message : String(error) });
+        }
+        if (!this.isRecord(parsed)) {
+            throw this.invalidResourceMetadata(type, name, "himan.yaml must be an object.", { yamlPath });
+        }
+        if (parsed.name !== name) {
+            throw this.invalidResourceMetadata(type, name, `himan.yaml name must be "${name}".`, { yamlPath, actual: parsed.name });
+        }
+        if (parsed.type !== type) {
+            throw this.invalidResourceMetadata(type, name, `himan.yaml type must be "${type}".`, { yamlPath, actual: parsed.type });
+        }
+        if (typeof parsed.entry !== "string" || parsed.entry.trim().length === 0) {
+            throw this.invalidResourceMetadata(type, name, "himan.yaml entry is required.", { yamlPath });
+        }
+        const entry = parsed.entry.trim();
+        const entryPath = path.resolve(resourceDir, entry);
+        const resourceRoot = path.resolve(resourceDir);
+        const relativeEntryPath = path.relative(resourceRoot, entryPath);
+        if (path.isAbsolute(entry) ||
+            relativeEntryPath === "" ||
+            relativeEntryPath.startsWith("..") ||
+            path.isAbsolute(relativeEntryPath)) {
+            throw this.invalidResourceMetadata(type, name, "himan.yaml entry must point to a file inside the resource directory.", { yamlPath, entry });
         }
+        let entryStat;
+        try {
+            entryStat = await fs.stat(entryPath);
+        }
+        catch (error) {
+            if (!this.isNotFoundError(error)) {
+                throw error;
+            }
+            throw this.invalidResourceMetadata(type, name, `Resource entry file not found: ${entry}`, { yamlPath, entry, entryPath });
+        }
+        if (!entryStat.isFile()) {
+            throw this.invalidResourceMetadata(type, name, `Resource entry is not a file: ${entry}`, { yamlPath, entry, entryPath });
+        }
+        return {
+            ...parsed,
+            name,
+            type,
+            entry,
+        };
+    }
+    invalidResourceMetadata(type, name, message, details) {
+        return new HimanError(errorCodes.INVALID_RESOURCE_METADATA, `Invalid metadata for ${type}/${name}: ${message}`, details);
+    }
+    isRecord(value) {
+        return typeof value === "object" && value !== null && !Array.isArray(value);
     }
     getTypeDir(type) {
         if (type === "rule")
@@ -134,6 +229,42 @@ export class GitSourceAdapter {
             return "commands";
         return "skills";
     }
+    async getResourceMetadataHash(baseDir) {
+        const hash = createHash("sha256");
+        hash.update("himan-resource-index-v1");
+        if (!(await this.exists(baseDir))) {
+            hash.update("\0missing");
+            return hash.digest("hex");
+        }
+        const entries = await fs.readdir(baseDir, { withFileTypes: true });
+        const resourceDirNames = entries
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort();
+        for (const resourceDirName of resourceDirNames) {
+            hash.update("\0dir:");
+            hash.update(resourceDirName);
+            const yamlPath = path.join(baseDir, resourceDirName, "himan.yaml");
+            try {
+                const raw = await fs.readFile(yamlPath);
+                hash.update("\0yaml:");
+                hash.update(raw);
+            }
+            catch (error) {
+                if (!this.isNotFoundError(error)) {
+                    throw error;
+                }
+                hash.update("\0yaml-missing");
+            }
+        }
+        return hash.digest("hex");
+    }
+    isNotFoundError(error) {
+        return (typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            error.code === "ENOENT");
+    }
     getDefaultEntry(type) {
         return type === "skill" ? "SKILL.md" : "content.md";
     }
@@ -146,4 +277,200 @@ export class GitSourceAdapter {
         }
         return `# ${name}\n\nDescribe skill workflow here.\n`;
     }
+    async buildReadmeContent(repoDir) {
+        const resourceLines = await this.buildResourceIndex(repoDir);
+        const repo = this.sourceConfig?.repo ?? "<git_url>";
+        return [
+            `# ${this.getSourceTitle()}`,
+            "",
+            "Himan source repository for reusable agent resources.",
+            "",
+            "## Resources",
+            "",
+            README_RESOURCES_START,
+            ...resourceLines,
+            README_RESOURCES_END,
+            "",
+            "## Usage",
+            "",
+            "```bash",
+            `himan source add team ${repo}`,
+            "himan source use team",
+            "himan list rule",
+            "himan install rule <name>",
+            "```",
+            "",
+            "## Maintenance",
+            "",
+            "- Add resources with `himan create <type> <name>`.",
+            "- Publish resource versions with `himan publish <type> <name>`.",
+            "- Record source-level changes in `CHANGELOG.md`.",
+            "- Resource versions are tracked by Git tags such as `rule/code-review@1.0.0`.",
+            "",
+        ].join("\n");
+    }
+    buildChangelogContent() {
+        return [
+            "# Changelog",
+            "",
+            "All notable source-level resource changes are documented in this file.",
+            "",
+            "## [Unreleased]",
+            "",
+            "### Added",
+            "",
+            "- Initial source README/CHANGELOG scaffold.",
+            "",
+        ].join("\n");
+    }
+    async buildResourceIndex(repoDir) {
+        const sections = [];
+        for (const type of RESOURCE_TYPES) {
+            const resources = (await this.scanner.scanByType(repoDir, type)).sort((a, b) => a.name.localeCompare(b.name));
+            sections.push(`### ${this.getTypeLabel(type)}`, "");
+            if (resources.length === 0) {
+                sections.push(`- No ${type} resources yet.`, "");
+                continue;
+            }
+            for (const resource of resources) {
+                const version = await this.readResourceVersion(repoDir, resource.type, resource.name);
+                const ref = version
+                    ? `${resource.type}/${resource.name}@${version}`
+                    : `${resource.type}/${resource.name}`;
+                sections.push(`- \`${ref}\`${resource.description ? `: ${resource.description}` : ""}`);
+            }
+            sections.push("");
+        }
+        while (sections.at(-1) === "") {
+            sections.pop();
+        }
+        return sections;
+    }
+    async maintainSourceDocs(repoDir, changelogEntry) {
+        const readmePath = await this.updateReadmeResourceIndex(repoDir);
+        const changelogPath = await this.updateChangelog(repoDir, changelogEntry);
+        return [readmePath, changelogPath];
+    }
+    async updateReadmeResourceIndex(repoDir) {
+        const readmePath = path.join(repoDir, "README.md");
+        if (!(await this.exists(readmePath))) {
+            await fs.writeFile(readmePath, await this.buildReadmeContent(repoDir), "utf8");
+            return readmePath;
+        }
+        const current = await fs.readFile(readmePath, "utf8");
+        const resourceSection = [
+            README_RESOURCES_START,
+            ...(await this.buildResourceIndex(repoDir)),
+            README_RESOURCES_END,
+        ].join("\n");
+        const updated = this.replaceOrAppendReadmeResourceSection(current, resourceSection);
+        if (updated !== current) {
+            await fs.writeFile(readmePath, updated, "utf8");
+        }
+        return readmePath;
+    }
+    replaceOrAppendReadmeResourceSection(content, resourceSection) {
+        const startIndex = content.indexOf(README_RESOURCES_START);
+        const endIndex = content.indexOf(README_RESOURCES_END);
+        if (startIndex >= 0 && endIndex > startIndex) {
+            const before = content.slice(0, startIndex).replace(/\s*$/, "\n");
+            const after = content
+                .slice(endIndex + README_RESOURCES_END.length)
+                .replace(/^\s*/, "\n\n");
+            return `${before}${resourceSection}${after}`.replace(/\s*$/, "\n");
+        }
+        const base = content.replace(/\s*$/, "");
+        return `${base}\n\n## Resources\n\n${resourceSection}\n`;
+    }
+    async updateChangelog(repoDir, entry) {
+        const changelogPath = path.join(repoDir, "CHANGELOG.md");
+        const current = (await this.exists(changelogPath))
+            ? await fs.readFile(changelogPath, "utf8")
+            : this.buildChangelogBaseContent();
+        const updated = this.insertChangelogEntry(current, entry);
+        if (updated !== current) {
+            await fs.writeFile(changelogPath, updated, "utf8");
+        }
+        return changelogPath;
+    }
+    buildChangelogBaseContent() {
+        return [
+            "# Changelog",
+            "",
+            "All notable source-level resource changes are documented in this file.",
+            "",
+            "## [Unreleased]",
+            "",
+        ].join("\n");
+    }
+    insertChangelogEntry(content, entry) {
+        const lines = content.replace(/\s*$/, "").split("\n");
+        let unreleasedIndex = lines.findIndex((line) => line.trim() === "## [Unreleased]");
+        if (unreleasedIndex === -1) {
+            const firstVersionIndex = lines.findIndex((line) => line.startsWith("## "));
+            const insertIndex = firstVersionIndex === -1 ? lines.length : firstVersionIndex;
+            lines.splice(insertIndex, 0, "## [Unreleased]", "");
+            unreleasedIndex = insertIndex;
+        }
+        const blockEnd = this.findNextHeadingIndex(lines, unreleasedIndex + 1, "## ");
+        const unreleasedLines = lines.slice(unreleasedIndex, blockEnd);
+        if (unreleasedLines.includes(entry.line)) {
+            return `${lines.join("\n")}\n`;
+        }
+        const sectionHeading = `### ${entry.section}`;
+        const sectionIndex = lines.findIndex((line, index) => index > unreleasedIndex && index < blockEnd && line.trim() === sectionHeading);
+        if (sectionIndex >= 0) {
+            const insertIndex = lines[sectionIndex + 1] === "" ? sectionIndex + 2 : sectionIndex + 1;
+            lines.splice(insertIndex, 0, entry.line);
+            return `${lines.join("\n")}\n`;
+        }
+        const insertIndex = this.findChangelogSectionInsertIndex(lines, unreleasedIndex, blockEnd, entry.section);
+        lines.splice(insertIndex, 0, `### ${entry.section}`, "", entry.line, "");
+        return `${lines.join("\n").replace(/\s*$/, "")}\n`;
+    }
+    findNextHeadingIndex(lines, startIndex, headingPrefix) {
+        const found = lines.findIndex((line, index) => index >= startIndex && line.startsWith(headingPrefix));
+        return found === -1 ? lines.length : found;
+    }
+    findChangelogSectionInsertIndex(lines, unreleasedIndex, blockEnd, section) {
+        const sectionOrder = ["Added", "Changed"];
+        const sectionRank = sectionOrder.indexOf(section);
+        for (let index = unreleasedIndex + 1; index < blockEnd; index += 1) {
+            const line = lines[index].trim();
+            if (!line.startsWith("### "))
+                continue;
+            const foundSection = line.slice(4);
+            const foundRank = sectionOrder.indexOf(foundSection);
+            if (foundRank > sectionRank) {
+                return index;
+            }
+        }
+        return blockEnd;
+    }
+    async readResourceVersion(repoDir, type, name) {
+        const yamlPath = path.join(repoDir, this.getTypeDir(type), name, "himan.yaml");
+        try {
+            const raw = await fs.readFile(yamlPath, "utf8");
+            const parsed = YAML.parse(raw);
+            return typeof parsed?.version === "string" ? parsed.version : undefined;
+        }
+        catch (error) {
+            if (!this.isNotFoundError(error)) {
+                throw error;
+            }
+            return undefined;
+        }
+    }
+    getSourceTitle() {
+        const repo = this.sourceConfig?.repo?.replace(/\/$/, "");
+        const repoName = repo?.split(/[/:]/).at(-1)?.replace(/\.git$/, "");
+        return repoName ? `${repoName} Himan Source` : "Himan Source";
+    }
+    getTypeLabel(type) {
+        if (type === "rule")
+            return "Rules";
+        if (type === "command")
+            return "Commands";
+        return "Skills";
+    }
 }

package/dist/adapters/source/registry-source-adapter.js

@@ -18,4 +18,7 @@ export class RegistrySourceAdapter {
     async create(_type, _name, _options) {
         throw new HimanError(errorCodes.NOT_IMPLEMENTED, "Registry source is reserved for phase 2.");
     }
+    async initDocs(_options) {
+        throw new HimanError(errorCodes.NOT_IMPLEMENTED, "Registry source is reserved for phase 2.");
+    }
 }

package/dist/cli/builders.js

@@ -60,7 +60,7 @@ function appendCommandGroupsHelp(program) {
     program.addHelpText("after", `
 Command groups:
   source   Data source management (git now, registry reserved)
-           init, source init, source add, source use, source list
+           init, source init, source add, source use, source list, source init-docs
   resource Source resource discovery and metadata
            list, history, create, resource list, resource history, resource create
   project  Resource usage lifecycle in current project

package/dist/cli/source-commands.js

@@ -55,4 +55,26 @@ export function registerSourceCommands(command, services, options) {
             }
         });
     });
+    command
+        .command("init-docs")
+        .option("--force", "overwrite existing README.md and CHANGELOG.md")
+        .option("--dry-run", "show files without writing")
+        .option("--json", "output json format")
+        .description("Create source-level README.md and CHANGELOG.md")
+        .action(async (options) => {
+        await runAction(async () => {
+            const result = await services.initSourceDocs({
+                force: options.force,
+                dryRun: options.dryRun,
+            });
+            if (options.json) {
+                process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+                return;
+            }
+            process.stdout.write(`Source docs ${result.dryRun ? "dry-run" : "initialized"}: ${result.sourceDir}\n`);
+            for (const file of result.files) {
+                process.stdout.write(`- ${file.action} ${file.path}${file.reason ? ` (${file.reason})` : ""}\n`);
+            }
+        });
+    });
 }

package/dist/domain/source-docs.js

@@ -0,0 +1 @@
+export {};

package/dist/services/index.js

@@ -2,7 +2,7 @@ import { GitSourceAdapter } from "../adapters/source/git-source-adapter.js";
 import { RegistrySourceAdapter } from "../adapters/source/registry-source-adapter.js";
 import { StateStore } from "../state/state-store.js";
 import { ProjectConfigStore } from "../state/project-config-store.js";
-import { ProjectLockStore } from "../state/project-lock-store.js";
+import { ProjectLockStore, } from "../state/project-lock-store.js";
 import { PathResolver } from "../utils/path-resolver.js";
 import { toRepoId } from "../utils/repo-id.js";
 import { HimanError, errorCodes } from "../utils/errors.js";
@@ -101,6 +101,10 @@ export class ServiceFactory {
             isDefault: name === config.sources?.default,
         }));
     }
+    async initSourceDocs(options) {
+        const source = await this.loadSourceFromConfig();
+        return source.initDocs(options);
+    }
     async setAgents(agents, scope, projectDir) {
         const normalized = normalizeAgents(agents);
         if (scope === "project") {
@@ -158,31 +162,8 @@ export class ServiceFactory {
         return source.history(type, name);
     }
     async install(type, name, version, projectDir, agents, mode = "link") {
-        const source = await this.loadSourceFromConfig();
-        const sourceInfo = await this.getLockSourceInfo();
-        const history = await source.history(type, name);
-        if (history.length === 0) {
-            throw new HimanError(errorCodes.RESOURCE_NOT_FOUND, `Resource not found: ${type}/${name}`);
-        }
-        const resolvedVersion = this.resolveVersion(history, version);
-        const storePath = this.getStorePath(type, name, resolvedVersion);
-        if (!(await this.exists(storePath))) {
-            await source.pull(type, name, resolvedVersion, storePath);
-        }
-        const resourceMeta = await this.readResourceMetaFromDir(storePath);
-        const effectiveTargets = await this.resolveEffectiveAgents(projectDir, agents, resourceMeta?.agents);
-        const linkPaths = getProjectResourcePaths(projectDir, type, name, effectiveTargets);
-        for (const linkPath of linkPaths) {
-            await this.materializeResource(storePath, linkPath, mode);
-        }
-        await this.lockStore.upsertResource(projectDir, sourceInfo, {
-            type,
-            name,
-            version: resolvedVersion,
-            agents: effectiveTargets,
-            mode,
-        });
-        return { type, name, version: resolvedVersion, linkPath: linkPaths[0], mode };
+        const { source, sourceInfo } = await this.loadSourceWithInfoFromConfig();
+        return this.installWithSource(source, sourceInfo, type, name, version, projectDir, agents, mode);
     }
     async dev(type, name, projectDir) {
         const installInfo = await this.resolveInstalledResource(projectDir, type, name);
@@ -275,21 +256,69 @@ export class ServiceFactory {
             throw new HimanError(errorCodes.LOCK_NOT_FOUND, `Lock file has no resources: ${this.lockStore.getLockPath(projectDir)}`);
         }
         const results = [];
+        const lockSourceInfo = this.normalizeLockSourceInfo(lock.source);
+        const lockedSource = await this.loadSourceFromLock(lockSourceInfo);
         for (const item of lock.resources) {
-            const result = await this.install(item.type, item.name, item.version, projectDir, agents ?? item.agents, mode ?? this.resolveInstallMode(item.mode));
+            const result = await this.installWithSource(lockedSource, lockSourceInfo, item.type, item.name, item.version, projectDir, agents ?? item.agents, mode ?? this.resolveInstallMode(item.mode));
             results.push(result);
         }
         return results;
     }
+    async installWithSource(source, sourceInfo, type, name, version, projectDir, agents, mode) {
+        const history = await source.history(type, name);
+        if (history.length === 0) {
+            throw new HimanError(errorCodes.RESOURCE_NOT_FOUND, `Resource not found: ${type}/${name}`);
+        }
+        const resolvedVersion = this.resolveVersion(history, version);
+        const storePath = this.getStorePath(type, name, resolvedVersion);
+        if (!(await this.exists(storePath))) {
+            await source.pull(type, name, resolvedVersion, storePath);
+        }
+        const resourceMeta = await this.readResourceMetaFromDir(storePath);
+        const effectiveTargets = await this.resolveEffectiveAgents(projectDir, agents, resourceMeta?.agents);
+        const linkPaths = getProjectResourcePaths(projectDir, type, name, effectiveTargets);
+        for (const linkPath of linkPaths) {
+            await this.materializeResource(storePath, linkPath, mode);
+        }
+        await this.lockStore.upsertResource(projectDir, sourceInfo, {
+            type,
+            name,
+            version: resolvedVersion,
+            agents: effectiveTargets,
+            mode,
+        });
+        return { type, name, version: resolvedVersion, linkPath: linkPaths[0], mode };
+    }
     async loadSourceFromConfig() {
+        return (await this.loadSourceWithInfoFromConfig()).source;
+    }
+    async loadSourceWithInfoFromConfig() {
+        const { name, source: stateSource } = await this.getCurrentSourceState();
+        const sourceInfo = this.toLockSourceInfo(stateSource, name);
+        const source = await this.loadSourceFromInfo(sourceInfo);
+        return {
+            source,
+            sourceInfo,
+        };
+    }
+    async loadSourceFromLock(sourceInfo) {
+        return this.loadSourceFromInfo(sourceInfo);
+    }
+    async loadSourceFromInfo(sourceInfo) {
+        const normalizedSourceInfo = this.normalizeLockSourceInfo(sourceInfo);
+        const sourceConfig = this.buildSourceConfig(normalizedSourceInfo.type, normalizedSourceInfo.repo, normalizedSourceInfo.repoId);
+        const source = this.createSource(normalizedSourceInfo.type);
+        await source.init(sourceConfig);
+        return source;
+    }
+    async getCurrentSourceState() {
         const config = await this.stateStore.loadConfig();
         if (!config?.source) {
             throw new HimanError(errorCodes.CONFIG_NOT_FOUND, "Source config not found. Please run `himan init <git_repo>` first.");
         }
-        const sourceConfig = this.buildSourceConfig(config.source.type, config.source.repo, config.source.repoId);
-        const source = this.createSource(config.source.type);
-        await source.init(sourceConfig);
-        return source;
+        const currentName = config.sources?.default ?? "default";
+        const currentSource = config.sources?.items[currentName] ?? config.source;
+        return { name: currentName, source: currentSource };
     }
     createSource(type) {
         return type === "registry"
@@ -297,14 +326,24 @@ export class ServiceFactory {
             : new GitSourceAdapter();
     }
     async getLockSourceInfo() {
-        const config = await this.stateStore.loadConfig();
-        if (!config?.source) {
-            throw new HimanError(errorCodes.CONFIG_NOT_FOUND, "Source config not found. Please run `himan init <git_repo>` first.");
+        const { name, source } = await this.getCurrentSourceState();
+        return this.toLockSourceInfo(source, name);
+    }
+    toLockSourceInfo(source, name) {
+        return this.normalizeLockSourceInfo({
+            name,
+            type: source.type,
+            repo: source.repo,
+            repoId: source.repoId,
+        });
+    }
+    normalizeLockSourceInfo(sourceInfo) {
+        if (sourceInfo.type !== "git" || !sourceInfo.repo) {
+            return sourceInfo;
         }
         return {
-            type: config.source.type,
-            repo: config.source.repo,
-            repoId: config.source.repoId,
+            ...sourceInfo,
+            repoId: sourceInfo.repoId ?? toRepoId(sourceInfo.repo),
         };
     }
     async getLockedResource(projectDir, type, name) {

package/dist/state/index-cache-store.js

@@ -12,12 +12,13 @@ export class IndexCacheStore {
             return null;
         return data.entries.find((item) => item.repoId === repoId && item.type === type) ?? null;
     }
-    async upsert(repoId, type, baseDirMtimeMs, resources) {
+    async upsert(repoId, type, metadataHash, resources) {
         const now = new Date().toISOString();
         const file = (await this.load()) ?? { version: 1, entries: [] };
         const found = file.entries.find((item) => item.repoId === repoId && item.type === type);
         if (found) {
-            found.baseDirMtimeMs = baseDirMtimeMs;
+            found.metadataHash = metadataHash;
+            delete found.baseDirMtimeMs;
             found.resources = resources;
             found.updatedAt = now;
         }
@@ -25,7 +26,7 @@ export class IndexCacheStore {
             file.entries.push({
                 repoId,
                 type,
-                baseDirMtimeMs,
+                metadataHash,
                 resources,
                 updatedAt: now,
             });

package/dist/utils/errors.js

@@ -21,5 +21,7 @@ export const errorCodes = {
     RESOURCE_EXISTS: "E_RESOURCE_EXISTS",
     TEMPLATE_NOT_FOUND: "E_TEMPLATE_NOT_FOUND",
     INVALID_RESOURCE_NAME: "E_INVALID_RESOURCE_NAME",
+    INVALID_RESOURCE_METADATA: "E_INVALID_RESOURCE_METADATA",
+    PUBLISH_NO_CHANGES: "E_PUBLISH_NO_CHANGES",
     UNSUPPORTED_RESOURCE_TYPE: "E_UNSUPPORTED_RESOURCE_TYPE",
 };