diff --git a/ai_docs/tests/herdr_install_plan_runbook.md b/ai_docs/tests/herdr_install_plan_runbook.md new file mode 100644 index 000000000..0f0b5a964 --- /dev/null +++ b/ai_docs/tests/herdr_install_plan_runbook.md @@ -0,0 +1,65 @@ +# CLI E2E Runbook: Herdr Install Plan + +Verifies that the panel offers the same skill paths the CLI installs, rather than target copies. + +**Origin**: [#838](https://github.com/runkids/skillshare/issues/838) — false install success and mismatched discovery. + +## Scope + +- CLI-owned discovery excludes target copies and applies `.skillignore`. +- The panel uses canonical names and paths, including generic-directory frontmatter names. +- A selected plan leads to the same installed content; dry-run does not install. +- Old CLI output without a plan is rejected, and non-zero install exits are failures. + +## Environment + +Run inside the devcontainer with mdproof's per-runbook HOME isolation. Requires Git, Node and jq. +All fixtures are under the isolated HOME. No network access or running Herdr window is required. + +## Steps + +### 1. Preview, parse, audit and install the selected skill + +```bash +set -euo pipefail +repo="$HOME/issue838-repo" +mkdir -p "$repo/.claude/skills/design" "$repo/cli/assets/design" "$repo/skills" "$repo/ignored" +printf '# Target copy\n' > "$repo/.claude/skills/design/SKILL.md" +printf '# Authored design\n' > "$repo/cli/assets/design/SKILL.md" +printf '%s\n' '---' 'name: Custom Tool' '---' '# Authored tool' > "$repo/skills/SKILL.md" +printf '# Ignored\n' > "$repo/ignored/SKILL.md" +printf 'ignored/\n' > "$repo/.skillignore" +git -C "$repo" init -q +git -C "$repo" -c user.email=test@example.com -c user.name=Test add . +git -C "$repo" -c user.email=test@example.com -c user.name=Test commit -qm fixture +/workspace/bin/skillshare install "file://$repo" --dry-run --json --kind skill -g > "$HOME/issue838-plan.json" +jq -e '.skills == [] and .failed == [] and .planned == [{"name":"design","path":"cli/assets/design"},{"name":"custom-tool","path":"skills"}]' "$HOME/issue838-plan.json" >/dev/null +test ! -f "$HOME/.config/skillshare/skills/design/SKILL.md" +node --input-type=module <<'JS' +import assert from 'node:assert/strict'; +import { readFileSync } from 'node:fs'; +import { parseDiscover, installResult } from '/workspace/herdr/skillshare/mods/skillshare/model.js'; +const plan = readFileSync(`${process.env.HOME}/issue838-plan.json`, 'utf8'); +const result = parseDiscover(`@dir /fixture\n${plan}`); +assert.equal(result.error, null); +assert.deepEqual(result.choices[0], { name: 'design', path: 'cli/assets/design' }); +assert.match(parseDiscover('@dir /fixture\n{"skills":[]}').error, /upgrade/i); +assert.ok(installResult({code: 1, stdout: '{"skills":[],"failed":[]}'}).error); +JS +/workspace/bin/skillshare audit "$repo/cli/assets/design" --json -g >/dev/null +/workspace/bin/skillshare install "file://$repo" --skill design --json --kind skill -g > "$HOME/issue838-result.json" +jq -e '.skills == ["design"] and .failed == [] and (has("planned") | not)' "$HOME/issue838-result.json" >/dev/null +cmp "$repo/cli/assets/design/SKILL.md" "$HOME/.config/skillshare/skills/design/SKILL.md" +test ! -f "$HOME/.config/skillshare/skills/custom-tool/SKILL.md" +printf 'INSTALL_PLAN_OK\n' +``` + +Expected: +- exit_code: 0 +- INSTALL_PLAN_OK + +## Pass Criteria + +- All steps pass. +- Only the selected authored skill is installed, with the same content the panel planned and audited. +- Legacy CLI output cannot produce a false install success or an unsafe fallback pick list. diff --git a/cmd/skillshare/install.go b/cmd/skillshare/install.go index 09b0f0809..b5572f032 100644 --- a/cmd/skillshare/install.go +++ b/cmd/skillshare/install.go @@ -27,14 +27,15 @@ type installArgs struct { // installJSONOutput is the JSON representation for install --json output. type installJSONOutput struct { - Source string `json:"source"` - Tracked bool `json:"tracked"` - DryRun bool `json:"dry_run"` - Into string `json:"into,omitempty"` - Skills []string `json:"skills"` - Failed []string `json:"failed"` - Duration string `json:"duration"` - Error string `json:"error,omitempty"` + Source string `json:"source"` + Tracked bool `json:"tracked"` + DryRun bool `json:"dry_run"` + Into string `json:"into,omitempty"` + Skills []string `json:"skills"` + Failed []string `json:"failed"` + Duration string `json:"duration"` + Error string `json:"error,omitempty"` + Planned *[]installPlannedSkill `json:"planned,omitempty"` } type installLogSummary struct { @@ -43,6 +44,7 @@ type installLogSummary struct { SkillCount int InstalledSkills []string FailedSkills []string + PlannedSkills []installPlannedSkill DryRun bool Tracked bool Into string @@ -579,6 +581,9 @@ func installOutputJSON(summary installLogSummary, start time.Time, installErr er Failed: summary.FailedSkills, Duration: formatDuration(start), } + if summary.PlannedSkills != nil { + output.Planned = &summary.PlannedSkills + } if installErr != nil { output.Error = installErr.Error() } diff --git a/cmd/skillshare/install_handlers.go b/cmd/skillshare/install_handlers.go index 5b2a8d8c2..7f1b8c005 100644 --- a/cmd/skillshare/install_handlers.go +++ b/cmd/skillshare/install_handlers.go @@ -165,6 +165,7 @@ func handleGitInstall(source *install.Source, cfg *config.Config, opts install.I return logSummary, err } defer install.CleanupDiscovery(discovery) + logSummary.planSkills(source, nil) treeSpinner.Stop() ui.StepDone("Source", sourceLabel(source.Raw)) @@ -211,6 +212,7 @@ func handleGitInstall(source *install.Source, cfg *config.Config, opts install.I skill.Name = opts.Name } ui.StepContinue("Found", fmt.Sprintf("1 skill: %s", skill.Name)) + logSummary.planSkills(source, []install.SkillInfo{skill}) renderSkillMeta(skill) @@ -295,6 +297,7 @@ func handleGitInstall(source *install.Source, cfg *config.Config, opts install.I } skill.Name = opts.Name } + logSummary.planSkills(source, []install.SkillInfo{skill}) renderSkillMeta(skill) @@ -343,6 +346,7 @@ func handleGitInstall(source *install.Source, cfg *config.Config, opts install.I } if opts.DryRun { + logSummary.planSkills(source, selected) if err := checkIntoFolder(cfg.EffectiveSkillsSource(), opts); err != nil { return logSummary, err } @@ -857,6 +861,7 @@ func handleDirectInstall(source *install.Source, cfg *config.Config, opts instal // Set the name in source for display source.Name = skillName + logSummary.planSkills(source, []install.SkillInfo{{Name: skillName, Path: "."}}) // Determine destination path destPath := destWithInto(cfg.EffectiveSkillsSource(), opts, skillName) diff --git a/cmd/skillshare/install_plan.go b/cmd/skillshare/install_plan.go new file mode 100644 index 000000000..883eb3045 --- /dev/null +++ b/cmd/skillshare/install_plan.go @@ -0,0 +1,28 @@ +package main + +import ( + "path/filepath" + + "skillshare/internal/install" +) + +// installPlannedSkill identifies a selected skill without claiming it was installed. +// Git paths are relative to the repository root, including an explicit subdirectory. +type installPlannedSkill struct { + Name string `json:"name"` + Path string `json:"path"` +} + +func (s *installLogSummary) planSkills(source *install.Source, skills []install.SkillInfo) { + if !s.DryRun { + return + } + s.PlannedSkills = make([]installPlannedSkill, 0, len(skills)) + for _, skill := range skills { + path := skill.Path + if source.IsGit() && source.HasSubdir() { + path = filepath.ToSlash(filepath.Join(source.Subdir, path)) + } + s.PlannedSkills = append(s.PlannedSkills, installPlannedSkill{Name: skill.Name, Path: path}) + } +} diff --git a/cmd/skillshare/install_plan_test.go b/cmd/skillshare/install_plan_test.go new file mode 100644 index 000000000..1c3d21a0b --- /dev/null +++ b/cmd/skillshare/install_plan_test.go @@ -0,0 +1,47 @@ +package main + +import ( + "os" + "path/filepath" + "reflect" + "testing" + + "skillshare/internal/config" + "skillshare/internal/install" +) + +func TestHandleGitInstall_SubdirPlan(t *testing.T) { + for _, nested := range []bool{false, true} { + t.Run(map[bool]string{false: "single", true: "collection"}[nested], func(t *testing.T) { + repo := t.TempDir() + subdir := ".claude/skills/explicit" + paths := []string{"."} + want := []installPlannedSkill{{Name: "explicit", Path: subdir}} + if nested { + paths = []string{"a", "b"} + want = []installPlannedSkill{{Name: "a", Path: subdir + "/a"}, {Name: "b", Path: subdir + "/b"}} + } + for _, path := range paths { + dir := filepath.Join(repo, subdir, path) + if err := os.MkdirAll(dir, 0755); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(dir, "SKILL.md"), []byte("# Skill"), 0644); err != nil { + t.Fatal(err) + } + } + initGitRepoForTest(t, repo) + source := &install.Source{Type: install.SourceTypeGitHTTPS, Raw: "file://" + repo + "/" + subdir, CloneURL: "file://" + repo, Subdir: subdir, Name: "explicit"} + cfg := &config.Config{Source: t.TempDir()} + captureStdoutStderr(t, func() { + summary, err := handleGitInstall(source, cfg, install.InstallOptions{DryRun: true, All: true, Force: true}) + if err != nil { + t.Fatal(err) + } + if !reflect.DeepEqual(summary.PlannedSkills, want) { + t.Fatalf("planned = %+v, want %+v", summary.PlannedSkills, want) + } + }) + }) + } +} diff --git a/herdr/skillshare/README.md b/herdr/skillshare/README.md index 3b216e39f..13e1c89af 100644 --- a/herdr/skillshare/README.md +++ b/herdr/skillshare/README.md @@ -71,11 +71,14 @@ Read ~/.config/herdr-app/AGENTS.md, then replace the files in mods/skillshare wi - Per scope, one detached script runs `list --all`, `diff`, `mcp list`, `plugin list` and `hooks list` with `--json`. `check` and `check agents` run every 10 minutes. Git state comes from `git status` in the source repository, because the CLI has no JSON for it. -- The CLI's install dry-run does not list a repository's skills, so the install dialog - shallow-clones the repository to a temp folder to offer the pick list. It then runs - `skillshare audit --json` on that clone, because `install --json` names a blocked - skill but not its findings. A block shows the findings before anything is written; - "Install anyway" reruns the install with `--force`. +- The install dialog reads canonical names and repository-relative paths from + `skillshare install --dry-run --json --kind skill` (`planned`), so its pick list + follows the CLI's discovery and ignore rules. Older CLIs without `planned` must be + upgraded on that machine before installing through the panel. Ambiguous names are refused. + A separate shallow clone is kept for `skillshare audit --json`, so a block shows + findings before anything is written; "Install anyway" runs the install with `--force`. + Any non-zero install exit is shown as a failure, even when an older CLI omits `error`. + Preview, audit and install fetch separately; a moving upstream branch can change between them. - The panel's version is `mods/skillshare/version.js`, the skillshare release it shipped with. Once an hour while shown, the panel asks where `github.com/runkids/skillshare/releases/latest` lands (`curl`, on this computer) and offers the update when that release is newer. The update diff --git a/herdr/skillshare/RECIPE.md b/herdr/skillshare/RECIPE.md index 568c4cb21..213ada666 100644 --- a/herdr/skillshare/RECIPE.md +++ b/herdr/skillshare/RECIPE.md @@ -52,9 +52,10 @@ Left to right, everything as in Herdr's `main` layout, plus two blocks: - Hook conflicts block `sync --all` for every resource kind; resolve them in the CLI or dashboard before retrying. - Sync, on Overview, syncs every scope that has something waiting in the scope the switch shows, and also runs `sync plugins` when a plugin waits. Sync in Library does the same, and with nothing waiting it syncs the shown scope again. - The install button opens a URL dialog with recent sources: - - a repository with several skills shows a pick list, marking the ones that would replace an installed skill; + - a repository with several skills shows a pick list from the CLI's `install --dry-run --json --kind skill` plan (`planned`), marking replacements; names and paths follow the CLI's discovery and ignore rules. Ambiguous names are refused. Older CLIs without the plan must be upgraded on that machine; - a progress view then runs Download (a shallow clone), Audit (`skillshare audit --json` on the clone) and Install; - - a blocked audit stops before anything is written and shows its findings, with "Ask to review…", Cancel and Install anyway (`--force`). + - a blocked audit stops before anything is written and shows its findings, with "Ask to review…", Cancel and Install anyway (`--force`); + - any non-zero install exit is a failure, even if the JSON has no `error` (older CLIs). - The source dialog lists uncommitted files and offers: - Sync both ways…; - Pull, which stays disabled while there are uncommitted changes or nothing to pull; @@ -102,7 +103,7 @@ Left to right, everything as in Herdr's `main` layout, plus two blocks: - Herdr stops an `exec` after 30 s. Long commands (the list snapshot, check, doctor, install, update, sync, pull, push, upgrade, the panel update) run detached into a temp folder on that machine, and the panel polls for their exit code. Herdr ends an exec's whole process group when it returns, and hangs up programs that still carry the exec's `HC_SCOPE`, so each job drops `HC_SCOPE` and gets its own group (`setsid`, or sh job control where `setsid` is missing, as on macOS). The panel checks every 5 s that the job still runs, and reports "skillshare stopped before it finished" when it was killed instead of waiting the full 15 minutes. A panel closed mid-job never collects the result, so the first job on each machine removes `skillshare-panel.*` folders unchanged for 15 minutes whose job no longer runs. - The CLI has no JSON for git state. Git state comes from `git status --porcelain=v1 --branch`. -- The CLI's install dry-run does not list a repository's skills, and `install --json` names a blocked skill without its findings. That is why the install dialog clones and audits on its own. +- The CLI's dry-run `planned` field owns skill discovery; the dialog does not scan for skills itself. `install --json` names a blocked skill without its findings, so the dialog keeps a separate clone for audit. Preview, audit and install fetch separately; a moving upstream branch can change between them. - `install --json` overwrites a skill of the same name. The dialog asks before replacing one. - Keep the panel out of the `panel` stack. Herdr's tabs mod restores that stack per space, so a panel there closes on every space switch. - `cx.notify()` throws during `render`, and `cx.spawn` runs its body up to its first `await` at once, so work started from `render` waits for the render to end first (`later`). Otherwise the error is swallowed and the button does nothing. diff --git a/herdr/skillshare/mods/skillshare/main.js b/herdr/skillshare/mods/skillshare/main.js index 2e28a203b..0f9585868 100644 --- a/herdr/skillshare/mods/skillshare/main.js +++ b/herdr/skillshare/mods/skillshare/main.js @@ -12,7 +12,7 @@ import { exec, hc, run, spaces, agents, focused, machines, shared, setShared, th import { KINDS, SCOPES, DISCOVER, AUDIT, parseJSON, lastLine, failure, flag, sourceLine, buildItems, hookArgs, toggleArgs, rowState, previewTargets, eligibleTargets, targetList, waitsForSync, syncScopes, overviewAnswer, remoteLine, waitingNames, mapLanes, needsBothWays, filterItems, groupItems, sourceGroups, counts, - cloneUrl, skillChoices, newerVersion, panelUpdate, updateState, ago, auditMessage, parseDiscover, parseAudit, + cloneUrl, installResult, newerVersion, panelUpdate, updateState, ago, auditMessage, parseDiscover, parseAudit, } from "./model.js"; import { createRunner } from "./jobs.js"; import { createChannel, EVERY } from "./channel.js"; @@ -1086,20 +1086,20 @@ export default class Skillshare extends View { this.dropClone(p); this.discovering = true; this.error = null; cx.notify(); cx.spawn(async (cx) => { - const r = await sh(DISCOVER, [target.url, ...(target.branch ? [target.branch] : [])], p.on); + const { job } = machineIO(cx); + const r = await job([source, target.url, target.branch ?? "", flag(this.scope)], { + on: p.on, cwd: this.scope === "project" ? p.project : null, script: DISCOVER, + }); this.discovering = false; - if (this.closed) { const d = parseDiscover(r.stdout).dir; if (d) sh('rm -rf "$1"', [d], p.on); return; } - if (r.code !== 0) { this.error = lastLine(r.stderr) || lastLine(r.stdout) || "Could not read the repository"; cx.notify(); return; } - const { dir, paths } = parseDiscover(r.stdout); + const { dir, choices, error } = parseDiscover(r.stdout); this.dir = dir; this.source = source; - const repoName = target.url.replace(/\.git$/, "").split("/").pop(); - if (target.single) { - const folder = target.path.replace(/\/SKILL\.md$/, ""); - return this.startInstall(cx, [{ path: paths.includes(folder) ? folder : null, name: folder.split("/").pop() }], null); + if (this.closed) { this.dropClone(p); return; } + if (r.code !== 0 || error) { + this.dropClone(p); + this.error = r.code !== 0 ? (lastLine(r.stderr) || error || "Could not read the repository") : error; + cx.notify(); return; } - if (paths.includes(".")) return this.startInstall(cx, [{ path: ".", name: repoName }], null); - const choices = skillChoices(paths); - if (!choices.length) { this.dropClone(p); this.error = "No SKILL.md in this repository."; cx.notify(); return; } + if (!choices.length) { this.dropClone(p); this.error = "No installable skills in this repository."; cx.notify(); return; } if (choices.length === 1) return this.startInstall(cx, choices, null); this.found = choices; this.picked = new Set(); this.step = "pick"; cx.notify(); }); @@ -1138,12 +1138,11 @@ export default class Skillshare extends View { if (a.blocked.length) { pr.blocked = a; cx.notify(); return; } pr.at = 2; cx.notify(); } - const args = ["install", this.source, "--json", flag(this.scope), ...(pr.skills?.length ? ["--skill", pr.skills.join(",")] : []), ...(pr.force ? ["--force"] : [])]; + const args = ["install", this.source, "--json", "--kind", "skill", flag(this.scope), ...(pr.skills?.length ? ["--skill", pr.skills.join(",")] : []), ...(pr.force ? ["--force"] : [])]; const r = await job(args, opt); - const j = parseJSON(r.stdout); - if (j?.error || (!j && r.code !== 0)) pr.error = j?.error ?? failure(r, "skillshare install"); - else if (j?.failed?.length) pr.error = `Installed ${plural(j.skills?.length ?? 0, "skill")}; ${j.failed.join(", ")} failed. The install's own audit can stop one.`; - else { pr.at = 3; pr.done = j?.skills ?? []; } + const result = installResult(r); + if (result.error) pr.error = result.error; + else { pr.at = 3; pr.done = result.done; } this.dropClone(p); } finally { channel.release(p.on); } request({ op: "refresh", on: p.on }); diff --git a/herdr/skillshare/mods/skillshare/model.js b/herdr/skillshare/mods/skillshare/model.js index 405b19d7f..3a4079fd5 100644 --- a/herdr/skillshare/mods/skillshare/model.js +++ b/herdr/skillshare/mods/skillshare/model.js @@ -73,14 +73,13 @@ export function parseSnapshot(text) { // sh -c PROJECT : prints the folder when skillshare treats it as a project. export const PROJECT = '[ -f "$1/.skillshare/config.yaml" ] || [ -f "$1/skillshare/config.yaml" ] && printf "%s" "$1"'; -// sh -c DISCOVER [branch]: "@dir " (the clone is kept in /r for the -// audit step; the caller removes it), then the skill folders, one per line ("." for a skill at -// the root). The CLI's install dry-run does not list them. -export const DISCOVER = `d=$(mktemp -d) -GIT_TERMINAL_PROMPT=0 git clone -q --depth 1 \${2:+-b "$2"} "$1" "$d/r" >/dev/null 2>"$d/err" || { tail -n 1 "$d/err" >&2; rm -rf "$d"; exit 1; } +// Through START_SCRIPT: DISCOVER <-g|-p>. +// Keep a clone for audit, then ask the CLI for canonical names and repository-relative paths. +export const DISCOVER = `${TEMP} +GIT_TERMINAL_PROMPT=0 git clone -q --depth 1 \${4:+-b "$4"} "$3" "$d/r" >/dev/null 2>"$d/err" || { tail -n 1 "$d/err" >&2; rm -rf "$d"; exit 1; } echo "@dir $d" -cd "$d/r" || exit 1 -find . -name SKILL.md -not -path './.git/*' -not -path '*/node_modules/*' | sed 's|/SKILL.md$||; s|^\\./||' | sort`; +cd "$1" 2>/dev/null || cd +skillshare install "$2" --dry-run --json --kind skill "$5"`; // Through START_SCRIPT: AUDIT <-g|-p> . One // "@@ " line, then that folder's `skillshare audit --json`, per folder. @@ -577,9 +576,18 @@ export function cloneUrl(source) { return { url: `https://${repo}.git`, single, path, branch: onBranch && parts[4] ? parts[4] : "" }; } -// Skill folders → what `install --skill` takes (the folder's own name). -export function skillChoices(paths) { - return paths.filter((p) => p && p !== ".").map((p) => ({ path: p, name: p.split("/").pop() })); +// Keep exit status authoritative even with valid JSON from an older CLI. +export function installResult(r) { + const j = parseJSON(r.stdout), done = j?.skills ?? [], failed = j?.failed ?? []; + if (j?.error) return { done: null, error: j.error }; + if (r.code !== 0) { + const details = [done.length ? `Installed: ${done.join(", ")}.` : "", failed.length ? `Failed: ${failed.join(", ")}.` : "", lastLine(r.stderr)].filter(Boolean); + details.push(`skillshare install exited with ${r.code}.`); + return { done: null, error: details.join(" ") }; + } + if (failed.length) return { done: null, error: `Installed ${done.length} skill(s); ${failed.join(", ")} failed. The install's own audit can stop one.` }; + if (!j) return { done: null, error: failure(r, "skillshare install returned no JSON") }; + return { done, error: null }; } export function newerVersion(a, b) { @@ -644,11 +652,23 @@ export function auditMessage(item) { return `Audit the ${item.kind === "agents" ? "agent" : "skill"} "${item.name}": run \`skillshare audit ${kind}${item.name}${flag} --json\` and \`skillshare diff${flag}\`. Summarize what changed and any findings, then wait for me.`; } -// DISCOVER's output → the kept clone folder and the skill folders in it. +// DISCOVER's output → the audit clone and the CLI's exact install plan. Never fall back +// to filesystem discovery: it can audit one directory and install a different one. export function parseDiscover(text) { - const lines = String(text ?? "").split("\n").map((l) => l.trim()).filter(Boolean); + const lines = String(text ?? "").trim().split("\n"); const dir = lines[0]?.startsWith("@dir ") ? lines.shift().slice(5) : null; - return { dir, paths: lines }; + const j = parseJSON(lines.join("\n")); + const fail = (error) => ({ dir, choices: [], error }); + if (j?.error) return fail(j.error); + if (!Array.isArray(j?.planned)) return fail("Upgrade skillshare on this machine: this CLI does not provide an install plan."); + const names = new Set(); + for (const skill of j.planned) { + if (!skill.name || !skill.path) return fail("The CLI returned an incomplete install plan."); + const key = skill.name.toLowerCase(); + if (names.has(key)) return fail(`Ambiguous install name: ${skill.name}. Use an explicit skill URL instead.`); + names.add(key); + } + return { dir, choices: j.planned, error: null }; } const SEVERITY = ["CRITICAL", "HIGH", "MEDIUM", "LOW", "INFO"]; diff --git a/herdr/tests/model.test.mjs b/herdr/tests/model.test.mjs index 9906219ed..26d100fe6 100644 --- a/herdr/tests/model.test.mjs +++ b/herdr/tests/model.test.mjs @@ -4,7 +4,7 @@ import { spawn, spawnSync } from "node:child_process"; import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, readdirSync, existsSync, rmSync, utimesSync } from "node:fs"; import { tmpdir } from "node:os"; import { join } from "node:path"; -import { parseGitStatus, sourceLine, driftFrom, targetDrift, buildItems, hookArgs, counts, groupItems, filterItems, sourceGroups, cloneUrl, skillChoices, newerVersion, parseDiscover, parseAudit, parsePreview, diffSides, mergeMetadata, START, ALIVE, SWEEP, SNAPSHOT, parseSnapshot, rowState, previewTargets, splitFrontmatter, mcpServer, targetList, mapLanes, needsBothWays, READ_SKILL, eligibleTargets, syncScopes, overviewAnswer, remoteLine, waitingNames, releaseTag, panelUpdate, updateState, PANEL_UPDATE, toggleArgs } from "../skillshare/mods/skillshare/model.js"; +import { parseGitStatus, sourceLine, driftFrom, targetDrift, buildItems, hookArgs, counts, groupItems, filterItems, sourceGroups, cloneUrl, installResult, newerVersion, parseDiscover, parseAudit, parsePreview, diffSides, mergeMetadata, START, ALIVE, SWEEP, SNAPSHOT, parseSnapshot, rowState, previewTargets, splitFrontmatter, mcpServer, targetList, mapLanes, needsBothWays, READ_SKILL, eligibleTargets, syncScopes, overviewAnswer, remoteLine, waitingNames, releaseTag, panelUpdate, updateState, PANEL_UPDATE, toggleArgs, DISCOVER } from "../skillshare/mods/skillshare/model.js"; import { VERSION } from "../skillshare/mods/skillshare/version.js"; test("git status reads branch, ahead/behind and files", () => { @@ -280,8 +280,32 @@ test("a path inside a repo names a single skill", () => { assert.equal(cloneUrl("github.com/o/r/skills/x").single, true); }); -test("skill folders become pickable names", () => { - assert.deepEqual(skillChoices([".", "skills/a"]), [{ path: "skills/a", name: "a" }]); +test("discovery uses CLI install names and paths, including root skills", () => { + const choices = [{ name: "custom-tool", path: "skills" }, { name: "root", path: "." }]; + assert.deepEqual(parseDiscover(`@dir /tmp/x\n${JSON.stringify({ planned: choices })}`), { dir: "/tmp/x", choices, error: null }); +}); + +test("discovery requires CLI plans and rejects ambiguous install names", () => { + assert.match(parseDiscover('@dir /tmp/x\n{"skills":[]}').error, /upgrade/i); + assert.deepEqual(parseDiscover('@dir /tmp/x\n{"planned":[]}').choices, []); + const planned = [{ name: "design", path: "a/design" }, { name: "Design", path: "b/Design" }]; + assert.match(parseDiscover(`@dir /tmp/x\n${JSON.stringify({ planned })}`).error, /ambiguous/i); + assert.equal(parseDiscover('@dir /tmp/x\n{"error":"skills not found"}').error, "skills not found"); +}); + +test("install results never report a nonzero exit as success, including older CLIs", () => { + for (const body of [{ skills: [], failed: [] }, { skills: ["a"], failed: [] }, { skills: ["a"], failed: ["b"] }]) { + const result = installResult({ code: 1, stdout: JSON.stringify(body), stderr: "" }); + assert.ok(result.error); + assert.equal(result.done, null); + assert.match(result.error, /exited with 1/); + if (body.skills.length) assert.match(result.error, /a/); + } + assert.equal(installResult({ code: 1, stdout: '{"error":"blocked"}' }).error, "blocked"); + assert.deepEqual(installResult({ code: 0, stdout: '{"skills":[]}' }), { done: [], error: null }); + assert.deepEqual(installResult({ code: 0, stdout: '{"skills":["a"]}' }), { done: ["a"], error: null }); + assert.match(installResult({ code: 0, stdout: '{"skills":["a"],"failed":["b"]}' }).error, /b failed/); + assert.ok(installResult({ code: 0, stdout: 'not JSON' }).error); }); test("versions compare numerically", () => { @@ -307,8 +331,31 @@ test("a tree URL names the skill folder inside the repo", () => { assert.deepEqual([c.path, c.branch], ["skills/x", "dev"]); }); -test("discovery keeps the clone folder apart from the skill folders", () => { - assert.deepEqual(parseDiscover("@dir /tmp/x\nskills/a\n"), { dir: "/tmp/x", paths: ["skills/a"] }); +test("discovery script asks the scoped CLI for its plan, never scans the clone", (t) => { + const dir = mkdtempSync(join(tmpdir(), "ss-discover-")); + t.after(() => rmSync(dir, { recursive: true, force: true })); + writeFileSync(join(dir, "git"), '#!/bin/sh\nfor last; do :; done\nmkdir -p "$last"\nprintf "%s\\n" "$@" >"$HOME/git-args"\n', { mode: 0o755 }); + writeFileSync(join(dir, "skillshare"), '#!/bin/sh\nprintf "%s\\n" "$@" >"$HOME/cli-args"\npwd >"$HOME/cwd"\nprintf \'%s\\n\' \'{"planned":[{"name":"custom-tool","path":"packs/skills"}]}\'\nexit "${CLI_EXIT:-0}"\n', { mode: 0o755 }); + const env = { ...process.env, HOME: dir, TMPDIR: dir, PATH: `${dir}:${process.env.PATH}` }; + for (const scope of ["-g", "-p"]) { + const r = spawnSync("sh", ["-c", DISCOVER, "test", dir, "o/r/tree/dev/packs", "https://github.com/o/r.git", "dev", scope], { env, encoding: "utf8" }); + assert.equal(r.status, 0, r.stderr); + const result = parseDiscover(r.stdout); + assert.deepEqual(result.choices, [{ name: "custom-tool", path: "packs/skills" }]); + assert.ok(existsSync(join(result.dir, "r"))); + assert.equal(readFileSync(join(dir, "cwd"), "utf8").trim(), dir); + assert.deepEqual(readFileSync(join(dir, "cli-args"), "utf8").trim().split("\n"), ["install", "o/r/tree/dev/packs", "--dry-run", "--json", "--kind", "skill", scope]); + assert.ok(readFileSync(join(dir, "git-args"), "utf8").includes("-b\ndev\n")); + } + const failed = spawnSync("sh", ["-c", DISCOVER, "test", dir, "o/r", "url", "", "-g"], { env: { ...env, CLI_EXIT: "1" }, encoding: "utf8" }); + assert.equal(failed.status, 1); + assert.ok(parseDiscover(failed.stdout).dir); +}); + +test("discovery keeps the clone folder available when a preview fails", () => { + const result = parseDiscover('@dir /tmp/x\n{"error":"cannot read repository"}'); + assert.equal(result.dir, "/tmp/x"); + assert.equal(result.error, "cannot read repository"); }); test("a blocked audit lists its findings with paths inside the repo", () => { diff --git a/skills/skillshare/references/install.md b/skills/skillshare/references/install.md index 0c69e1589..be0f4aea7 100644 --- a/skills/skillshare/references/install.md +++ b/skills/skillshare/references/install.md @@ -17,6 +17,15 @@ Discovery skips target directories such as `.claude/` and `.agents/`, which usua hold copies of a repository's skills. A repository with no other skills has its root `.agents/skills/` discovered instead. +For an explicit, untracked skill source, `install --dry-run --json` +returns `planned: [{name, path}]`: canonical install names and repository-relative +Git paths (including a selected subdirectory), or `.` for a local skill. Use this +instead of scanning for `SKILL.md` or guessing names. Discovery, `.skillignore`, and +selection rules apply; without a filter JSON mode selects all. `skills` remains +empty during dry-run. An empty discovered selection returns `planned: []`; +tracked and config-based installs omit the field. Check the exit status as well +as `error`, including when consuming JSON from older CLIs. + ### Source Formats ```bash diff --git a/tests/integration/install_plan_test.go b/tests/integration/install_plan_test.go new file mode 100644 index 000000000..7acab5d93 --- /dev/null +++ b/tests/integration/install_plan_test.go @@ -0,0 +1,211 @@ +//go:build !online + +package integration + +import ( + "encoding/json" + "path/filepath" + "reflect" + "testing" + + "skillshare/internal/testutil" +) + +func TestInstall_JSON_PlannedFromMetadata(t *testing.T) { + for _, project := range []bool{false, true} { + mode := "global" + if project { + mode = "project" + } + t.Run(mode, func(t *testing.T) { + sb := testutil.NewSandbox(t) + defer sb.Cleanup() + sb.WriteConfig("source: " + sb.SourcePath + "\ntargets: {}\n") + cwd, dest, flag := sb.Root, sb.SourcePath, "-g" + if project { + cwd = sb.SetupProjectDir("claude") + dest, flag = filepath.Join(cwd, ".skillshare", "skills"), "-p" + } + repo := filepath.Join(sb.Root, "collection") + content := "---\nname: Canonical Tool\n---\n# Tool" + sb.WriteFile(filepath.Join(repo, "packs/skills/SKILL.md"), content) + initGitRepo(t, repo) + sb.RunCLIInDir(cwd, "install", "file://"+repo+"//packs/skills", "--name", "renamed-tool", "--json", flag).AssertSuccess(t) + result := sb.RunCLIInDir(cwd, "install", "renamed-tool", "--dry-run", "--json", flag) + result.AssertSuccess(t) + var out struct { + Planned []struct { + Name string `json:"name"` + Path string `json:"path"` + } `json:"planned"` + Skills []string `json:"skills"` + } + if err := json.Unmarshal([]byte(result.Stdout), &out); err != nil { + t.Fatal(err) + } + if len(out.Planned) != 1 || out.Planned[0].Name != "renamed-tool" || out.Planned[0].Path != "packs/skills" || len(out.Skills) != 0 { + t.Fatalf("metadata-resolved plan: %s", result.Stdout) + } + if got := sb.ReadFile(filepath.Join(dest, "renamed-tool/SKILL.md")); got != content { + t.Fatalf("preview changed the installed skill: %q", got) + } + }) + } +} + +func TestInstall_JSON_PlannedOmitted(t *testing.T) { + for _, project := range []bool{false, true} { + for _, tracked := range []bool{false, true} { + mode := "global" + if project { + mode = "project" + } + kind := "config" + if tracked { + kind = "tracked" + } + t.Run(mode+"/"+kind, func(t *testing.T) { + sb := testutil.NewSandbox(t) + defer sb.Cleanup() + sb.WriteConfig("source: " + sb.SourcePath + "\ntargets: {}\n") + cwd := sb.Root + args := []string{"install", "--json", "--dry-run"} + if project { + cwd = sb.SetupProjectDir("claude") + args = append(args, "-p") + } else { + args = append(args, "-g") + } + if tracked { + repo := createMultiSkillGitRepo(t, sb, "tracked", []string{"design"}) + args = append(args, "file://"+repo, "--track") + } + result := sb.RunCLIInDir(cwd, args...) + result.AssertSuccess(t) + var out map[string]any + if err := json.Unmarshal([]byte(result.Stdout), &out); err != nil { + t.Fatal(err) + } + if _, ok := out["planned"]; ok { + t.Fatalf("unexpected plan for %s install: %s", kind, result.Stdout) + } + }) + } + } +} + +func TestInstall_JSON_Planned(t *testing.T) { + type skill struct { + Name string `json:"name"` + Path string `json:"path"` + } + for _, project := range []bool{false, true} { + mode := "global" + if project { + mode = "project" + } + for _, layout := range []string{"collection", "fallback", "root", "local", "local-frontmatter", "local-renamed", "renamed", "empty"} { + t.Run(mode+"/"+layout, func(t *testing.T) { + sb := testutil.NewSandbox(t) + defer sb.Cleanup() + sb.WriteConfig("source: " + sb.SourcePath + "\ntargets: {}\n") + cwd, dest := sb.Root, sb.SourcePath + args := []string{"install", "--json", "--dry-run", "--kind", "skill"} + if project { + cwd = sb.SetupProjectDir("claude") + dest = filepath.Join(cwd, ".skillshare", "skills") + args = append(args, "-p") + } else { + args = append(args, "-g") + } + repo := filepath.Join(sb.Root, "collection") + source := "file://" + repo + want := []skill{} + sb.WriteFile(filepath.Join(repo, "README.md"), "# Collection") + sb.WriteFile(filepath.Join(repo, ".claude/skills/phantom/SKILL.md"), "# Target copy") + switch layout { + case "collection": + sb.WriteFile(filepath.Join(repo, "cli/assets/design/SKILL.md"), "# Design") + sb.WriteFile(filepath.Join(repo, ".claude/skills/design/SKILL.md"), "# Target copy") + sb.WriteFile(filepath.Join(repo, "agents/critic.md"), "---\nname: critic\ndescription: Review code\n---\n# Critic") + sb.WriteFile(filepath.Join(repo, "skills/SKILL.md"), "---\nname: Custom Tool\n---\n# Tool") + sb.WriteFile(filepath.Join(repo, "ignored/SKILL.md"), "# Ignored") + sb.WriteFile(filepath.Join(repo, ".agents/skills/copy/SKILL.md"), "# Copy") + sb.WriteFile(filepath.Join(repo, ".skillignore"), "ignored/\n") + want = []skill{{"design", "cli/assets/design"}, {"custom-tool", "skills"}} + case "fallback": + sb.WriteFile(filepath.Join(repo, ".agents/skills/only/SKILL.md"), "# Authored") + want = []skill{{"only", ".agents/skills/only"}} + case "local-frontmatter": + sb.WriteFile(filepath.Join(repo, "skills/SKILL.md"), "---\nname: Custom Tool\n---\n# Tool") + source = filepath.Join(repo, "skills") + want = []skill{{"custom-tool", "."}} + case "root", "local", "local-renamed", "renamed": + sb.WriteFile(filepath.Join(repo, "SKILL.md"), "# Root") + want = []skill{{"collection", "."}} + if layout == "local" || layout == "local-renamed" { + source = repo + } + if layout == "renamed" || layout == "local-renamed" { + args = append(args, "--name", "custom-root") + want[0].Name = "custom-root" + } + } + initGitRepo(t, repo) + result := sb.RunCLIInDir(cwd, append(args, source)...) + result.AssertSuccess(t) + var out struct { + Planned *[]skill `json:"planned"` + Skills []string `json:"skills"` + Failed []string `json:"failed"` + } + if err := json.Unmarshal([]byte(result.Stdout), &out); err != nil { + t.Fatalf("invalid JSON: %v\n%s", err, result.Stdout) + } + if out.Planned == nil || !reflect.DeepEqual(*out.Planned, want) { + t.Fatalf("planned = %v, want %v; output: %s", out.Planned, want, result.Stdout) + } + if len(out.Skills) != 0 || len(out.Failed) != 0 { + t.Fatalf("dry-run reported installed/failed skills: %s", result.Stdout) + } + for _, s := range want { + if sb.FileExists(filepath.Join(dest, s.Name, "SKILL.md")) { + t.Fatalf("dry-run installed %s", s.Name) + } + } + if layout == "collection" { + // Preview selection uses the same canonical names as the install. + selected := sb.RunCLIInDir(cwd, append(args, source, "--skill", "custom-tool")...) + selected.AssertSuccess(t) + if err := json.Unmarshal([]byte(selected.Stdout), &out); err != nil { + t.Fatal(err) + } + if out.Planned == nil || !reflect.DeepEqual(*out.Planned, want[1:]) { + t.Fatalf("selected plan: %s", selected.Stdout) + } + // Existing destinations must not prevent listing candidates. + sb.WriteFile(filepath.Join(dest, "custom-tool/SKILL.md"), "# Existing") + sb.RunCLIInDir(cwd, append(args, source)...).AssertSuccess(t) + installArgs := []string{"install", source, "--json", "--kind", "skill", "--skill", "design"} + if project { + installArgs = append(installArgs, "-p") + } else { + installArgs = append(installArgs, "-g") + } + installed := sb.RunCLIInDir(cwd, installArgs...) + installed.AssertSuccess(t) + if got := sb.ReadFile(filepath.Join(dest, "design/SKILL.md")); got != "# Design" { + t.Fatalf("installed a different path: %q", got) + } + var actual map[string]any + if err := json.Unmarshal([]byte(installed.Stdout), &actual); err != nil { + t.Fatal(err) + } + if _, ok := actual["planned"]; ok || !reflect.DeepEqual(actual["skills"], []any{"design"}) { + t.Fatalf("unexpected actual install result: %s", installed.Stdout) + } + } + }) + } + } +} diff --git a/website/docs/reference/commands/install.md b/website/docs/reference/commands/install.md index f92879f04..504ea74aa 100644 --- a/website/docs/reference/commands/install.md +++ b/website/docs/reference/commands/install.md @@ -313,6 +313,8 @@ See [Project Setup](/docs/how-to/sharing/project-setup) for the full guide. skillshare install anthropics/skills --json ``` +For an explicit, untracked skill source, add `--dry-run --json` to read a `planned` array of `{name, path}` objects without installing. Names are the CLI's install names; Git paths are relative to the repository root (including any selected subdirectory), and a local skill uses `.`. The plan follows discovery, `.skillignore`, and selection rules. Without a selection filter, JSON mode selects all skills. `skills` still reports only installed names and stays empty in a dry run. A discovered source with no selected skills returns `planned: []`; tracked and config-based installs do not provide this field. + ```json { "source": "anthropics/skills", diff --git a/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/install.md b/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/install.md index 3005a6e60..42ac8663c 100644 --- a/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/install.md +++ b/website/i18n/ja/docusaurus-plugin-content-docs/current/reference/commands/install.md @@ -307,6 +307,8 @@ skillshare sync skillshare install anthropics/skills --json ``` +明示的に指定した非追跡の skill ソースでは、`--dry-run --json` を追加すると、インストールせずに `{name, path}` の `planned` 配列を取得できます。名前は CLI のインストール名です。Git のパスはリポジトリのルートからの相対パス(選択したサブディレクトリを含む)で、ローカル skill は `.` を使用します。検出、`.skillignore`、選択のルールが適用され、JSON モードではフィルターがなければ全選択になります。`skills` は引き続きインストール済みの名前のみを報告し、dry-run では空です。検出後に選択された skill がなければ `planned: []` を返します。追跡および設定ファイルからのインストールでは、このフィールドは提供されません。 + ```json { "source": "anthropics/skills", diff --git a/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/install.md b/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/install.md index 84d67f9d6..49bf459de 100644 --- a/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/install.md +++ b/website/i18n/ko/docusaurus-plugin-content-docs/current/reference/commands/install.md @@ -307,6 +307,8 @@ skillshare sync skillshare install anthropics/skills --json ``` +명시적으로 지정한 비추적 skill 소스에 `--dry-run --json`을 추가하면 설치하지 않고 `{name, path}` 객체의 `planned` 배열을 받을 수 있습니다. 이름은 CLI의 설치 이름이며, Git 경로는 선택한 하위 디렉터리를 포함한 저장소 루트 기준 상대 경로입니다. 로컬 skill은 `.`을 사용합니다. 검색, `.skillignore`, 선택 규칙이 적용되며 JSON 모드에서 필터가 없으면 모두 선택됩니다. `skills`는 계속 설치된 이름만 보고하므로 dry-run에서는 비어 있습니다. 검색 후 선택한 skill이 없으면 `planned: []`를 반환합니다. 추적 및 설정 파일 기반 설치는 이 필드를 제공하지 않습니다. + ```json { "source": "anthropics/skills", diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/install.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/install.md index 994f068e6..16218911b 100644 --- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/install.md +++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/reference/commands/install.md @@ -307,6 +307,8 @@ skillshare sync skillshare install anthropics/skills --json ``` +对明确指定、非跟踪的 skill 来源,加上 `--dry-run --json` 可取得 `planned` 数组,包含 `{name, path}`,不会安装。名称是 CLI 的安装名称;Git 路径相对于仓库根目录(包含选取的子目录),本地 skill 使用 `.`。列表遵循发现、`.skillignore` 和选择规则;JSON 模式未指定筛选条件时会全选。`skills` 仍只报告已安装名称,在 dry-run 中保持空数组。发现后没有选中的 skill 时返回 `planned: []`;跟踪与配置文件安装不提供此字段。 + ```json { "source": "anthropics/skills", diff --git a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/install.md b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/install.md index 5a50ff7a9..52ccf1fed 100644 --- a/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/install.md +++ b/website/i18n/zh-Hant/docusaurus-plugin-content-docs/current/reference/commands/install.md @@ -307,6 +307,8 @@ skillshare sync skillshare install anthropics/skills --json ``` +對明確指定、非追蹤的 skill 來源,加上 `--dry-run --json` 可取得 `planned` 陣列,內含 `{name, path}`,不會安裝。名稱是 CLI 的安裝名稱;Git 路徑相對於儲存庫根目錄(包含選取的子目錄),本機 skill 則使用 `.`。清單遵循探索、`.skillignore` 與選取規則;JSON 模式未指定篩選條件時會全選。`skills` 仍只回報已安裝名稱,在 dry-run 中保持空陣列。探索後沒有選取的 skill 時回傳 `planned: []`;追蹤與設定檔安裝不提供此欄位。 + ```json { "source": "anthropics/skills",