@ainova-systems/intelligence 0.11.0-rc.1 → 0.11.0-rc.11

package/cli/lib/lockfile.sh

@@ -12,7 +12,7 @@ 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.
+# engine's read_schema_version is hardwired to its own key.
 top_scalar() {
     [ -f "$1" ] || return 0
     awk -v key="$2" '
@@ -54,14 +54,18 @@ lock_write_from_tsv() {
         echo "lockfile_version: $LOCKFILE_VERSION"
         echo "engine_version: \"$(bundled_engine_version)\""
         echo "packages:"
+        # Values reach a double-quoted YAML scalar: a `"` or `\` in any of
+        # them (registry-supplied url/path included) must be escaped, or it
+        # would break or alias the neighbouring field.
         awk -F"$LOCK_SEP" '
+            function esc(s) { gsub(/\\/, "\\\\", s); gsub(/"/, "\\\"", s); return s }
             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 "\""
+                print "  \"" esc($1) "\":"
+                if ($2 != "") print "    requested: \"" esc($2) "\""
+                print "    url: \"" esc($3) "\""
+                if ($4 != "") print "    path: \"" esc($4) "\""
+                if ($5 != "") print "    resolved: \"" esc($5) "\""
+                print "    sha: \"" esc($6) "\""
             }
         ' "$tsv"
     } > "$tmp"
@@ -72,7 +76,8 @@ lock_write_from_tsv() {
 # 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"
+    local tsv
+    tsv="$(mktemp -t intelligence-lock-XXXXXX 2>/dev/null || mktemp)"
     {
         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' \
@@ -86,7 +91,8 @@ lock_upsert() {
 lock_remove() {
     local lock="$1" name="$2"
     [ -f "$lock" ] || return 0
-    local tsv="${TMPDIR:-/tmp}/intelligence-lock-$$.tsv"
+    local tsv
+    tsv="$(mktemp -t intelligence-lock-XXXXXX 2>/dev/null || mktemp)"
     lock_to_tsv "$lock" | awk -F"$LOCK_SEP" -v n="$name" '$1 != n' > "$tsv"
     if [ -s "$tsv" ]; then
         lock_write_from_tsv "$lock" "$tsv"

package/cli/lib/manifest.sh

@@ -24,6 +24,102 @@ assert_valid_pkg_name() {
     case "$1" in
         *[!@/A-Za-z0-9._-]*|*/*/*) die "invalid package name '$1' — allowed: letters, digits, . _ -, one '/'" ;;
     esac
+    # Both segments become store path components fed to rm -rf: an empty one
+    # ('@scope/') resolves to the whole scope dir, and a dot segment walks the
+    # tree — either would turn one bad --name into deleting other packages.
+    local scope="${1%%/*}" short="${1#*/}"
+    case "${scope#@}" in
+        ""|.|..) die "invalid package name '$1' — empty or dot scope" ;;
+    esac
+    case "$short" in
+        ""|.|..) die "invalid package name '$1' — empty or dot name" ;;
+    esac
+}
+
+# Target names become adapter filenames and shell function suffixes, so keep
+# them inside the portable shell-identifier subset used by built-in adapters.
+assert_valid_target_name() {
+    case "$1" in
+        ""|[!abcdefghijklmnopqrstuvwxyz]*|*[!abcdefghijklmnopqrstuvwxyz0123456789_]*)
+            die "invalid target name '$1' — expected [a-z][a-z0-9_]*"
+            ;;
+    esac
+}
+
+# target_exists <manifest> <name> — distinguish a disabled target from one
+# that is not declared at all. Both inline and block target shapes count.
+target_exists() {
+    local file="$1" target="$2"
+    [ -f "$file" ] || return 1
+    awk -v target="$target" '
+        { sub(/\r$/, "") }
+        /^targets:[[:space:]]*$/ { in_targets = 1; next }
+        /^[A-Za-z]/ { in_targets = 0 }
+        in_targets && $0 ~ "^  " target ":[[:space:]]*" { found = 1; exit }
+        END { exit(found ? 0 : 1) }
+    ' "$file"
+}
+
+# target_set_enabled <manifest> <name> <true|false> <default-output>
+# Transactionally update only `enabled`, preserving every other target field
+# and comment. A missing target is added in the compact form used by init.
+target_set_enabled() {
+    local file="$1" target="$2" enabled="$3" output="$4"
+    [ -f "$file" ] || die "no such file: $file"
+    case "$enabled" in true|false) ;; *) die "internal: invalid target state '$enabled'" ;; esac
+    output="$(_yq_esc "$output")"
+    _qmap_stage "$file" -v target="$target" -v enabled="$enabled" -v output="$output" '
+        function entry() { return "  " target ": { enabled: " enabled ", output: \"" output "\" }" }
+        function add_enabled_to_inline(line,    p) {
+            p = index(line, "{")
+            if (p > 0) return substr(line, 1, p) " enabled: " enabled "," substr(line, p + 1)
+            return line
+        }
+        function flush_target() {
+            if (in_target && !enabled_seen) print "    enabled: " enabled
+            in_target = 0
+        }
+        function flush_targets() {
+            flush_target()
+            if (in_targets && !target_seen) { print entry(); target_seen = 1 }
+            in_targets = 0
+        }
+        { sub(/\r$/, "") }
+        /^targets:[[:space:]]*$/ { targets_seen = 1; in_targets = 1; print; next }
+        in_targets && /^[A-Za-z]/ { flush_targets() }
+        in_targets && /^  [A-Za-z]/ {
+            flush_target()
+            if ($0 ~ "^  " target ":[[:space:]]*") {
+                target_seen = 1
+                if (match($0, /enabled:[[:space:]]*(true|false)/)) {
+                    print substr($0, 1, RSTART - 1) "enabled: " enabled substr($0, RSTART + RLENGTH)
+                    enabled_seen = 1
+                } else if ($0 ~ /\{/) {
+                    print add_enabled_to_inline($0)
+                    enabled_seen = 1
+                } else {
+                    print
+                    in_target = 1
+                    enabled_seen = 0
+                }
+                next
+            }
+        }
+        in_target && /^    enabled:[[:space:]]*/ {
+            print "    enabled: " enabled
+            enabled_seen = 1
+            next
+        }
+        { last = $0; print }
+        END {
+            flush_targets()
+            if (!targets_seen) {
+                if (last != "") print ""
+                print "targets:"
+                print entry()
+            }
+        }
+    '
 }
 
 # qmap_keys <file> <block> — quoted keys, one per line.
