@ainova-systems/intelligence 0.11.0-rc.1

package/cli/lib/cli-common.sh

@@ -0,0 +1,149 @@
+#!/bin/bash
+# Shared plumbing for every CLI command. Commands are separate processes (the
+# dispatcher execs them), so each one sources this file first.
+#
+# All YAML reading goes through the engine's lib/common.sh — the CLI never
+# grows a parallel parser for shapes the engine can already read. The only
+# CLI-owned parsing lives in lib/manifest.sh (quoted-key `packages:` /
+# `registries:` blocks, which the engine deliberately never reads).
+
+# Engine libraries (readers, is_status, IS_RC_*, engine_version). Sourced in
+# the same order sync.sh uses. CLI_DIR / IS_ENGINE_DIR come exported from the
+# dispatcher.
+source "$IS_ENGINE_DIR/scripts/lib/common.sh"
+source "$IS_ENGINE_DIR/scripts/lib/layout.sh"
+source "$IS_ENGINE_DIR/scripts/lib/migrations.sh"
+
+die() {
+    echo "ERROR: $*" >&2
+    exit 1
+}
+
+source "$CLI_DIR/lib/manifest.sh"
+source "$CLI_DIR/lib/semver.sh"
+source "$CLI_DIR/lib/registry.sh"
+source "$CLI_DIR/lib/lockfile.sh"
+
+# Meta-skills that the CLI replaces with first-class commands — staging skips
+# them so a v2 project never carries a skill telling the agent to run a flow
+# the CLI already owns.
+CLI_OBSOLETE_SKILLS="intelligence-update intelligence-sync"
+
+# --- Project detection ---------------------------------------------------
+# Sets: IP_MODE (v2|legacy|none), IP_ROOT, IP_UMBRELLA, IP_MODULE_DIR.
+# These ARE this lib's public API — every command reads them after calling
+# detect_project, which per-file shellcheck cannot see.
+# shellcheck disable=SC2034
+# v2 wins: the nearest ancestor holding intelligence.yaml. Legacy is a git
+# repo holding an umbrella (a dir with config.yaml) whose module is identified
+# by role — scripts/sync.sh + scripts/VERSION — never by name.
+detect_project() {
+    IP_MODE="none"; IP_ROOT=""; IP_UMBRELLA=""; IP_MODULE_DIR=""
+    local dir="$PWD"
+    while :; do
+        if [ -f "$dir/intelligence.yaml" ]; then
+            IP_MODE="v2"
+            IP_ROOT="$(cd "$dir" && pwd)"
+            return 0
+        fi
+        [ "$dir" = "$(dirname "$dir")" ] && break
+        dir="$(dirname "$dir")"
+    done
+    local root
+    root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+    [ -n "$root" ] || return 0
+    root="$(cd "$root" && pwd)"
+    local cf umbrella mod
+    while IFS= read -r cf; do
+        [ -n "$cf" ] || continue
+        umbrella="$(cd "$(dirname "$cf")" && pwd)"
+        for mod in "$umbrella"/*/; do
+            [ -d "$mod" ] || continue
+            if [ -f "${mod}scripts/sync.sh" ] && [ -f "${mod}scripts/VERSION" ]; then
+                IP_MODE="legacy"; IP_ROOT="$root"; IP_UMBRELLA="$umbrella"
+                IP_MODULE_DIR="${mod%/}"
+                return 0
+            fi
+        done
+    done < <(find "$root" -maxdepth 2 -name 'config.yaml' -not -path '*/.*' 2>/dev/null)
+    return 0
+}
+
+require_v2() {
+    detect_project
+    case "$IP_MODE" in
+        v2) ;;
+        legacy) die "this is a vendored (v1) setup — run 'intelligence migrate' first, or keep using its own flow" ;;
+        *) die "no intelligence project found here — run 'intelligence init'" ;;
+    esac
+}
+
+# --- Manifest basics (engine-readable shapes) ----------------------------
+
+manifest_intelligence_dir() {
+    local manifest="$1" v
+    v="$(get_yaml_field "$manifest" "project" "intelligence_dir")"
+    printf '%s' "${v:-intelligence}"
+}
+
+bundled_engine_version() {
+    tr -d ' \t\r\n' < "$IS_ENGINE_DIR/scripts/VERSION"
+}
+
+# --- Engine content staging ----------------------------------------------
+# The v2 project vendors no engine code; the engine's own rules / agents /
+# meta-skills / docs are staged into the package store so sources can reach
+# them as ordinary repo-relative dirs. Re-staged whenever the bundled engine
+# version differs from the `.version` stamp.
+# stage_engine_content <dest-dir> — unconditional copy of the engine's own
+# content into <dest-dir> plus the `.version` stamp.
+stage_engine_content() {
+    local store="$1"
+    rm -rf "$store"
+    mkdir -p "$store"
+    local d s name skip
+    for d in rules agents docs; do
+        [ -d "$IS_ENGINE_DIR/$d" ] && cp -R "$IS_ENGINE_DIR/$d" "$store/$d"
+    done
+    if [ -d "$IS_ENGINE_DIR/skills" ]; then
+        mkdir -p "$store/skills"
+        for s in "$IS_ENGINE_DIR"/skills/*/; do
+            [ -d "$s" ] || continue
+            name="$(basename "$s")"
+            skip=0
+            for d in $CLI_OBSOLETE_SKILLS; do
+                [ "$name" = "$d" ] && skip=1
+            done
+            [ "$skip" = "1" ] && continue
+            cp -R "$s" "$store/skills/$name"
+        done
+    fi
+    bundled_engine_version > "$store/.version"
+}
+
+ensure_engine_staged() {
+    local root="$1"
+    local store="$root/.intelligence/engine"
+    local bundled_ver staged_ver
+    bundled_ver="$(bundled_engine_version)"
+    staged_ver=""
+    [ -f "$store/.version" ] && staged_ver="$(tr -d ' \t\r\n' < "$store/.version")"
+    [ "$staged_ver" = "$bundled_ver" ] && return 0
+    stage_engine_content "$store"
+    echo "  engine content staged: .intelligence/engine ($bundled_ver)"
+}
+
+# --- The engine env contract ---------------------------------------------
+# Everything the IS_CLI mode of sync.sh needs, derived from the manifest.
+export_engine_env() {
+    local root="$1"
+    local umbrella
+    umbrella="$(manifest_intelligence_dir "$root/intelligence.yaml")"
+    export IS_CLI=1
+    export CONFIG_FILE="$root/intelligence.yaml"
+    export REPO_ROOT="$root"
+    export IS_UMBRELLA_REL="$umbrella"
+    export IS_MODULE_REL=".intelligence/engine"
+    export IS_SYNC_CMD="intelligence sync"
+    export IS_PROTECTED_DIRS="$umbrella:.intelligence"
+}

package/cli/lib/lockfile.sh

@@ -0,0 +1,97 @@
+#!/bin/bash
+# intelligence.lock — the resolved state, committed with the project.
+#
+# The lock is fully generated (npm's model): readers use the qmap parser from
+# manifest.sh, writers rebuild the whole file from a row stream of entries.
+# Columns: name, requested, url, path, resolved, sha — separated by the ASCII
+# unit separator, NOT a tab: tab is IFS whitespace, so `read` would collapse
+# an empty field (a rootless `path`) and shift every column after it.
+
+LOCKFILE_VERSION=1
+LOCK_SEP=$'\x1f'
+
+# top_scalar <file> <key> — one top-level scalar (`key: "value"`), quotes and
+# trailing comment stripped. The declared exception to "no new parsing": the
+# engine's read_engine_stamp is hardwired to its own key.
+top_scalar() {
+    [ -f "$1" ] || return 0
+    awk -v key="$2" '
+        { sub(/\r$/, "") }
+        $0 ~ "^" key ":" {
+            v = substr($0, length(key) + 2)
+            sub(/^[ \t]+/, "", v)
+            if (v ~ /^"/) { v = substr(v, 2); q = index(v, "\""); if (q > 0) v = substr(v, 1, q - 1) }
+            else { sub(/[ \t]+#.*$/, "", v); sub(/[ \t]+$/, "", v) }
+            print v
+            exit
+        }
+    ' "$1"
+}
+
+# lock_to_tsv <lock> — every locked package as one row.
+lock_to_tsv() {
+    local lock="$1" name
+    [ -f "$lock" ] || return 0
+    while IFS= read -r name; do
+        [ -n "$name" ] || continue
+        printf '%s\037%s\037%s\037%s\037%s\037%s\n' \
+            "$name" \
+            "$(qmap_field "$lock" "packages" "$name" "requested")" \
+            "$(qmap_field "$lock" "packages" "$name" "url")" \
+            "$(qmap_field "$lock" "packages" "$name" "path")" \
+            "$(qmap_field "$lock" "packages" "$name" "resolved")" \
+            "$(qmap_field "$lock" "packages" "$name" "sha")"
+    done < <(qmap_keys "$lock" "packages")
+}
+
+# lock_write_from_tsv <lock> <tsv-file> — rebuild the lock. Entries are
+# written in the TSV's order; callers keep it stable (manifest order).
+lock_write_from_tsv() {
+    local lock="$1" tsv="$2"
+    local tmp="$lock.cli.tmp"
+    {
+        echo "# Generated by the intelligence CLI. Do not edit."
+        echo "lockfile_version: $LOCKFILE_VERSION"
+        echo "engine_version: \"$(bundled_engine_version)\""
+        echo "packages:"
+        awk -F"$LOCK_SEP" '
+            NF >= 6 {
+                print "  \"" $1 "\":"
+                if ($2 != "") print "    requested: \"" $2 "\""
+                print "    url: \"" $3 "\""
+                if ($4 != "") print "    path: \"" $4 "\""
+                if ($5 != "") print "    resolved: \"" $5 "\""
+                print "    sha: \"" $6 "\""
+            }
+        ' "$tsv"
+    } > "$tmp"
+    mv "$tmp" "$lock"
+}
+
+# lock_upsert <lock> <name> <requested> <url> <path> <resolved> <sha>
+# Replace-or-append one entry, keeping the others.
+lock_upsert() {
+    local lock="$1" name="$2" requested="$3" url="$4" path="$5" resolved="$6" sha="$7"
+    local tsv="${TMPDIR:-/tmp}/intelligence-lock-$$.tsv"
+    {
+        lock_to_tsv "$lock" | awk -F"$LOCK_SEP" -v n="$name" '$1 != n'
+        printf '%s\037%s\037%s\037%s\037%s\037%s\n' \
+            "$name" "$requested" "$url" "$path" "$resolved" "$sha"
+    } > "$tsv"
+    lock_write_from_tsv "$lock" "$tsv"
+    rm -f "$tsv"
+}
+
+# lock_remove <lock> <name>
+lock_remove() {
+    local lock="$1" name="$2"
+    [ -f "$lock" ] || return 0
+    local tsv="${TMPDIR:-/tmp}/intelligence-lock-$$.tsv"
+    lock_to_tsv "$lock" | awk -F"$LOCK_SEP" -v n="$name" '$1 != n' > "$tsv"
+    if [ -s "$tsv" ]; then
+        lock_write_from_tsv "$lock" "$tsv"
+    else
+        rm -f "$lock"
+    fi
+    rm -f "$tsv"
+}

package/cli/lib/manifest.sh

@@ -0,0 +1,211 @@
+#!/bin/bash
+# The CLI-owned YAML shapes: quoted-key maps (`packages:`, `registries:` in
+# the manifest, `packages:` in the lock and in registry indexes).
+#
+# The engine deliberately never reads these blocks, and its readers cannot
+# hold `@scope/name` keys — so this is the CLI's single, deliberate parser,
+# scoped to exactly one shape:
+#
+#   block:
+#     "@scope/name":            # 2-space indent, key always quoted
+#       field: "value"          # 4-space indent
+#     "@scope/other": "value"   # flat form (registries)
+#
+# Every editor stages to `<file>.cli.tmp` and `mv`s — the migrations
+# discipline — and preserves unrelated lines and comments byte-for-byte.
+
+# Package names are paths (store dirs) and YAML keys, so the charset is
+# closed: scoped, one slash, no spaces / quotes / colons.
+assert_valid_pkg_name() {
+    case "$1" in
+        @*/*) ;;
+        *) die "invalid package name '$1' — expected @scope/name" ;;
+    esac
+    case "$1" in
+        *[!@/A-Za-z0-9._-]*|*/*/*) die "invalid package name '$1' — allowed: letters, digits, . _ -, one '/'" ;;
+    esac
+}
+
+# qmap_keys <file> <block> — quoted keys, one per line.
+qmap_keys() {
+    [ -f "$1" ] || return 0
+    awk -v block="$2" '
+        { sub(/\r$/, "") }
+        $0 ~ "^" block ":[ \t]*$" { inb = 1; next }
+        inb && /^[^ #]/ { inb = 0 }
+        inb {
+            if ($0 ~ /^  "/) {
+                s = substr($0, 4)
+                q = index(s, "\"")
+                if (q > 0) print substr(s, 1, q - 1)
+            }
+        }
+    ' "$1"
+}
+
+# qmap_field <file> <block> <key> <field> — 4-indent field value under a
+# quoted key; strips surrounding quotes and a trailing unquoted comment.
+qmap_field() {
+    [ -f "$1" ] || return 0
+    awk -v block="$2" -v key="$3" -v field="$4" '
+        { sub(/\r$/, "") }
+        $0 ~ "^" block ":[ \t]*$" { inb = 1; next }
+        inb && /^[^ #]/ { inb = 0; ink = 0 }
+        inb && /^  "/ {
+            s = substr($0, 4); q = index(s, "\"")
+            ink = (q > 0 && substr(s, 1, q - 1) == key)
+            next
+        }
+        inb && ink && /^    [A-Za-z_]/ {
+            line = $0
+            sub(/^    /, "", line)
+            c = index(line, ":")
+            if (c == 0) next
+            if (substr(line, 1, c - 1) != field) next
+            v = substr(line, c + 1)
+            sub(/^[ \t]+/, "", v)
+            if (v ~ /^"/) { v = substr(v, 2); q2 = index(v, "\""); if (q2 > 0) v = substr(v, 1, q2 - 1) }
+            else { sub(/[ \t]+#.*$/, "", v); sub(/[ \t]+$/, "", v) }
+            print v
+            exit
+        }
+    ' "$1"
+}
+
+# qmap_value <file> <block> <key> — flat form: `  "key": "value"`.
+qmap_value() {
+    [ -f "$1" ] || return 0
+    awk -v block="$2" -v key="$3" '
+        { sub(/\r$/, "") }
+        $0 ~ "^" block ":[ \t]*$" { inb = 1; next }
+        inb && /^[^ #]/ { inb = 0 }
+        inb && /^  "/ {
+            s = substr($0, 4); q = index(s, "\"")
+            if (q == 0 || substr(s, 1, q - 1) != key) next
+            v = substr(s, q + 1)
+            sub(/^:[ \t]*/, "", v)
+            if (v ~ /^"/) { v = substr(v, 2); q2 = index(v, "\""); if (q2 > 0) v = substr(v, 1, q2 - 1) }
+            else { sub(/[ \t]+#.*$/, "", v); sub(/[ \t]+$/, "", v) }
+            if (v != "") print v
+            exit
+        }
+    ' "$1"
+}
+
+# _qmap_stage <file> <awk-program> [awk args…] — run an editing pass, verify
+# it produced output, commit.
+_qmap_stage() {
+    local file="$1"; shift
+    local tmp="$file.cli.tmp"
+    awk "$@" "$file" > "$tmp"
+    [ -s "$tmp" ] || { rm -f "$tmp"; die "internal: manifest edit produced an empty file for $file"; }
+    mv "$tmp" "$file"
+}
+
+# qmap_set <file> <block> <key> <field> <value> — upsert one field, creating
+# the block and the key as needed.
+qmap_set() {
+    local file="$1" block="$2" key="$3" field="$4" value="$5"
+    [ -f "$file" ] || die "no such file: $file"
+    _qmap_stage "$file" -v block="$block" -v key="$key" -v field="$field" -v value="$value" '
+        function keyline()   { return "  \"" key "\":" }
+        function fieldline() { return "    " field ": \"" value "\"" }
+        function flush_key() {
+            # leaving the key without having written the field -> append it
+            if (ink && !done) { print fieldline(); done = 1 }
+            ink = 0
+        }
+        function flush_block() {
+            if (inb && !keyseen && !done) { print keyline(); print fieldline(); keyseen = 1; done = 1 }
+            inb = 0
+        }
+        { sub(/\r$/, "") }
+        $0 ~ "^" block ":[ \t]*$" { blockseen = 1; inb = 1; print; next }
+        inb && /^[^ #]/ { flush_key(); flush_block() }
+        inb && /^  "/ {
+            flush_key()
+            s = substr($0, 4); q = index(s, "\"")
+            if (q > 0 && substr(s, 1, q - 1) == key) { keyseen = 1; ink = 1 }
+            print; next
+        }
+        inb && ink && /^    [A-Za-z_]/ {
+            line = $0; sub(/^    /, "", line)
+            c = index(line, ":")
+            if (c > 0 && substr(line, 1, c - 1) == field) { print fieldline(); done = 1; next }
+            print; next
+        }
+        { print }
+        END {
+            flush_key(); flush_block()
+            if (!blockseen) {
+                print block ":"
+                print keyline()
+                print fieldline()
+            }
+        }
+    '
+}
+
+# qmap_set_value <file> <block> <key> <value> — flat-form upsert.
+qmap_set_value() {
+    local file="$1" block="$2" key="$3" value="$4"
+    [ -f "$file" ] || die "no such file: $file"
+    _qmap_stage "$file" -v block="$block" -v key="$key" -v value="$value" '
+        function entry() { return "  \"" key "\": \"" value "\"" }
+        { sub(/\r$/, "") }
+        $0 ~ "^" block ":[ \t]*$" { blockseen = 1; inb = 1; print; next }
+        inb && /^[^ #]/ { if (!done) { print entry(); done = 1 }; inb = 0 }
+        inb && /^  "/ {
+            s = substr($0, 4); q = index(s, "\"")
+            if (q > 0 && substr(s, 1, q - 1) == key) { print entry(); done = 1; next }
+        }
+        { print }
+        END {
+            if (inb && !done) { print entry(); done = 1 }
+            if (!blockseen) { print block ":"; print entry() }
+        }
+    '
+}
+
+# qmap_delete_key <file> <block> <key> — drop the key and everything indented
+# under it. Flat-form entries are one line, block-form keys take their fields
+# with them. The block header stays even when it empties.
+qmap_delete_key() {
+    local file="$1" block="$2" key="$3"
+    [ -f "$file" ] || return 0
+    _qmap_stage "$file" -v block="$block" -v key="$key" '
+        { sub(/\r$/, "") }
+        $0 ~ "^" block ":[ \t]*$" { inb = 1; print; next }
+        inb && /^[^ #]/ { inb = 0; drop = 0 }
+        inb && /^  "/ {
+            s = substr($0, 4); q = index(s, "\"")
+            drop = (q > 0 && substr(s, 1, q - 1) == key)
+            if (drop) next
+        }
+        inb && drop && /^    / { next }
+        { print }
+    '
+}
+
+# sources_remove_entry <file> <section> <entry> — remove `- "entry"` from
+# sources.<section>. Inverse of the engine-side _mig_add_source.
+sources_remove_entry() {
+    local file="$1" section="$2" entry="$3"
+    [ -f "$file" ] || return 0
+    _qmap_stage "$file" -v section="$section" -v entry="$entry" '
+        { sub(/\r$/, "") }
+        /^sources:[ \t]*$/ { ins = 1; print; next }
+        ins && /^[^ #]/ { ins = 0; insec = 0 }
+        ins && $0 ~ "^  " section ":[ \t]*$" { insec = 1; print; next }
+        ins && /^  [A-Za-z_]/ { insec = 0 }
+        insec {
+            line = $0
+            sub(/^[ \t]*-[ \t]*/, "", line)
+            gsub(/["\x27]/, "", line)
+            sub(/[ \t]+#.*$/, "", line)
+            sub(/[ \t]+$/, "", line)
+            if (line == entry) next
+        }
+        { print }
+    '
+}

package/cli/lib/registry.sh

@@ -0,0 +1,141 @@
+#!/bin/bash
+# Name -> source resolution and package fetching.
+#
+# Resolution order (first hit wins):
+#   1. project `registries:` — a scope bound to a registry repo (a git repo
+#      holding index.yaml); private orgs override anything shipped
+#   2. the bundled default index (registry/index.yaml next to the CLI)
+#   3. convention: @org/name -> https://github.com/org/name.git, content at
+#      the repo root — the zero-infrastructure default
+#
+# An index is itself fetched with git (never curl): auth, proxies and private
+# hosting all come for free, and the CLI keeps the engine's bash+awk+git-only
+# dependency footprint.
+
+default_index_file() {
+    local f="$CLI_DIR/../registry/index.yaml"
+    [ -f "$f" ] && printf '%s' "$f"
+    return 0
+}
+
+# _fetch_index <registry-repo-url> — clones the registry repo (shallow) and
+# prints the path of its index.yaml; empty on failure. Cached per run+url.
+_fetch_index() {
+    local url="$1" cache key tmp
+    cache="${TMPDIR:-/tmp}/intelligence-cli-index-$$"
+    key="$(printf '%s' "$url" | cksum | awk '{print $1}')"
+    if [ -f "$cache/$key/index.yaml" ]; then
+        printf '%s' "$cache/$key/index.yaml"
+        return 0
+    fi
+    mkdir -p "$cache"
+    tmp="$cache/$key"
+    if GIT_TERMINAL_PROMPT=0 git -c core.autocrlf=false clone --depth 1 --quiet "$url" "$tmp" 2>/dev/null \
+        && [ -f "$tmp/index.yaml" ]; then
+        printf '%s' "$tmp/index.yaml"
+    fi
+    return 0
+}
+
+# resolve_package_source <manifest-or-empty> <@scope/name>
+# Sets RES_URL, RES_PATH (may be empty = repo root), RES_VIA — the caller's
+# result contract, invisible to per-file shellcheck.
+# shellcheck disable=SC2034
+resolve_package_source() {
+    local manifest="$1" name="$2"
+    local scope="${name%%/*}" short="${name#*/}"
+    RES_URL=""; RES_PATH=""; RES_VIA=""
+
+    if [ -n "$manifest" ] && [ -f "$manifest" ]; then
+        local reg_url index
+        reg_url="$(qmap_value "$manifest" "registries" "$scope")"
+        if [ -n "$reg_url" ]; then
+            index="$(_fetch_index "${reg_url#git+}")"
+            [ -n "$index" ] || die "registry for scope '$scope' is unreachable or has no index.yaml: $reg_url"
+            RES_URL="$(qmap_field "$index" "packages" "$name" "url")"
+            RES_PATH="$(qmap_field "$index" "packages" "$name" "path")"
+            [ -n "$RES_URL" ] || die "package '$name' not found in the '$scope' registry ($reg_url)"
+            RES_VIA="registry:$reg_url"
+            return 0
+        fi
+    fi
+
+    local bundled
+    bundled="$(default_index_file)"
+    if [ -n "$bundled" ]; then
+        RES_URL="$(qmap_field "$bundled" "packages" "$name" "url")"
+        if [ -n "$RES_URL" ]; then
+            RES_PATH="$(qmap_field "$bundled" "packages" "$name" "path")"
+            RES_VIA="index"
+            return 0
+        fi
+    fi
+
+    RES_URL="https://github.com/${scope#@}/$short.git"
+    RES_PATH=""
+    RES_VIA="convention"
+    return 0
+}
+
+# fetch_package <url> <ref> <subpath> <dest-dir>
+# Shallow-clones url@ref (tag, branch, or SHA fallback), copies <subpath>
+# (or the repo root) into <dest-dir>, prints the resolved commit sha.
+# The clone pins autocrlf/eol/symlinks exactly like the engine does, so the
+# store holds the bytes the package published.
+fetch_package() {
+    local url="$1" ref="$2" subpath="$3" dest="$4"
+    local tmp sha src
+    local -a branch_arg=()
+    [ -n "$ref" ] && branch_arg=(--branch "$ref")
+    tmp="$(mktemp -d -t intelligence-pkg-XXXXXX 2>/dev/null || mktemp -d)"
+    if ! GIT_TERMINAL_PROMPT=0 git -c core.symlinks=false -c core.autocrlf=false -c core.eol=lf \
+            clone --depth 1 "${branch_arg[@]+"${branch_arg[@]}"}" --quiet "$url" "$tmp/clone" 2>/dev/null; then
+        # A SHA is not clonable with --branch — fall back to a full clone + checkout.
+        rm -rf "$tmp/clone"
+        GIT_TERMINAL_PROMPT=0 git -c core.symlinks=false -c core.autocrlf=false -c core.eol=lf \
+            clone --quiet "$url" "$tmp/clone" 2>/dev/null \
+            || { rm -rf "$tmp"; die "cannot clone $url"; }
+        [ -z "$ref" ] || git -C "$tmp/clone" checkout --quiet "$ref" \
+            || { rm -rf "$tmp"; die "ref '$ref' not found in $url"; }
+    fi
+    sha="$(git -C "$tmp/clone" rev-parse HEAD)"
+    src="$tmp/clone"
+    if [ -n "$subpath" ]; then
+        case "$subpath" in
+            *..*) rm -rf "$tmp"; die "unsafe path '$subpath'" ;;
+        esac
+        src="$tmp/clone/$subpath"
+        [ -d "$src" ] || { rm -rf "$tmp"; die "path '$subpath' not found in $url${ref:+@$ref}" ; }
+    fi
+    rm -rf "$dest"
+    mkdir -p "$dest"
+    cp -R "$src/." "$dest/"
+    # A nested repository would land as an untracked .git — the store must
+    # hold plain files only.
+    rm -rf "$dest/.git"
+    rm -rf "$tmp"
+    printf '%s' "$sha"
+}
+
+# wire_package_sources <manifest> <@scope/name> <store-rel-dir>
+# The provides convention: whichever of rules/agents/skills the installed
+# package has becomes a sources entry. Reuses the engine's idempotent,
+# comment-preserving _mig_add_source.
+wire_package_sources() {
+    local manifest="$1" name="$2" rel="$3" root="$4"
+    local section
+    for section in rules agents skills; do
+        if [ -d "$root/$rel/$section" ]; then
+            _mig_add_source "$manifest" "$section" "$rel/$section"
+        fi
+    done
+}
+
+# unwire_package_sources <manifest> <store-rel-dir>
+unwire_package_sources() {
+    local manifest="$1" rel="$2"
+    local section
+    for section in rules agents skills; do
+        sources_remove_entry "$manifest" "$section" "$rel/$section"
+    done
+}