@opengsd/gsd-path 1.4.0 → 1.5.0

package/scripts/install.mjs

@@ -212,9 +212,10 @@ export const EXPLICIT_ONLY_TARGETS = new Set([
   "cursor",
   "zed",
   "kimi",
+  "muse",
   "shared-agents",
 ]);
-const SHARED_AGENT_TARGETS = new Set(["codex", "antigravity", "zed"]);
+const SHARED_AGENT_TARGETS = new Set(["codex", "antigravity", "zed", "muse"]);
 export const SHARED_AGENT_PROFILE = "shared-agents";
 export const CURSOR_AGENT_FILENAME = "gsd-path.md";
 export const CURSOR_AGENT_BACKUP_NAME = "cursor-agent-gsd-path.md";
@@ -228,7 +229,7 @@ const MANIFEST = JSON.parse(
 );
 
 function sharedInvocations(text) {
-  const pattern = /(`?)(\$gsd-path(?:-[a-z0-9]+)*|\$path)( status)?\1(?: \(Codex\) (?:and|or) (`?)\/(gsd-path(?:-[a-z0-9]+)*|path)( status)?\4 \((?:other hosts|Antigravity\/Zed)\))?/g;
+  const pattern = /(`?)(\$gsd-path(?:-[a-z0-9]+)*|\$path)( status)?\1(?: \(Codex\) (?:and|or) (`?)\/(gsd-path(?:-[a-z0-9]+)*|path)( status)?\4 \((?:other hosts|Antigravity\/Zed\/Muse)\))?/g;
   return text.replace(pattern, (_match, quote, token, arguments_, pairedQuote, pairedSkill, pairedArguments) => {
     const skill = token.slice(1);
     const argumentsText = arguments_ || "";
@@ -237,7 +238,7 @@ function sharedInvocations(text) {
     }
     const codex = `${MANIFEST.hosts.codex.invocation_prefix}${skill}`;
     const others = `${MANIFEST.hosts.antigravity.invocation_prefix}${skill}`;
-    return `${quote}${codex}${argumentsText}${quote} (Codex) or ${quote}${others}${argumentsText}${quote} (Antigravity/Zed)`;
+    return `${quote}${codex}${argumentsText}${quote} (Codex) or ${quote}${others}${argumentsText}${quote} (Antigravity/Zed/Muse)`;
   });
 }
 export function skillNamesForManifest(manifest) {
@@ -355,7 +356,7 @@ export function defaultRoot(target, env = process.env) {
   }
   if (target === "antigravity") return absolutePath("~/.gemini/antigravity-cli/skills");
   if (target === "cursor") return absolutePath("~/.cursor/skills");
-  if (target === "zed") return absolutePath("~/.agents/skills");
+  if (target === "zed" || target === "muse") return absolutePath("~/.agents/skills");
   if (target === "kiro") {
     return absolutePath(path.join(env.KIRO_HOME || expandUser("~/.kiro"), "skills"));
   }
@@ -386,7 +387,9 @@ function isOwnedRouterAlias(skillDir) {
   const versionFile = path.join(skillDir, "VERSION");
   if (!isFile(versionFile)) return isManagedProjectRuntime(runtime); // installs before alias version stamping
   try {
-    return /^[0-9]+(?:\.[0-9]+)+$/.test(fs.readFileSync(versionFile, "utf8").trim());
+    return /^[0-9]+(?:\.[0-9]+)+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.test(
+      fs.readFileSync(versionFile, "utf8").trim()
+    );
   } catch {
     return false;
   }
@@ -1037,7 +1040,7 @@ async function applyTarget(plan, stagedRoot, transaction) {
     const destination = path.join(plan.root, name);
     hooks.reserveDirectory(destination);
     transaction.installed.push(destination);
-    fs.cpSync(path.join(stagedRoot, name), destination, { recursive: true, errorOnExist: true, force: false });
+    copyIntoReservedDirectory(path.join(stagedRoot, name), destination);
     await tick();
   }
   if (cursorAgent !== null) {
@@ -1051,6 +1054,18 @@ function reserveDirectory(destination) {
   fs.mkdirSync(destination);
 }
 
+// Node 26 rejects recursive cpSync when the destination directory already exists
+// and errorOnExist is set. Reserve the skill directory, then copy each staged entry.
+export function copyIntoReservedDirectory(source, destination) {
+  for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+    fs.cpSync(path.join(source, entry.name), path.join(destination, entry.name), {
+      recursive: true,
+      errorOnExist: true,
+      force: false,
+    });
+  }
+}
+
 function reserveFile(destination) {
   const descriptor = fs.openSync(destination, "wx", 0o644);
   try {
@@ -1192,7 +1207,7 @@ export function deploymentPlans(plans) {
     if (group.length > 1) {
       if (!targets.every((name) => SHARED_AGENT_TARGETS.has(name))) {
         throw new InstallerError(
-          `only Codex, Antigravity, and Zed may share a skills root: ${targets.join(", ")}`
+          `only Codex, Antigravity, Zed, and Muse may share a skills root: ${targets.join(", ")}`
         );
       }
       profile = SHARED_AGENT_PROFILE;
@@ -1546,7 +1561,7 @@ export async function install(sourceRoot, plans, options = {}) {
 }
 
 // Documented project-relative skill roots (verified against each host's
-// official skills docs). Codex, Zed, and Antigravity all discover the
+// official skills docs). Codex, Zed, Muse, and Antigravity all discover the
 // project-level .agents/skills standard directory.
 export function localRoot(target, projectDir) {
   const relative = LOCAL_ROOTS[target];

package/scripts/install.py

@@ -124,7 +124,7 @@ STATUS_STATE_FIELDS = frozenset(
         "integration_source",
     }
 )
-STATUS_INTEGRATION_MODES = frozenset({"direct", "pull-request"})
+STATUS_INTEGRATION_MODES = frozenset({"direct", "pull-request", "external-landing"})
 STATUS_INTEGRATION_SOURCES = frozenset({"default", "milestone"})
 STATUS_SLUG = re.compile(r"^[a-z0-9][a-z0-9-]*$")
 STATUS_BRANCH = re.compile(r"^gsd-path/M(\d{3,})$")
@@ -505,9 +505,9 @@ HOST_NOTES = {
     "kiro": KIRO_NOTE,
 }
 EXPLICIT_ONLY_TARGETS = frozenset(
-    {"claude", "grok", "copilot", "qwen", "cursor", "zed", "kimi", "shared-agents"}
+    {"claude", "grok", "copilot", "qwen", "cursor", "zed", "kimi", "muse", "shared-agents"}
 )
-SHARED_AGENT_TARGETS = frozenset({"codex", "antigravity", "zed"})
+SHARED_AGENT_TARGETS = frozenset({"codex", "antigravity", "zed", "muse"})
 SHARED_AGENT_PROFILE = "shared-agents"
 CURSOR_AGENT_FILENAME = "gsd-path.md"
 CURSOR_AGENT_BACKUP_NAME = "cursor-agent-gsd-path.md"
@@ -533,7 +533,7 @@ def _shared_invocations(text: str) -> str:
         others = f"{hosts['antigravity']['invocation_prefix']}{skill}"
         return (
             f"{quote}{codex}{arguments}{quote} (Codex) or "
-            f"{quote}{others}{arguments}{quote} (Antigravity/Zed)"
+            f"{quote}{others}{arguments}{quote} (Antigravity/Zed/Muse)"
         )
 
     return re.sub(
@@ -542,7 +542,7 @@ def _shared_invocations(text: str) -> str:
         r"(?: \(Codex\) (?:and|or) (?P<paired_quote>`?)/"
         r"(?P<paired_skill>gsd-path(?:-[a-z0-9]+)*|path)"
         r"(?P<paired_arguments> status)?(?P=paired_quote)"
-        r" \((?:other hosts|Antigravity/Zed)\))?",
+        r" \((?:other hosts|Antigravity/Zed/Muse)\))?",
         replace,
         text,
     )
@@ -620,7 +620,7 @@ def default_root(target: str, environ: Optional[Mapping[str, str]] = None) -> Pa
         return absolute_path(Path("~/.gemini/antigravity-cli/skills"))
     if target == "cursor":
         return absolute_path(Path("~/.cursor/skills"))
-    if target == "zed":
+    if target in ("zed", "muse"):
         return absolute_path(Path("~/.agents/skills"))
     if target == "kiro":
         return absolute_path(Path(env.get("KIRO_HOME") or "~/.kiro") / "skills")
@@ -656,7 +656,15 @@ def _is_owned_router_alias(skill_dir: Path) -> bool:
         version = version_file.read_text(encoding="utf-8").strip()
     except (OSError, UnicodeError):
         return False
-    return re.fullmatch(r"[0-9]+(?:\.[0-9]+)+", version) is not None
+    return (
+        re.fullmatch(
+            r"[0-9]+(?:\.[0-9]+)+"
+            r"(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?"
+            r"(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?",
+            version,
+        )
+        is not None
+    )
 
 
 def _is_managed_install_entry(root: Path, name: str) -> bool:
@@ -2259,7 +2267,7 @@ def _deployment_plans(plans: Sequence[TargetPlan]) -> List[DeploymentPlan]:
             if not target_set <= SHARED_AGENT_TARGETS:
                 labels = ", ".join(targets)
                 raise InstallerError(
-                    "only Codex, Antigravity, and Zed may share a skills root: "
+                    "only Codex, Antigravity, Zed, and Muse may share a skills root: "
                     f"{labels}"
                 )
             profile = SHARED_AGENT_PROFILE
@@ -3275,6 +3283,31 @@ def install(
     return results
 
 
+def _runtime_provenance(arguments, source_root: Path):
+    """Owner-recorded provenance from --runtime-provenance-* upgrade flags.
+
+    When the supplied source root is a git checkout and no patch reference
+    was given, its HEAD sha is recorded with one best-effort rev-parse.
+    Provenance is display/audit metadata on the runtime declaration only; it
+    never joins the pinned digest or runtime validation.
+    """
+    supplied = (arguments.runtime_provenance_source, arguments.runtime_provenance_patch,
+                arguments.runtime_provenance_note)
+    recorded = {key: value for key, value in zip(runtime_store.PROVENANCE_KEYS, supplied) if value}
+    if not recorded:
+        return None
+    if "patch_ref" not in recorded:
+        try:
+            head = subprocess.run(["git", "rev-parse", "--show-toplevel", "HEAD"], cwd=source_root,
+                                  capture_output=True, encoding="utf-8", check=True)
+            toplevel, _, sha = head.stdout.strip().partition("\n")
+            if sha and Path(toplevel).resolve() == Path(source_root).resolve():
+                recorded["patch_ref"] = sha
+        except (OSError, subprocess.CalledProcessError):
+            pass
+    return recorded
+
+
 def parser() -> argparse.ArgumentParser:
     argument_parser = argparse.ArgumentParser(description=__doc__)
     for target in TARGETS:
@@ -3291,6 +3324,9 @@ def parser() -> argparse.ArgumentParser:
     runtime_actions = argument_parser.add_mutually_exclusive_group()
     for action in ("restore", "upgrade", "migrate"):
         runtime_actions.add_argument(f"--runtime-{action}", action="store_true")
+    argument_parser.add_argument("--runtime-provenance-source")
+    argument_parser.add_argument("--runtime-provenance-patch")
+    argument_parser.add_argument("--runtime-provenance-note")
     argument_parser.add_argument("--hooks", action="store_true")
     argument_parser.add_argument("--hooks-init", action="store_true")
     argument_parser.add_argument("--hooks-refresh", action="store_true")
@@ -3336,6 +3372,9 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
     )
     runtime_action = next((action for action in ("restore", "upgrade", "migrate")
                            if getattr(arguments, "runtime_" + action)), None)
+    provenance = _runtime_provenance(arguments, source_root)
+    if provenance is not None and runtime_action != "upgrade":
+        argument_parser.error("--runtime-provenance-* requires --runtime-upgrade")
     if runtime_action:
         if project is None:
             argument_parser.error(f"--runtime-{runtime_action} requires --project")
@@ -3343,7 +3382,8 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
             _validate_project_git_root(project)
             locks, created = ([], []) if arguments.dry_run else _acquire_install_locks([project / HOOKS_DIRECTORY])
             try:
-                pin = runtime_store.operate(source_root, project, runtime_action, dry_run=arguments.dry_run)
+                pin = runtime_store.operate(source_root, project, runtime_action,
+                                            dry_run=arguments.dry_run, provenance=provenance)
             finally:
                 _release_install_locks(locks, created)
             print(f"runtime: {runtime_action} {pin['version']} ({pin['digest']})"

package/scripts/integration.py

@@ -9,6 +9,7 @@ sys.dont_write_bytecode = True
 
 import json
 import re
+import contextlib
 from pathlib import Path, PurePosixPath
 from typing import Optional
 
@@ -797,6 +798,36 @@ def pull_request_tag_metadata(project: Path, tag_ref: str) -> dict[str, str]:
     return fields
 
 
+def external_landing_tag_message(
+    archive_name: str, ship_commit: str, landing: str
+) -> str:
+    return (
+        f"milestone {archive_name}\n\n"
+        "Mode: external-landing\n"
+        f"Ship: {ship_commit}\n"
+        f"Landing: {landing}"
+    )
+
+
+def external_landing_tag_metadata(project: Path, tag_ref: str) -> dict[str, str]:
+    message = archive_milestone.require_git_success(
+        run_git(project, "for-each-ref", "--format=%(contents)", tag_ref),
+        "inspect external-landing milestone tag",
+    )
+    fields: dict[str, str] = {}
+    for line in message.splitlines():
+        match = re.fullmatch(r"(Mode|Ship|Landing): (.+)", line)
+        if match:
+            if match.group(1) in fields:
+                raise ArchiveError("external-landing milestone tag repeats metadata")
+            fields[match.group(1)] = match.group(2)
+    if set(fields) != {"Mode", "Ship", "Landing"}:
+        raise ArchiveError("external-landing milestone tag is missing metadata")
+    if fields["Mode"] != "external-landing":
+        raise ArchiveError("external-landing milestone tag has the wrong mode")
+    return fields
+
+
 def require_pull_request_merge(
     project: Path,
     merge_commit: str,
@@ -1021,6 +1052,78 @@ def integrate_pull_request(
     return validate_integrated(project, archive_milestone.milestone_slug(state))
 
 
+def integrate_external_landing(
+    project: Path,
+    state: PipelineState,
+    archive_path: str,
+    archive_name: str,
+    ship_commit: str,
+    remote_default: str,
+    default_name: str,
+    bound_branch: str,
+) -> dict:
+    if state.branch is None:
+        raise ArchiveError("external-landing integration requires a bound branch")
+    publishable_bound_branch(project, bound_branch, ship_commit)
+    contains_ship = run_git(
+        project, "merge-base", "--is-ancestor", ship_commit, remote_default
+    )
+    if contains_ship.returncode == 1:
+        publish_bound_branch(project, bound_branch, ship_commit)
+        return {
+            "status": "awaiting-merge",
+            "mode": "external-landing",
+            "archive": archive_path,
+            "commit": ship_commit,
+        }
+    if contains_ship.returncode != 0:
+        archive_milestone.require_git_success(
+            contains_ship, "inspect ship ancestry on the remote default"
+        )
+        raise AssertionError("unreachable")
+
+    merge_commit = find_integrate_commit(
+        project, remote_default, archive_name, ship_commit
+    )
+    require_generated_integration_commit(
+        project,
+        merge_commit,
+        archive_path,
+        archive_name,
+        ship_commit,
+        default_name,
+        bound_branch,
+    )
+    tag_name = f"milestone/{archive_name}"
+    message = external_landing_tag_message(archive_name, ship_commit, merge_commit)
+    tag_object, tag_published = ensure_integration_tag(
+        project,
+        tag_name,
+        merge_commit,
+        message,
+    )
+    if not tag_published:
+        archive_milestone.require_git_success(
+            run_git(
+                project,
+                "push",
+                "origin",
+                f"refs/tags/{tag_name}:refs/tags/{tag_name}",
+            ),
+            "push milestone tag",
+        )
+        archive_milestone.require_git_success(
+            run_git(
+                project,
+                "update-ref",
+                f"refs/remotes/origin/tags/{tag_name}",
+                tag_object,
+            ),
+            "refresh local milestone-tag ref",
+        )
+    return validate_integrated(project, archive_milestone.milestone_slug(state))
+
+
 def integrate(repo: Path, slug: str) -> dict:
     project = repo.resolve()
     active_root = archive_milestone.require_project_layout(project)
@@ -1070,6 +1173,17 @@ def integrate(repo: Path, slug: str) -> dict:
             archive_name,
             ship_commit,
         )
+    if state.integration == "external-landing":
+        return integrate_external_landing(
+            project,
+            state,
+            archive_path,
+            archive_name,
+            ship_commit,
+            remote_default,
+            default_name,
+            bound_branch,
+        )
     publishable_bound_branch(project, bound_branch, ship_commit)
     integration_branch, worktree = integration_names(project, archive_name, pin=True)
     interrupted_worktree = registered_worktree(project, integration_branch)
@@ -1345,6 +1459,32 @@ def validate_integrated(
                 merge_commit,
             ),
         )
+    elif state.integration == "external-landing":
+        merge_commit = find_integrate_commit(
+            project, remote_default, archive_name, ship_commit
+        )
+        archive_milestone.require_canonical_commit_body(
+            project,
+            merge_commit,
+            integrate_subject(archive_name, default_name),
+            integrate_commit_body(configured, ship_commit, default_name, bound_branch),
+            "integration",
+        )
+        require_pull_request_merge(project, merge_commit, ship_commit, remote_default)
+        if run_git(project, "rev-parse", "--verify", "--quiet", tag_ref).returncode != 0:
+            raise ArchiveError(f"missing milestone tag: {tag_name}")
+        metadata = external_landing_tag_metadata(project, tag_ref)
+        if metadata["Ship"] != ship_commit:
+            raise ArchiveError("external-landing milestone tag names the wrong ship commit")
+        if metadata["Landing"] != merge_commit:
+            raise ArchiveError("external-landing milestone tag names the wrong landing")
+        require_annotated_tag(
+            project,
+            tag_ref,
+            merge_commit,
+            f"milestone tag {tag_name}",
+            external_landing_tag_message(archive_name, ship_commit, merge_commit),
+        )
     else:
         merge_commit = find_integrate_commit(
             project, remote_default, archive_name, ship_commit
@@ -1381,7 +1521,8 @@ def validate_integrated(
         ship_commit,
         tag_name,
         merge_commit,
-        allow_missing_bound=state.integration == "pull-request" or (historical and has_origin),
+        allow_missing_bound=state.integration in ("pull-request", "external-landing")
+        or (historical and has_origin),
         retired=historical,
     )
 
@@ -1799,6 +1940,10 @@ def retire_member(coordinator: Path, member: str, archive_path: str, reviewed_he
     for kind, ref in (("push", bound_ref), ("push", "refs/heads/main"), ("push", f"refs/tags/{tag_name}"),
                       ("delete", bound_ref)):
         members.clear_authorization(checkout, project, kind, ref)
+    # The last sidecar retires here at milestone end; isolation's retires also
+    # release the pin whenever the workspace is idle, so a new root can apply.
+    with contextlib.suppress(ValueError, OSError):
+        worktree_paths.release_workspace(checkout)
     return {"member": member, "retired": bound}