@@ -104,9 +200,19 @@ _qmap_stage() {
 
 # qmap_set <file> <block> <key> <field> <value> — upsert one field, creating
 # the block and the key as needed.
+# _yq_esc <string> — escape \ and " for a double-quoted YAML scalar.
+_yq_esc() {
+    local s="$1"
+    s="${s//\\/\\\\}"
+    printf '%s' "${s//\"/\\\"}"
+}
+
 qmap_set() {
     local file="$1" block="$2" key="$3" field="$4" value="$5"
     [ -f "$file" ] || die "no such file: $file"
+    # url/path values can carry a `"`; escape before it reaches the quoted
+    # scalar the writer emits.
+    value="$(_yq_esc "$value")"
     _qmap_stage "$file" -v block="$block" -v key="$key" -v field="$field" -v value="$value" '
         function keyline()   { return "  \"" key "\":" }
         function fieldline() { return "    " field ": \"" value "\"" }
@@ -134,10 +240,13 @@ qmap_set() {
             if (c > 0 && substr(line, 1, c - 1) == field) { print fieldline(); done = 1; next }
             print; next
         }
-        { print }
+        { last = $0; print }
         END {
             flush_key(); flush_block()
             if (!blockseen) {
+                # A block appended to a file that does not end blank would
+                # otherwise glue itself onto the previous section.
+                if (last != "") print ""
                 print block ":"
                 print keyline()
                 print fieldline()
@@ -150,6 +259,7 @@ qmap_set() {
 qmap_set_value() {
     local file="$1" block="$2" key="$3" value="$4"
     [ -f "$file" ] || die "no such file: $file"
+    value="$(_yq_esc "$value")"
     _qmap_stage "$file" -v block="$block" -v key="$key" -v value="$value" '
         function entry() { return "  \"" key "\": \"" value "\"" }
         { sub(/\r$/, "") }
@@ -159,10 +269,14 @@ qmap_set_value() {
             s = substr($0, 4); q = index(s, "\"")
             if (q > 0 && substr(s, 1, q - 1) == key) { print entry(); done = 1; next }
         }
-        { print }
+        { last = $0; print }
         END {
             if (inb && !done) { print entry(); done = 1 }
-            if (!blockseen) { print block ":"; print entry() }
+            if (!blockseen) {
+                if (last != "") print ""
+                print block ":"
+                print entry()
+            }
         }
     '
 }
@@ -187,8 +301,147 @@ qmap_delete_key() {
     '
 }
 
+# qmap_delete_field <file> <block> <key> <field> — drop one field from a
+# quoted-key entry without disturbing its other fields or surrounding YAML.
+qmap_delete_field() {
+    local file="$1" block="$2" key="$3" field="$4"
+    [ -f "$file" ] || return 0
+    _qmap_stage "$file" -v block="$block" -v key="$key" -v field="$field" '
+        { sub(/\r$/, "") }
+        $0 ~ "^" block ":[ \t]*$" { inb = 1; print; next }
+        inb && /^[^ #]/ { inb = 0; ink = 0 }
+        inb && /^  "/ {
+            s = substr($0, 4); q = index(s, "\"")
+            ink = (q > 0 && substr(s, 1, q - 1) == key)
+            print; next
+        }
+        inb && ink && /^    [A-Za-z_]/ {
+            line = $0; sub(/^    /, "", line)
+            c = index(line, ":")
+            if (c > 0 && substr(line, 1, c - 1) == field) next
+        }
+        { print }
+    '
+}
+
+# --- registries: a trust LIST, not a scope map -----------------------------
+# The block holds registry repo URLs in trust order. Two shapes are read so
+# early manifests keep working: the list form (`- "url"`) and the retired
+# flat-map form (`"@scope": "url"` — the scope label is ignored, the URL is
+# simply another registry).
+
+# registries_list <file> — registry URLs, one per line, manifest order.
+registries_list() {
+    [ -f "$1" ] || return 0
+    awk '
+        { sub(/\r$/, "") }
+        /^registries:[ \t]*$/ { inb = 1; next }
+        inb && /^[^ #]/ { inb = 0 }
+        inb {
+            line = $0
+            if (line ~ /^[ \t]*-[ \t]*/) {
+                sub(/^[ \t]*-[ \t]*/, "", line)
+            } else if (line ~ /^  "/) {
+                c = index(line, ":")
+                if (c == 0) next
+                line = substr(line, c + 1)
+            } else next
+            sub(/^[ \t]+/, "", line)
+            gsub(/["\x27]/, "", line)
+            sub(/[ \t]+#.*$/, "", line)
+            sub(/[ \t]+$/, "", line)
+            if (line != "") print line
+        }
+    ' "$1"
+}
+
+# registries_add <file> <url> — idempotent append in list form.
+registries_add() {
+    local file="$1" url="$2" existing
+    while IFS= read -r existing; do
+        [ "$existing" = "$url" ] && return 0
+    done < <(registries_list "$file")
+    _qmap_stage "$file" -v url="$url" '
+        function entry() { return "  - \"" url "\"" }
+        { sub(/\r$/, "") }
+        /^registries:[ \t]*$/ { blockseen = 1; inb = 1; print; next }
+        inb && /^[^ #]/ { if (!done) { print entry(); done = 1 }; inb = 0 }
+        { last = $0; print }
+        END {
+            if (inb && !done) { print entry(); done = 1 }
+            if (!blockseen) {
+                if (last != "") print ""
+                print "registries:"
+                print entry()
+            }
+        }
+    '
+}
+
+# registries_remove <file> <url> — drop the entry, either shape.
+registries_remove() {
+    local file="$1" url="$2"
+    [ -f "$file" ] || return 0
+    _qmap_stage "$file" -v url="$url" '
+        { sub(/\r$/, "") }
+        /^registries:[ \t]*$/ { inb = 1; print; next }
+        inb && /^[^ #]/ { inb = 0 }
+        inb {
+            line = $0
+            v = ""
+            if (line ~ /^[ \t]*-[ \t]*/) { v = line; sub(/^[ \t]*-[ \t]*/, "", v) }
+            else if (line ~ /^  "/) { c = index(line, ":"); if (c > 0) v = substr(line, c + 1) }
+            if (v != "") {
+                sub(/^[ \t]+/, "", v)
+                gsub(/["\x27]/, "", v)
+                sub(/[ \t]+#.*$/, "", v)
+                sub(/[ \t]+$/, "", v)
+                if (v == url) next
+            }
+        }
+        { print }
+    '
+}
+# True (0) if <config> already lists <entry> under any sources section. Quoted
+# and bare spellings both count - a manifest may hold either.
+_mig_has_source() {
+    local config="$1" entry="$2"
+    [ -f "$config" ] || return 1
+    grep -Fq -- "\"$entry\"" "$config" || grep -Fq -- "- $entry" "$config"
+}
+
+
+# sources_add_entry_first <file> <section> <entry> — idempotent insert at the
+# TOP of sources.<section> (creating sources:/section as needed). Package
+# entries go through this so project-owned entries stay later in the list —
+# adapters copy sources in order and the last write wins, which is exactly
+# the documented "your file overrides the package's" behavior.
+sources_add_entry_first() {
+    local file="$1" section="$2" entry="$3"
+    _mig_has_source "$file" "$entry" && return 0
+    _qmap_stage "$file" -v section="$section" -v entry="$entry" '
+        function line() { return "    - \"" entry "\"" }
+        { sub(/\r$/, "") }
+        /^sources:[ \t]*$/ { ins = 1; sourceseen = 1; print; next }
+        ins && /^[^ #]/ {
+            if (!secseen && !done) { print "  " section ":"; print line(); done = 1 }
+            ins = 0
+        }
+        ins && $0 ~ "^  " section ":[ \t]*$" { secseen = 1; print; print line(); done = 1; next }
+        { print }
+        END {
+            if (ins && !secseen && !done) { print "  " section ":"; print line(); done = 1 }
+            if (!sourceseen) {
+                print "sources:"
+                print "  " section ":"
+                print line()
+            }
+        }
+    '
+}
+
 # sources_remove_entry <file> <section> <entry> — remove `- "entry"` from
-# sources.<section>. Inverse of the engine-side _mig_add_source.
+# sources.<section>.
 sources_remove_entry() {
     local file="$1" section="$2" entry="$3"
     [ -f "$file" ] || return 0

package/cli/lib/registry.sh

@@ -1,36 +1,46 @@
 #!/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
+# A name resolves ONLY through the manifest's `registries:` trust list (git
+# repos holding index.yaml, consulted in order; the first to declare the name
+# wins). There is deliberately no built-in catalog and no name->github
+# convention: the CLI core knows no vendor, and a name nobody explicitly
+# trusted must never silently turn into an install from a guessed URL.
+# Sources without a registry are always EXPLICIT: github:org/repo, git+<url>.
+# Vendor defaults exist only as lines `init` writes into the manifest —
+# visible, reviewable, deletable.
+#
+# The NAME is the trust anchor a developer reasons with; source integrity is
+# a separate mechanism: the lock pins url+sha, and `status --check` flags
+# resolution/lock url drift.
 #
 # 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-$$"
+    local url="$1" key tmp
+    assert_safe_source_url "$url"
+    # Per-run private cache dir under an UNPREDICTABLE mktemp path (a fixed
+    # /tmp/...-$$ would be trusted on cache hit and pre-creatable by others).
+    # No EXIT trap: _fetch_index is always called inside $( ), so a trap would
+    # fire in that subshell and delete the dir before the caller reads it. The
+    # dir is small and OS-reaped from the temp root; IS_REMOTE_CACHE-style
+    # persistence is exported so repeated calls in one command share it.
+    if [ -z "${IS_CLI_INDEX_CACHE:-}" ]; then
+        IS_CLI_INDEX_CACHE="$(mktemp -d -t intelligence-cli-index-XXXXXX 2>/dev/null || mktemp -d)"
+        export IS_CLI_INDEX_CACHE
+    fi
+    local cache="$IS_CLI_INDEX_CACHE"
     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 \
+    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
@@ -43,38 +53,57 @@ _fetch_index() {
 # shellcheck disable=SC2034
 resolve_package_source() {
     local manifest="$1" name="$2"
-    local scope="${name%%/*}" short="${name#*/}"
     RES_URL=""; RES_PATH=""; RES_VIA=""
 
+    local reg_url index
     if [ -n "$manifest" ] && [ -f "$manifest" ]; then
-        local reg_url index
-        reg_url="$(qmap_value "$manifest" "registries" "$scope")"
-        if [ -n "$reg_url" ]; then
+        while IFS= read -r reg_url; do
+            [ -n "$reg_url" ] || continue
             index="$(_fetch_index "${reg_url#git+}")"
-            [ -n "$index" ] || die "registry for scope '$scope' is unreachable or has no index.yaml: $reg_url"
+            if [ -z "$index" ]; then
+                echo "  WARN: registry unreachable or missing index.yaml, skipped: $reg_url" >&2
+                continue
+            fi
             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
+            if [ -n "$RES_URL" ]; then
+                RES_PATH="$(qmap_field "$index" "packages" "$name" "path")"
+                RES_VIA="registry:$reg_url"
+                return 0
+            fi
+        done < <(registries_list "$manifest")
     fi
+    # No trusted registry declares the name. Deliberately NOT an invented
+    # URL: the caller reports it, with suggestions.
+    return 0
+}
 
-    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
+# suggest_similar <manifest-or-empty> <@scope/name> — "Did you mean" lines to
+# stderr, matched on the short name (singular/plural tolerant) across every
+# trusted registry.
+suggest_similar() {
+    local manifest="$1" name="$2"
+    local want cand cshort reg_url index seen=" "
+    want="${name#*/}"; want="${want%s}"
+    _suggest_from() {
+        local idx="$1"
+        [ -n "$idx" ] && [ -f "$idx" ] || return 0
+        while IFS= read -r cand; do
+            [ -n "$cand" ] || continue
+            case "$seen" in *" $cand "*) continue ;; esac
+            cshort="${cand#*/}"; cshort="${cshort%s}"
+            if [ "$cshort" = "$want" ] && [ "$cand" != "$name" ]; then
+                seen="$seen$cand "
+                echo "  Did you mean: intelligence package add $cand" >&2
+            fi
+        done < <(qmap_keys "$idx" "packages")
+    }
+    if [ -n "$manifest" ] && [ -f "$manifest" ]; then
+        while IFS= read -r reg_url; do
+            [ -n "$reg_url" ] || continue
+            index="$(_fetch_index "${reg_url#git+}")"
+            _suggest_from "$index"
+        done < <(registries_list "$manifest")
     fi
-
-    RES_URL="https://github.com/${scope#@}/$short.git"
-    RES_PATH=""
-    RES_VIA="convention"
-    return 0
 }
 
 # fetch_package <url> <ref> <subpath> <dest-dir>
@@ -84,25 +113,45 @@ resolve_package_source() {
 # store holds the bytes the package published.
 fetch_package() {
     local url="$1" ref="$2" subpath="$3" dest="$4"
+    assert_safe_source_url "$url"
+    assert_safe_ref "$ref"
+    # Bundle seed: the engine-content package at the CLI's own version copies
+    # from the npm bundle — no network, which keeps init, sync restoration and
+    # archived-project conversion offline. Keyed on the
+    # full (url, path, ref) triple; any other version or source falls through
+    # to the normal clone.
+    if [ "$url" = "$SYNC_PKG_URL" ] && [ "$subpath" = "$SYNC_PKG_PATH" ] \
+        && [ "${ref#v}" = "$(bundled_engine_version)" ]; then
+        [ -n "${IS_BUNDLED_PKG_DIR:-}" ] && [ -d "$IS_BUNDLED_PKG_DIR" ] \
+            || die "bundled engine content not found next to the CLI — reinstall @ainova-systems/intelligence"
+        rm -rf "$dest"
+        mkdir -p "$dest"
+        cp -R "$IS_BUNDLED_PKG_DIR/." "$dest/"
+        rm -rf "$dest/.git"
+        if [ -f "$IS_ENGINE_DIR/ENGINE_SHA" ]; then
+            tr -d ' \t\r\n' < "$IS_ENGINE_DIR/ENGINE_SHA"
+        fi
+        return 0
+    fi
     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
+            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 \
+            clone --quiet -- "$url" "$tmp/clone" 2>/dev/null \
             || { rm -rf "$tmp"; die "cannot clone $url"; }
-        [ -z "$ref" ] || git -C "$tmp/clone" checkout --quiet "$ref" \
+        [ -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'" ;;
+            *..*|/*|*[\"\']*) 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}" ; }
@@ -119,14 +168,14 @@ fetch_package() {
 
 # 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.
+# package has becomes a sources entry — inserted FIRST in its section, so
+# project-owned entries come later and win on same-named artifacts.
 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"
+            sources_add_entry_first "$manifest" "$section" "$rel/$section"
         fi
     done
 }

package/cli/lib/semver.sh

@@ -39,9 +39,12 @@ semver_match() {
         ""|"*"|latest) return 0 ;;
     esac
     local op="" base="$range"
+    # Both strip patterns are quoted: an unquoted `~` in ${range#~} is a tilde
+    # EXPANSION (it becomes $HOME), so the prefix never strips and every
+    # `~x.y.z` range silently matches nothing.
     case "$range" in
-        "^"*) op="^"; base="${range#^}" ;;
-        "~"*) op="~"; base="${range#~}" ;;
+        "^"*) op="^"; base="${range#'^'}" ;;
+        "~"*) op="~"; base="${range#'~'}" ;;
     esac
     base="${base#v}"
     semver_is_stable "$base" || return 1
@@ -72,7 +75,11 @@ semver_match() {
 # onto their tag.
 list_remote_versions() {
     local url="$1"
-    GIT_TERMINAL_PROMPT=0 git ls-remote --tags "$url" 2>/dev/null \
+    assert_safe_source_url "$url"
+    # `|| true` inside the pipeline: an unreachable repo must read as "no
+    # versions", not kill a pipefail caller mid-command-substitution —
+    # reachability is the CALLER's question (add probes it explicitly).
+    { GIT_TERMINAL_PROMPT=0 git ls-remote --tags -- "$url" 2>/dev/null || true; } \
         | awk '{
             sub(/\r$/, "")
             ref = $2
@@ -89,7 +96,8 @@ list_remote_versions() {
 # prints "<tag> <sha>". Peeled sha (the commit a tag object points at) wins.
 remote_tag_for_version() {
     local url="$1" ver="${2#v}"
-    GIT_TERMINAL_PROMPT=0 git ls-remote --tags "$url" 2>/dev/null \
+    assert_safe_source_url "$url"
+    { GIT_TERMINAL_PROMPT=0 git ls-remote --tags -- "$url" 2>/dev/null || true; } \
         | awk -v want="$ver" '
             {
                 sub(/\r$/, "")

package/engine/ENGINE_SHA

@@ -0,0 +1 @@
+9be4945e8194e82d53d510e72b7a30769ff30e95

package/engine/{scripts/adapters → adapters}/_template.sh

@@ -1,22 +1,21 @@
 #!/bin/bash
-# intelligence-sync: Adapter template
-# Copy this file to create a new IDE adapter.
+# Intelligence CLI: project adapter template
+# Scaffold this file with: intelligence adapter create <name>
 #
 # This file is NOT executable as-is — `<name>` placeholders below would be
 # parsed by bash as input redirection (`<` operator). Replace every
 # occurrence with your adapter name before sourcing.
 #
 # Required:
-#   1. Name the file: <ide-name>.sh (e.g., myide.sh)
-#   2. Replace every `<name>` placeholder with your adapter name
-#   3. Implement sync_to_<name>() function
-#   4. Add target to config.yaml:
+#   1. Implement sync_to_<name>() and its three content transforms
+#   2. Enable it after implementation: intelligence adapter enable <name>
+#      This adds the target to intelligence.yaml when it is absent:
 #      targets:
 #        <name>: { enabled: true, output: ".<name>" }
 #
 # The sync_to_<name>() function receives:
 #   $1 = repo_root     — absolute path to the project root
-#   $2 = config_file   — absolute path to config.yaml
+#   $2 = config_file   — absolute path to intelligence.yaml
 #   $3 = output_dir    — absolute path to the output directory (e.g., .myide/)
 #
 # Available library functions (from lib/common.sh):
@@ -29,10 +28,12 @@
 #   get_model_default(ide, tier)        — hardcoded default for ide:tier
 #   map_access_to_claude_tools(access)  — full->"" (no tools list; inherits all), readonly->restricted
 #   map_access_to_claude_disallowed(access) — readonly->"Write, Edit", full->""
-#   read_yaml_list(config, section)     — read list from config.yaml
+#   read_yaml_list(manifest, section)   — read a source list from intelligence.yaml
 #   get_target_field(config, target, field) — read a target's config field
 
-source "$(dirname "${BASH_SOURCE[0]}")/../lib/common.sh"
+# Project adapters are sourced by engine/sync.sh after the shared library is
+# loaded. Keep this template position-independent: after scaffolding it lives
+# under the project's content directory, not beside engine/lib/.
 
 # Sync rules for <agent-name>
 # Typical transformations: