@shirokuma-library/shirokuma-docs 0.1.0-alpha.5

package/dist/utils/setup-check.js

@@ -0,0 +1,136 @@
+/**
+ * GitHub setup validation utility (#345)
+ *
+ * Checks whether manual GitHub configuration steps have been completed:
+ * - Discussion categories (Handovers, ADR, Knowledge, Research)
+ * - Project workflow automations (Item closed → Done, PR merged → Done)
+ * - Metrics text fields (if metrics enabled)
+ */
+import { runGraphQL, getRepoInfo } from "./github.js";
+import { loadGhConfig, getMetricsConfig } from "./gh-config.js";
+import { getProjectId, fetchWorkflows, RECOMMENDED_WORKFLOWS, } from "../commands/projects.js";
+import { getProjectFields } from "./project-fields.js";
+// =============================================================================
+// Constants
+// =============================================================================
+const REQUIRED_DISCUSSION_CATEGORIES = ["Handovers", "ADR", "Knowledge", "Research"];
+// =============================================================================
+// GraphQL Query (reuse same shape as session.ts)
+// =============================================================================
+const GRAPHQL_QUERY_CATEGORIES = `
+query($owner: String!, $name: String!) {
+  repository(owner: $owner, name: $name) {
+    discussionCategories(first: 20) {
+      nodes {
+        id
+        name
+      }
+    }
+  }
+}
+`;
+// =============================================================================
+// Check Functions
+// =============================================================================
+function checkDiscussionCategories(owner, repo) {
+    const result = runGraphQL(GRAPHQL_QUERY_CATEGORIES, {
+        owner,
+        name: repo,
+    });
+    const nodes = result.success
+        ? (result.data?.data?.repository?.discussionCategories?.nodes ?? [])
+        : [];
+    const existingNames = new Set(nodes.map((n) => n?.name).filter(Boolean));
+    const categoriesUrl = `https://github.com/${owner}/${repo}/discussions/categories`;
+    return REQUIRED_DISCUSSION_CATEGORIES.map((cat) => ({
+        category: "discussions",
+        name: cat,
+        ok: existingNames.has(cat),
+        hint: existingNames.has(cat) ? undefined : `Create "${cat}" category in GitHub UI`,
+        url: existingNames.has(cat) ? undefined : categoriesUrl,
+    }));
+}
+function checkWorkflows(owner) {
+    const projectId = getProjectId(owner);
+    if (!projectId)
+        return [];
+    const workflows = fetchWorkflows(projectId);
+    if (workflows.length === 0)
+        return [];
+    return RECOMMENDED_WORKFLOWS.map((name) => {
+        const wf = workflows.find((w) => w.name === name);
+        const ok = wf?.enabled ?? false;
+        return {
+            category: "workflows",
+            name,
+            ok,
+            hint: ok ? undefined : `Enable "${name}" workflow in GitHub Project Settings > Workflows`,
+            url: ok ? undefined : undefined, // Project workflow settings URL is not stable
+        };
+    });
+}
+function checkMetricsFields(owner, metricsConfig) {
+    if (!metricsConfig.enabled)
+        return [];
+    const projectId = getProjectId(owner);
+    if (!projectId)
+        return [];
+    const fields = getProjectFields(projectId);
+    const mapping = metricsConfig.statusToDateMapping ?? {};
+    return Object.values(mapping).map((fieldName) => ({
+        category: "metrics",
+        name: fieldName,
+        ok: fieldName in fields && fields[fieldName].type === "TEXT",
+        hint: fieldName in fields
+            ? undefined
+            : `Create Text field "${fieldName}" in GitHub Project Settings > Fields`,
+    }));
+}
+// =============================================================================
+// Main Validation Function
+// =============================================================================
+/**
+ * Validate GitHub setup and return results
+ */
+export function validateGitHubSetup(logger) {
+    const repoInfo = getRepoInfo();
+    if (!repoInfo) {
+        logger.error("Could not determine repository");
+        return null;
+    }
+    const { owner: repoOwner, name: repo } = repoInfo;
+    const config = loadGhConfig();
+    const items = [
+        ...checkDiscussionCategories(repoOwner, repo),
+        ...checkWorkflows(repoOwner),
+        ...checkMetricsFields(repoOwner, getMetricsConfig(config)),
+    ];
+    const ok = items.filter((i) => i.ok).length;
+    return {
+        repository: `${repoOwner}/${repo}`,
+        items,
+        summary: {
+            total: items.length,
+            ok,
+            missing: items.length - ok,
+        },
+    };
+}
+/**
+ * Print setup check results to logger (human-friendly format)
+ */
+export function printSetupCheckResults(result, logger) {
+    for (const item of result.items) {
+        if (item.ok) {
+            logger.success(`${item.category}: ${item.name}`);
+        }
+        else {
+            logger.error(`${item.category}: ${item.name}`);
+            if (item.hint)
+                logger.info(`  → ${item.hint}`);
+            if (item.url)
+                logger.info(`  URL: ${item.url}`);
+        }
+    }
+}
+//# sourceMappingURL=setup-check.js.map

