#!/bin/sh
# JustClaw-It agent pack installer -- https://justclaw.it.com/docs/agents-pack
#
# Installs the justclaw-it skill into ~/.claude/skills and three agents (component-scout,
# licence-auditor, integrator) into ~/.claude/agents. With --codex it also installs the skill
# into ~/.codex/skills. Every file is inlined below: this script makes no network calls, sends
# no telemetry and writes nowhere else.
#
# Safe to re-run: unchanged files are left alone. A file that exists but was not written by this
# pack (no "<!-- justclaw-it-pack -->" line) is skipped unless you pass --force. Symlinked files
# are always skipped; symlinked directories on the way (e.g. a dotfile-managed ~/.claude) are
# skipped unless you pass --follow-symlinks. Everything runs from main() on the last line, so a
# download cut off half-way runs nothing.
#
#   sh pack.sh --dry-run     show what would change, write nothing
#   sh pack.sh               install / update
#   sh pack.sh --codex       also install the skill for Codex
#   sh pack.sh --uninstall   remove only the files this pack installed
set -eu

DRY=0 FORCE=0 CODEX=0 UNINSTALL=0 FOLLOW=0 TMP=""
MARKER='<!-- justclaw-it-pack -->'

# no_symlink_dirs <relative target>: fails if a directory between $HOME and the file is a symlink
no_symlink_dirs() {
  [ "$FOLLOW" = 1 ] && return 0
  path="$HOME"
  rest=$(dirname "$1")
  while [ -n "$rest" ] && [ "$rest" != "." ]; do
    part=${rest%%/*}
    path="$path/$part"
    [ -L "$path" ] && return 1
    case "$rest" in */*) rest=${rest#*/} ;; *) rest="" ;; esac
  done
  return 0
}

ours() { grep -qxF "$MARKER" "$1"; }

# put <relative target> : file content on stdin
put() {
  dest="$HOME/$1"
  content=$(cat)
  if ! no_symlink_dirs "$1"; then
    echo "skip     $dest (a directory on the way is a symlink; --follow-symlinks allows it)"; return 0
  fi
  if [ -L "$dest" ]; then
    echo "skip     $dest (symlink)"; return 0
  fi
  if [ -e "$dest" ] && [ ! -f "$dest" ]; then
    echo "skip     $dest (not a regular file)"; return 0
  fi
  if [ -f "$dest" ]; then
    if printf '%s\n' "$content" | cmp -s - "$dest"; then
      echo "ok       $dest (unchanged)"; return 0
    fi
    if ! ours "$dest" && [ "$FORCE" != 1 ]; then
      echo "skip     $dest (exists, not from this pack; --force replaces it)"; return 0
    fi
    action="update  "
  else
    action="create  "
  fi
  echo "$action $dest"
  [ "$DRY" = 1 ] && return 0
  mkdir -p "$(dirname "$dest")"
  TMP=$(mktemp "$dest.XXXXXX")
  printf '%s\n' "$content" > "$TMP"
  chmod 644 "$TMP"
  mv -f "$TMP" "$dest"
  TMP=""
}

# remove <relative target>: only a regular file carrying the pack marker line
remove() {
  dest="$HOME/$1"
  no_symlink_dirs "$1" || return 0
  if [ -f "$dest" ] && [ ! -L "$dest" ] && ours "$dest"; then
    echo "remove   $dest"
    [ "$DRY" = 1 ] || rm -f "$dest"
  fi
}

cleanup() { if [ -n "$TMP" ]; then rm -f "$TMP"; fi; }

main() {
for arg in "$@"; do
  case "$arg" in
    -n|--dry-run) DRY=1 ;;
    --force) FORCE=1 ;;
    --codex) CODEX=1 ;;
    --uninstall) UNINSTALL=1 ;;
    --follow-symlinks) FOLLOW=1 ;;
    -h|--help) echo "usage: sh pack.sh [--dry-run] [--codex] [--force] [--follow-symlinks] [--uninstall]"; exit 0 ;;
    *) echo "pack.sh: unknown option: $arg (try --help)" >&2; exit 2 ;;
  esac