package/dist/utils/setup-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-check.js","sourceRoot":"","sources":["../../src/utils/setup-check.ts"],"names":[],"mappings":"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"}

package/dist/utils/shirokumaignore.d.ts

@@ -0,0 +1,55 @@
+/**
+ * .shirokumaignore Parser
+ *
+ * Parses .shirokumaignore files (gitignore-like syntax) for excluding
+ * files/directories from public repository releases via repo-pairs.
+ *
+ * Supported syntax:
+ * - Comments: lines starting with #
+ * - Blank lines: ignored
+ * - Glob patterns: same as rsync --exclude
+ * - Inline comments: `pattern # comment` (stripped)
+ * - CRLF line endings: handled transparently
+ */
+/** File name for project-level ignore patterns */
+export declare const SHIROKUMAIGNORE_FILENAME = ".shirokumaignore";
+/**
+ * Parse .shirokumaignore content into an array of exclude patterns.
+ *
+ * Rules:
+ * - Lines starting with # are comments (ignored)
+ * - Empty/whitespace-only lines are ignored
+ * - Leading/trailing whitespace is trimmed
+ * - Inline comments (` # ...`) are stripped
+ * - CRLF line endings are handled
+ *
+ * @param content - Raw file content
+ * @returns Array of exclude pattern strings
+ */
+export declare function parseShirokumaIgnore(content: string): string[];
+/**
+ * Load .shirokumaignore file from a project directory.
+ *
+ * Returns an empty array if the file does not exist or cannot be read.
+ * This makes the feature optional - projects without .shirokumaignore
+ * simply use config-only patterns.
+ *
+ * @param projectPath - Absolute path to the project root
+ * @returns Array of exclude patterns (empty if file not found)
+ */
+export declare function loadShirokumaIgnoreFile(projectPath: string): string[];
+/**
+ * Merge exclude patterns from multiple sources with deduplication.
+ *
+ * Priority order (all are additive):
+ * 1. Default patterns (base, always included)
+ * 2. Config patterns (from shirokuma-docs.config.yaml)
+ * 3. File patterns (from .shirokumaignore)
+ *
+ * @param defaultPatterns - Built-in default exclude patterns
+ * @param configPatterns - Patterns from config file
+ * @param filePatterns - Patterns from .shirokumaignore file
+ * @returns Deduplicated merged array of all patterns
+ */
+export declare function mergeExcludePatterns(defaultPatterns: string[], configPatterns: string[], filePatterns: string[]): string[];
+//# sourceMappingURL=shirokumaignore.d.ts.map

package/dist/utils/shirokumaignore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shirokumaignore.d.ts","sourceRoot":"","sources":["../../src/utils/shirokumaignore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,kDAAkD;AAClD,eAAO,MAAM,wBAAwB,qBAAqB,CAAC;AAE3D;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAc9D;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAcrE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAClC,eAAe,EAAE,MAAM,EAAE,EACzB,cAAc,EAAE,MAAM,EAAE,EACxB,YAAY,EAAE,MAAM,EAAE,GACrB,MAAM,EAAE,CAYV"}

package/dist/utils/shirokumaignore.js

@@ -0,0 +1,94 @@
+/**
+ * .shirokumaignore Parser
+ *
+ * Parses .shirokumaignore files (gitignore-like syntax) for excluding
+ * files/directories from public repository releases via repo-pairs.
+ *
+ * Supported syntax:
+ * - Comments: lines starting with #
+ * - Blank lines: ignored
+ * - Glob patterns: same as rsync --exclude
+ * - Inline comments: `pattern # comment` (stripped)
+ * - CRLF line endings: handled transparently
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/** File name for project-level ignore patterns */
+export const SHIROKUMAIGNORE_FILENAME = ".shirokumaignore";
+/**
+ * Parse .shirokumaignore content into an array of exclude patterns.
+ *
+ * Rules:
+ * - Lines starting with # are comments (ignored)
+ * - Empty/whitespace-only lines are ignored
+ * - Leading/trailing whitespace is trimmed
+ * - Inline comments (` # ...`) are stripped
+ * - CRLF line endings are handled
+ *
+ * @param content - Raw file content
+ * @returns Array of exclude pattern strings
+ */
+export function parseShirokumaIgnore(content) {
+    if (!content.trim())
+        return [];
+    return content
+        .split(/\r?\n/)
+        .map(line => {
+        // Strip inline comments (space + # + content)
+        const inlineCommentIndex = line.indexOf(" #");
+        if (inlineCommentIndex !== -1) {
+            line = line.substring(0, inlineCommentIndex);
+        }
+        return line.trim();
+    })
+        .filter(line => line.length > 0 && !line.startsWith("#"));
+}
+/**
+ * Load .shirokumaignore file from a project directory.
+ *
+ * Returns an empty array if the file does not exist or cannot be read.
+ * This makes the feature optional - projects without .shirokumaignore
+ * simply use config-only patterns.
+ *
+ * @param projectPath - Absolute path to the project root
+ * @returns Array of exclude patterns (empty if file not found)
+ */
+export function loadShirokumaIgnoreFile(projectPath) {
+    const filePath = join(projectPath, SHIROKUMAIGNORE_FILENAME);
+    if (!existsSync(filePath)) {
+        return [];
+    }
+    try {
+        const content = readFileSync(filePath, "utf-8");
+        return parseShirokumaIgnore(content);
+    }
+    catch {
+        // Gracefully handle read errors (permissions, etc.)
+        return [];
+    }
+}
+/**
+ * Merge exclude patterns from multiple sources with deduplication.
+ *
+ * Priority order (all are additive):
+ * 1. Default patterns (base, always included)
+ * 2. Config patterns (from shirokuma-docs.config.yaml)
+ * 3. File patterns (from .shirokumaignore)
+ *
+ * @param defaultPatterns - Built-in default exclude patterns
+ * @param configPatterns - Patterns from config file
+ * @param filePatterns - Patterns from .shirokumaignore file
+ * @returns Deduplicated merged array of all patterns
+ */
+export function mergeExcludePatterns(defaultPatterns, configPatterns, filePatterns) {
+    const seen = new Set();
+    const merged = [];
+    for (const pattern of [...defaultPatterns, ...configPatterns, ...filePatterns]) {
+        if (!seen.has(pattern)) {
+            seen.add(pattern);
+            merged.push(pattern);
+        }
+    }
+    return merged;
+}
+//# sourceMappingURL=shirokumaignore.js.map