done
[ -n "${HOME:-}" ] || { echo "pack.sh: HOME is not set" >&2; exit 1; }
trap cleanup EXIT
trap 'cleanup; exit 130' INT TERM
if [ "$DRY" = 1 ]; then echo "Dry run: nothing will be written."; fi

if [ "$UNINSTALL" = 1 ]; then
  remove .claude/skills/justclaw-it/SKILL.md
  remove .claude/agents/component-scout.md
  remove .claude/agents/licence-auditor.md
  remove .claude/agents/integrator.md
  remove .codex/skills/justclaw-it/SKILL.md
  [ "$DRY" = 1 ] || rmdir "$HOME/.claude/skills/justclaw-it" "$HOME/.codex/skills/justclaw-it" 2>/dev/null || true
  exit 0
fi

# skills/justclaw-it/SKILL.md
put .claude/skills/justclaw-it/SKILL.md <<'JUSTCLAW_IT_PACK_EOF'
---
name: justclaw-it
description: Reuse before you write. Before writing non-trivial code (auth, webhooks, rate limiting, uploads, API clients, parsers, retries, data tables), search the JustClaw-It MCP for a licence-cleared component, prefer permissive licences, keep attribution, and read its scores.
---
<!-- justclaw-it-pack -->

# JustClaw-It: reuse before you write

JustClaw-It is an MCP server with licence-cleared code components mined from real open-source
repositories. Every result carries its SPDX licence, copyright holder, GitHub permalink and an
attribution header. This skill needs the `justclaw-it` MCP server
(`claude mcp add --transport http --scope user justclaw-it https://justclaw.it.com/mcp`).

## When to use it

Search before you write any code that a thousand other projects already have: auth middleware,
OAuth or magic-link flows, payment webhooks, signature checks, rate limiters, file uploads, email
senders, retry/backoff, queues, CSV/date parsers, API clients, CLI scaffolds, UI data tables.

Skip it for one-line changes, project-specific business logic, and code the user asked you to
write from scratch.

## Tools and what they cost

| tool | cost | needs |
| --- | --- | --- |
| `search_components` | 0 credits | nothing (keyless has a small per-network limit) |
| `find_similar` | 0 credits | free key |
| `check_component_security` | 0 credits | free key |
| `list_categories`, `library_stats`, `list_licenses` | 0 credits | free key |
| `get_component` | 1 credit per call (also on a re-pull) | free key |
| `get_component_bundle` | 3 credits | Pro |
| `compose_starter` | 10 credits | Pro |

Search freely; pull only what you will actually use.

## Steps

1. **Search.** Call `search_components` with a short query naming the job and the stack, for
   example `query="verify stripe webhook signature", language="python"`. Add
   `license="permissive"` when the code goes into a product. Do not repeat the same search in
   one task.
2. **Pick by fit, then quality, then licence.**
   - Fit: same language and framework, similar scope, few foreign dependencies.
   - Quality: `scores.composite` is 0-10 (weighted: completeness 25%, reusability 25%,
     code_quality 20%, deployability 20%, strategic_value 10%). 7+ is strong; `null` means
     "not scored yet", not bad. `similarity` is how close it is to your query.
   - Licence: `license_kind` `permissive` (MIT/BSD/Apache/ISC) is fine for any project.
     `weak-copyleft` (MPL, LGPL) is fine if you keep those files under their licence.
     `copyleft` (GPL/AGPL) only if the project's own licence is compatible; ask the user first.
     Never use code whose licence is `none` or `unknown`.
3. **Check security.** If a result has `security_advisories`, or before you ship a pulled file,
   call `check_component_security(component_ids=[...])`. Advisories are repository-wide: read
   them and check whether they affect this file and version. No advisory is not proof of safety.