package/dist/utils/shirokumaignore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shirokumaignore.js","sourceRoot":"","sources":["../../src/utils/shirokumaignore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,kDAAkD;AAClD,MAAM,CAAC,MAAM,wBAAwB,GAAG,kBAAkB,CAAC;AAE3D;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAe;IAClD,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,CAAC;IAE/B,OAAO,OAAO;SACX,KAAK,CAAC,OAAO,CAAC;SACd,GAAG,CAAC,IAAI,CAAC,EAAE;QACV,8CAA8C;QAC9C,MAAM,kBAAkB,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC9C,IAAI,kBAAkB,KAAK,CAAC,CAAC,EAAE,CAAC;YAC9B,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,kBAAkB,CAAC,CAAC;QAC/C,CAAC;QACD,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC;IACrB,CAAC,CAAC;SACD,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,uBAAuB,CAAC,WAAmB;IACzD,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,EAAE,wBAAwB,CAAC,CAAC;IAE7D,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1B,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAChD,OAAO,oBAAoB,CAAC,OAAO,CAAC,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,oDAAoD;QACpD,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,oBAAoB,CAClC,eAAyB,EACzB,cAAwB,EACxB,YAAsB;IAEtB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,KAAK,MAAM,OAAO,IAAI,CAAC,GAAG,eAAe,EAAE,GAAG,cAAc,EAAE,GAAG,YAAY,CAAC,EAAE,CAAC;QAC/E,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YACvB,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YAClB,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/utils/skills-repo.d.ts

@@ -0,0 +1,353 @@
+/**
+ * Bundled plugin utilities for shirokuma-skills-en
+ *
+ * @description Constants, validators, and helpers for installing/updating
+ * the bundled shirokuma-skills-en plugin. Skills and rules are bundled in
+ * the plugin/ directory within the shirokuma-docs npm package.
+ */
+/**
+ * Plugin name for the bundled skills/rules package
+ */
+export declare const PLUGIN_NAME = "shirokuma-skills-en";
+/**
+ * Japanese language plugin name (parallel plugin for i18n)
+ */
+export declare const PLUGIN_NAME_JA = "shirokuma-skills-ja";
+/**
+ * Hooks-only plugin name (language-independent safety hooks)
+ */
+export declare const PLUGIN_NAME_HOOKS = "shirokuma-hooks";
+/**
+ * Available skills list (matches actual plugin/skills/ directory names)
+ */
+export declare const AVAILABLE_SKILLS: readonly ["managing-agents", "managing-skills", "managing-plugins", "managing-output-styles", "managing-rules", "frontend-designing", "nextjs-vibe-coding", "reviewing-on-issue", "codebase-rule-discovery", "best-practices-researching", "claude-config-reviewing", "planning-on-issue", "working-on-issue", "committing-on-issue", "creating-pr-on-issue", "github-project-setup", "starting-session", "ending-session", "showing-github", "managing-github-items", "project-config-generator", "publishing"];
+/**
+ * Available rules list
+ */
+export declare const AVAILABLE_RULES: readonly ["best-practices-first.md", "config-authoring-flow.md", "git-commit-style.md", "output-destinations.md", "skill-authoring.md", "github/branch-workflow.md", "github/discussions-usage.md", "github/pr-review-response.md", "github/project-items.md", "nextjs/known-issues.md", "nextjs/lib-structure.md", "nextjs/radix-ui-hydration.md", "nextjs/server-actions.md", "nextjs/tailwind-v4.md", "nextjs/tech-stack.md", "nextjs/testing.md", "shirokuma-docs/cli-invocation.md", "shirokuma-docs/plugin-cache.md", "shirokuma-docs/shirokuma-annotations.md"];
+/**
+ * Deploy target directory for rules (relative to project root)
+ */
+export declare const DEPLOYED_RULES_DIR = ".claude/rules/shirokuma";
+/**
+ * Deploy target directory for Japanese rules (relative to project root)
+ */
+export declare const DEPLOYED_RULES_DIR_JA = ".claude/rules/shirokuma-ja";
+/**
+ * Gitignore entries managed by shirokuma-docs init
+ */
+export declare const GITIGNORE_ENTRIES: string[];
+/**
+ * Result of registering the plugin in Claude Code's global cache
+ */
+export interface CacheRegistrationResult {
+    success: boolean;
+    method: "install" | "reinstall" | "skipped";
+    message?: string;
+}
+/**
+ * Deploy options for deployRules()
+ */
+export interface DeployRulesOptions {
+    /** Preview mode - report what would change without writing */
+    dryRun?: boolean;
+    /** Enable verbose logging */
+    verbose?: boolean;
+    /** Override bundled plugin path (for JA plugin support) */
+    bundledPluginPath?: string;
+    /** Override deploy target directory (for JA plugin support) */
+    targetDir?: string;
+}
+/**
+ * Result for a single deployed rule
+ */
+export interface DeployedRuleItem {
+    name: string;
+    status: "deployed" | "updated" | "unchanged" | "removed" | "error";
+    reason?: string;
+}
+/**
+ * Full deploy result
+ */
+export interface DeployResult {
+    deployed: DeployedRuleItem[];
+    targetDir: string;
+    /** デプロイ対象に含まれないファイル（管理外） */
+    unmanagedFiles: string[];
+}
+/**
+ * Get path to a bundled plugin directory by name
+ *
+ * Resolves the plugin directory relative to this module's location.
+ * In development: {repo-root}/plugin/{pluginName}/
+ * When installed: {node_modules/shirokuma-docs}/plugin/{pluginName}/
+ *
+ * @param pluginName - Plugin directory name
+ * @returns Absolute path to the bundled plugin directory
+ */
+export declare function getBundledPluginPathFor(pluginName: string): string;
+/**
+ * Get path to the bundled plugin directory (EN)
+ *
+ * @returns Absolute path to the bundled plugin directory
+ */
+export declare function getBundledPluginPath(): string;
+/**
+ * Get path to the bundled Japanese plugin directory
+ *
+ * @returns Absolute path to the bundled Japanese plugin directory
+ */
+export declare function getBundledPluginPathJa(): string;
+/**
+ * Check if the Japanese plugin is bundled in this package
+ *
+ * @returns true if the Japanese plugin directory exists
+ */
+export declare function hasJaPlugin(): boolean;
+/**
+ * Check if the hooks plugin is bundled in this package
+ *
+ * @returns true if the hooks plugin directory exists
+ */
+export declare function hasHooksPlugin(): boolean;
+/**
+ * Get version from package.json
+ *
+ * @returns Package version string or "unknown"
+ */
+export declare function getPackageVersion(): string;
+/**
+ * Get version from the bundled plugin's plugin.json
+ *
+ * @returns Plugin version string or "unknown"
+ */
+export declare function getPluginVersion(): string;
+/**
+ * Validate skill name against AVAILABLE_SKILLS list
+ *
+ * @param skill - Skill name to validate
+ * @returns true if skill is in the available list
+ */
+export declare function isValidSkill(skill: string): skill is typeof AVAILABLE_SKILLS[number];
+/**
+ * Validate skill name format (prevents path traversal)
+ *
+ * Accepts: lowercase alphanumeric + hyphens (e.g., "managing-agents", "reviewing-on-issue")
+ * Rejects: dots, slashes, underscores, spaces, uppercase, empty strings
+ *
+ * @param name - Skill name to validate
+ * @returns true if the name is a safe, valid format
+ */
+export declare function isValidSkillName(name: string): boolean;
+/**
+ * Get list of skill names from the bundled plugin directory
+ *
+ * Scans the plugin/skills/ directory to detect available skills,
+ * independent of the AVAILABLE_SKILLS constant.
+ *
+ * @returns Array of valid skill names found in the bundled plugin
+ */
+export declare function getBundledSkillNames(): string[];
+/**
+ * Get list of rule file paths from the bundled plugin directory
+ *
+ * Scans plugin/rules/ up to 2 levels deep (root + 1 subdirectory),
+ * returning relative paths like "best-practices-first.md",
+ * "github/project-items.md", etc.
+ *
+ * Note: Matches the depth of getInstalledRules(). If deeper nesting
+ * is needed in the future, both functions should be updated together.
+ *
+ * @returns Array of relative rule file paths
+ */
+export declare function getBundledRuleNames(): string[];
+/**
+ * Get list of rule file paths from a given rules directory
+ *
+ * Scans up to 2 levels deep (root + 1 subdirectory).
+ *
+ * @param rulesDir - Absolute path to rules directory
+ * @returns Array of relative rule file paths
+ */
+export declare function getBundledRuleNamesFrom(rulesDir: string): string[];
+/**
+ * Detect if the project is the shirokuma-docs repository itself
+ *
+ * When running inside the shirokuma-docs repo, the bundled plugin source
+ * (plugin/shirokuma-skills-en/) is directly available, so copying to
+ * .claude/plugins/ is unnecessary.
+ *
+ * @param projectPath - Project root path
+ * @returns true if the project contains the plugin source
+ */
+export declare function isSelfRepo(projectPath: string): boolean;
+/**
+ * Get the effective plugin directory for a project
+ *
+ * For self-repo (shirokuma-docs itself): returns the bundled source path
+ * For external projects: global cache → bundled fallback
+ *
+ * @param projectPath - Project root path
+ * @returns Absolute path to the effective plugin directory
+ */
+export declare function getEffectivePluginDir(projectPath: string): string;
+/**
+ * Install the bundled plugin to a project (self-repo 用)
+ *
+ * self-repo（shirokuma-docs 自身）では bundled source を直接使用するためスキップ。
+ * 外部プロジェクトでは ensureMarketplace() + registerPluginCache() を使用する。
+ * この関数は後方互換性のために残しているが、外部プロジェクトでのローカルコピーは
+ * 不要になった。
+ *
+ * @param projectPath - Target project root path
+ * @param verbose - Enable verbose logging
+ * @returns true on success, false on failure
+ */
+export declare function installPlugin(projectPath: string, verbose: boolean, pluginName?: string): Promise<boolean>;
+/**
+ * Get list of installed skill names from a project
+ *
+ * Scans the effective plugin directory for installed skills.
+ * For self-repo, reads from bundled source; otherwise from .claude/plugins/.
+ *
+ * @param projectPath - Project root path
+ * @returns Array of installed skill names
+ */
+export declare function getInstalledSkills(projectPath: string): string[];
+/**
+ * Get list of installed rule names from a project
+ *
+ * Scans the effective plugin directory for installed rules.
+ * For self-repo, reads from bundled source; otherwise from .claude/plugins/.
+ *
+ * @param projectPath - Project root path
+ * @returns Array of installed rule file paths
+ */
+export declare function getInstalledRules(projectPath: string): string[];
+/**
+ * .gitignore にエントリを追加する（重複チェック付き）
+ *
+ * @param projectPath - プロジェクトルートパス
+ * @param options - オプション（dryRun, verbose）
+ * @returns 追加されたエントリ数
+ */
+export declare function updateGitignore(projectPath: string, options?: {
+    dryRun?: boolean;
+    verbose?: boolean;
+}): {
+    added: string[];
+    alreadyPresent: string[];
+};
+/**
+ * .gitignore から特定のエントリを削除する
+ *
+ * @param projectPath - プロジェクトルートパス
+ * @param entry - 削除するエントリ（例: ".claude/plugins/"）
+ * @returns true: 削除成功、false: エントリが見つからないまたはファイルなし
+ */
+export declare function removeGitignoreEntry(projectPath: string, entry: string): boolean;
+/**
+ * レガシー .claude/plugins/ ディレクトリを削除する（マイグレーション用）
+ *
+ * 旧バージョンの init で作成された .claude/plugins/ ディレクトリと
+ * 対応する .gitignore エントリを削除する。
+ *
+ * @param projectPath - プロジェクトルートパス
+ */
+export declare function cleanupLegacyPluginDir(projectPath: string): void;
+/**
+ * Deploy plugin rules to .claude/rules/shirokuma/ for Claude Code auto-loading
+ *
+ * Copies rule files from the bundled plugin directly to the target directory.
+ * The shirokuma/ directory is fully owned by shirokuma-docs, so files are
+ * always overwritten without conflict detection.
+ *
+ * @param projectPath - Target project root path
+ * @param options - Deploy options (dryRun, verbose)
+ * @returns Deploy result with per-file status
+ */
+export declare function deployRules(projectPath: string, options?: DeployRulesOptions): Promise<DeployResult>;
+/**
+ * マーケットプレース名（marketplace.json の name フィールドで解決）
+ */
+export declare const MARKETPLACE_NAME = "shirokuma-library";
+/**
+ * マーケットプレースリポジトリ
+ */
+export declare const MARKETPLACE_REPO = "ShirokumaLibrary/shirokuma-plugins";
+/**
+ * マーケットプレースが登録済みか確認し、未登録なら追加する
+ *
+ * `claude plugin marketplace list` で確認し、MARKETPLACE_NAME が
+ * 含まれていなければ `claude plugin marketplace add` で登録する。
+ *
+ * 既存の登録（directory/github）は上書きしない。
+ *
+ * @returns true: 登録済みまたは登録成功、false: 登録失敗
+ */
+export declare function ensureMarketplace(): boolean;
+/**
+ * グローバルキャッシュ内のプラグインディレクトリパスを解決する
+ *
+ * キャッシュパス: ~/.claude/plugins/cache/{marketplace}/{pluginName}/{version}/
+ *
+ * @param pluginName - プラグイン名
+ * @param version - 特定バージョン（省略時は最新を自動検出）
+ * @returns キャッシュパス、見つからない場合は null
+ */
+export declare function getGlobalCachePath(pluginName: string, version?: string): string | null;
+/**
+ * Plugin identifier for Claude Code's plugin registry
+ */
+export declare const PLUGIN_REGISTRY_ID = "shirokuma-skills-en@shirokuma-library";
+/**
+ * Japanese plugin identifier for Claude Code's plugin registry
+ */
+export declare const PLUGIN_REGISTRY_ID_JA = "shirokuma-skills-ja@shirokuma-library";
+/**
+ * Hooks plugin identifier for Claude Code's plugin registry
+ */
+export declare const PLUGIN_REGISTRY_ID_HOOKS = "shirokuma-hooks@shirokuma-library";
+/**
+ * Register the plugin in Claude Code's global cache
+ *
+ * Runs `claude plugin install` to copy from .claude/plugins/ to the global
+ * cache (~/.claude/plugins/cache/). Claude Code only reads skills from the
+ * global cache, not the project-local directory.
+ *
+ * @param projectPath - Project root path
+ * @param options - Registration options
+ * @returns Registration result
+ */
+export declare function registerPluginCache(projectPath: string, options?: {
+    reinstall?: boolean;
+    registryId?: string;
+}): CacheRegistrationResult;
+/**
+ * Check if the `claude` CLI is available in PATH
+ *
+ * @returns true if claude CLI is installed and accessible
+ */
+export declare function isClaudeCliAvailable(): boolean;
+/**
+ * プロジェクトの .claude/settings.json から language 設定を読み取る
+ *
+ * @param projectPath - プロジェクトルートパス
+ * @returns "english" | "japanese" | null（未設定時）
+ */
+export declare function getLanguageSetting(projectPath: string): string | null;
+/**
+ * Remove all deployed rules by deleting .claude/rules/shirokuma/ directory
+ *
+ * The shirokuma/ directory is fully owned by shirokuma-docs, so the entire
+ * directory is removed without per-file checks.
+ *
+ * @param projectPath - Project root path
+ * @param options - Clean options (dryRun, verbose)
+ * @returns Array of removed items (for reporting)
+ */
+export declare function cleanDeployedRules(projectPath: string, options?: {
+    dryRun?: boolean;
+    verbose?: boolean;
+}): Promise<DeployedRuleItem[]>;
+//# sourceMappingURL=skills-repo.d.ts.map

package/dist/utils/skills-repo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills-repo.d.ts","sourceRoot":"","sources":["../../src/utils/skills-repo.ts"],"names":[],"mappings":"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"}