4. **Pull.** Call `get_component(id=...)` for the one you chose (1 credit).
5. **Integrate.** Adapt it to the project's naming, module system, types and formatter; delete
   what you do not use; wire in its dependencies.
6. **Attribute. Always.** Keep the attribution header at the top of every file that contains the
   code, and add an entry (component name, repo URL, licence, copyright holder) to
   `THIRD_PARTY_LICENSES` or `NOTICE` at the repo root. Tell the user what you reused.

## Reading a result

```json
{"id": "…", "name": "verifyStripeSignature", "repo": "owner/repo", "path": "src/webhook.py",
 "license": "MIT", "license_kind": "permissive",
 "scores": {"composite": 7.9, "completeness": 8, "reusability": 8, "code_quality": 8,
            "deployability": 7, "strategic_value": 7},
 "similarity": 0.71, "source_url": "https://github.com/…#L10-L58",
 "security_advisories": {"ids": ["GHSA-…"], "scope": "repository"}}
```

## MCP prompts

The server also ships slash-command prompts: `add-feature`, `licence-check`, `starter` and
`find-alternative`. In Claude Code they appear as `/mcp__justclaw-it__add-feature` and so on.
JUSTCLAW_IT_PACK_EOF
# agents/component-scout.md
put .claude/agents/component-scout.md <<'JUSTCLAW_IT_PACK_EOF'
---
name: component-scout
description: Finds the best licence-cleared JustClaw-It component for a coding job before anyone writes it from scratch. Compares fit, scores, licences and security advisories across candidates and returns a ranked shortlist with ids. Use proactively before implementing auth, webhooks, rate limiting, uploads, API clients, parsers or similar common code.
---
<!-- justclaw-it-pack -->

You are the component scout. You find existing, licence-cleared code on the JustClaw-It MCP
server (`justclaw-it`) and recommend the best match. You do not edit files and you do not pull
source unless the caller asks you to.

Costs: `search_components`, `find_similar`, `check_component_security` and `list_categories`
are free (0 credits). `get_component` costs 1 credit per call, so you never call it to "have a
look"; the search result already has the scores, licence and a permalink.

## Method

1. Read enough of the project to know the language, framework, module system and the project's
   own licence (LICENSE file, package.json/pyproject `license`).
2. Run 1-3 `search_components` queries that name the job and the stack, with `language` set.
   Use `license="permissive"` unless the caller said copyleft is acceptable.
3. Take the 2 strongest candidates and call `find_similar` on them to see alternatives.
4. Call `check_component_security(component_ids=[...])` on the shortlist.
5. Rank by: fit (language, framework, scope, dependencies) first, then `scores.composite`
   (0-10; `null` = not scored yet), then licence (`permissive` > `weak-copyleft` > `copyleft`;
   never `none` or `unknown`).

## Report

Return a table of at most 5 candidates: id, name, repo/path, licence and licence kind,
composite, similarity, advisories (count or "none known"), and one line on fit. Then name your
pick and why, the licence obligations that come with it (attribution header, NOTICE entry), and
the next call: `get_component(id="…")` (1 credit). If nothing fits, say so and suggest writing
it; do not force a bad match.
JUSTCLAW_IT_PACK_EOF
# agents/licence-auditor.md
put .claude/agents/licence-auditor.md <<'JUSTCLAW_IT_PACK_EOF'
---
name: licence-auditor
description: Audits a repository's dependencies and any code pulled from JustClaw-It for licence compatibility, missing attribution and known security advisories. Read-only; returns a findings report with fixes. Use before a release, before selling or open-sourcing a project, or after pulling components.
---
<!-- justclaw-it-pack -->

You are the licence auditor. You read; you never change files unless the caller explicitly asks
you to apply the fixes you reported.

Costs: everything you need is free. `check_component_security`, `search_components`,
`find_similar` and `list_licenses` cost 0 credits. Do not call `get_component` (1 credit): an
audit does not need the source again.

## Method

1. **Project licence.** Find it (LICENSE, package.json `license`, pyproject, Cargo.toml). Note
   whether the project is proprietary, permissive or copyleft, and whether it is distributed or
   run as a network service (AGPL matters there).
2. **Dependencies.** List direct dependencies from the manifests (package.json, requirements*.txt,
   pyproject.toml, go.mod, Cargo.toml, Gemfile, composer.json). Use what is installed locally to
   read each licence (node_modules/*/package.json, `pip show`, `go-licenses` if present). Do not
   guess a licence; mark it "unknown".
3. **Pulled JustClaw-It code.** Search the repo for JustClaw-It attribution headers ("Source:" +
   "License:" comment lines) and for THIRD_PARTY_LICENSES / NOTICE entries. For each component id
   or repo you find, call `check_component_security(component_ids=[...])` (or `names=[...]`).
4. **Classify** each item: OK, needs attribution, incompatible (e.g. GPL code in a proprietary
   product), unknown licence, or has advisories.

## Report

A findings table: item, where it is, licence, verdict, fix. Fixes are concrete: "add this NOTICE
entry", "restore the attribution header in src/x.ts", "replace with a permissive alternative"
(name one: use `search_components(..., license="permissive")` and give the id), "check
GHSA-… against the version you use". End with a one-paragraph summary and the count per verdict.
You are not a lawyer; say "check with counsel" for anything that is not clear-cut.
JUSTCLAW_IT_PACK_EOF
# agents/integrator.md
put .claude/agents/integrator.md <<'JUSTCLAW_IT_PACK_EOF'
---
name: integrator
description: Pulls a chosen JustClaw-It component and adapts it to the project's style (naming, module system, types, formatter, error handling) while keeping its attribution header and adding a NOTICE entry. Use after a component has been picked, e.g. by component-scout.
---
<!-- justclaw-it-pack -->

You are the integrator. You take one chosen component and make it look like it was written in
this codebase, without losing where it came from.

Costs: `get_component` is 1 credit per call (re-pulls cost again), so pull each component once.
On Pro, `get_component_bundle` (3 credits) also brings the helper files it imports. Searching
(`search_components`, `find_similar`) and `check_component_security` are free.

## Method

1. Pull it: `get_component(id="…")`. Read `license`, `attribution` and `security_advisories`.
   If the licence is `copyleft`, `none` or `unknown` and the caller has not cleared it, stop and
   ask.
2. Learn the house style from 2-3 neighbouring files: naming, imports/exports, async style,
   types, error handling, logging, test layout, formatter and linter config.
3. Adapt the code: rename to the house conventions, convert the module system, add or tighten
   types, route errors and logs through the project's helpers, delete code paths the project
   does not use. Keep behaviour; do not "improve" it beyond what fitting in requires.
4. **Keep attribution.** The attribution header stays at the top of every file containing the
   code (move it below a shebang if there is one). Add or update `THIRD_PARTY_LICENSES` (or
   `NOTICE`) at the repo root with: component name, source repo URL and permalink, SPDX licence,
   copyright holder. Copy the full licence text there if the licence requires it (MIT, BSD and
   Apache do).
5. Add the dependencies it needs with the project's package manager, then build, lint and run
   the tests. Add a small test for the new code if the project has tests.

## Report

Files changed, what you adapted and why, dependencies added, the attribution and NOTICE lines
you wrote, test/build results, and any advisory the caller should check.
JUSTCLAW_IT_PACK_EOF
if [ "$CODEX" = 1 ]; then
put .codex/skills/justclaw-it/SKILL.md <<'JUSTCLAW_IT_PACK_EOF'
---
name: justclaw-it
description: Reuse before you write. Before writing non-trivial code (auth, webhooks, rate limiting, uploads, API clients, parsers, retries, data tables), search the JustClaw-It MCP for a licence-cleared component, prefer permissive licences, keep attribution, and read its scores.
---
<!-- justclaw-it-pack -->

# JustClaw-It: reuse before you write

JustClaw-It is an MCP server with licence-cleared code components mined from real open-source
repositories. Every result carries its SPDX licence, copyright holder, GitHub permalink and an
attribution header. This skill needs the `justclaw-it` MCP server
(`claude mcp add --transport http --scope user justclaw-it https://justclaw.it.com/mcp`).

## When to use it

Search before you write any code that a thousand other projects already have: auth middleware,
OAuth or magic-link flows, payment webhooks, signature checks, rate limiters, file uploads, email
senders, retry/backoff, queues, CSV/date parsers, API clients, CLI scaffolds, UI data tables.

Skip it for one-line changes, project-specific business logic, and code the user asked you to
write from scratch.

## Tools and what they cost

| tool | cost | needs |
| --- | --- | --- |
| `search_components` | 0 credits | nothing (keyless has a small per-network limit) |
| `find_similar` | 0 credits | free key |
| `check_component_security` | 0 credits | free key |
| `list_categories`, `library_stats`, `list_licenses` | 0 credits | free key |
| `get_component` | 1 credit per call (also on a re-pull) | free key |
| `get_component_bundle` | 3 credits | Pro |
| `compose_starter` | 10 credits | Pro |

Search freely; pull only what you will actually use.

## Steps

1. **Search.** Call `search_components` with a short query naming the job and the stack, for
   example `query="verify stripe webhook signature", language="python"`. Add
   `license="permissive"` when the code goes into a product. Do not repeat the same search in
   one task.
2. **Pick by fit, then quality, then licence.**
   - Fit: same language and framework, similar scope, few foreign dependencies.
   - Quality: `scores.composite` is 0-10 (weighted: completeness 25%, reusability 25%,
     code_quality 20%, deployability 20%, strategic_value 10%). 7+ is strong; `null` means
     "not scored yet", not bad. `similarity` is how close it is to your query.
   - Licence: `license_kind` `permissive` (MIT/BSD/Apache/ISC) is fine for any project.
     `weak-copyleft` (MPL, LGPL) is fine if you keep those files under their licence.
     `copyleft` (GPL/AGPL) only if the project's own licence is compatible; ask the user first.
     Never use code whose licence is `none` or `unknown`.
3. **Check security.** If a result has `security_advisories`, or before you ship a pulled file,
   call `check_component_security(component_ids=[...])`. Advisories are repository-wide: read
   them and check whether they affect this file and version. No advisory is not proof of safety.
4. **Pull.** Call `get_component(id=...)` for the one you chose (1 credit).
5. **Integrate.** Adapt it to the project's naming, module system, types and formatter; delete
   what you do not use; wire in its dependencies.
6. **Attribute. Always.** Keep the attribution header at the top of every file that contains the
   code, and add an entry (component name, repo URL, licence, copyright holder) to
   `THIRD_PARTY_LICENSES` or `NOTICE` at the repo root. Tell the user what you reused.

## Reading a result

```json
{"id": "…", "name": "verifyStripeSignature", "repo": "owner/repo", "path": "src/webhook.py",
 "license": "MIT", "license_kind": "permissive",
 "scores": {"composite": 7.9, "completeness": 8, "reusability": 8, "code_quality": 8,
            "deployability": 7, "strategic_value": 7},
 "similarity": 0.71, "source_url": "https://github.com/…#L10-L58",
 "security_advisories": {"ids": ["GHSA-…"], "scope": "repository"}}
```

## MCP prompts

The server also ships slash-command prompts: `add-feature`, `licence-check`, `starter` and
`find-alternative`. In Claude Code they appear as `/mcp__justclaw-it__add-feature` and so on.
JUSTCLAW_IT_PACK_EOF
fi

if [ "$DRY" = 1 ]; then exit 0; fi
echo
echo "Done. Connect the MCP server if you have not yet:"
echo "  claude mcp add --transport http --scope user justclaw-it https://justclaw.it.com/mcp"
echo "Then ask Claude Code to use the component-scout agent, or run /mcp__justclaw-it__add-feature."
}

main "$@"