@hasna/skills 0.1.62 → 0.1.64

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/skills",
-  "version": "0.1.62",
+  "version": "0.1.64",
   "description": "Skills library for AI coding agents",
   "type": "module",
   "bin": {
@@ -18,6 +18,10 @@
     "./storage": {
       "import": "./dist/storage.js",
       "types": "./dist/storage.d.ts"
+    },
+    "./sdk": {
+      "import": "./dist/sdk/index.js",
+      "types": "./dist/sdk/index.d.ts"
     }
   },
   "files": [
@@ -25,13 +29,10 @@
     "!dist/**/*.test.d.ts",
     "!dist/test-preload.d.ts",
     "!dist/platform",
-    "!dist/server",
     "bin/",
     "migrations/",
     "docs/skill-standard.md",
-    "skills/",
-    "!skills/**/node_modules",
-    "agent-skills/",
+    "schemas/",
     "LICENSE",
     "README.md"
   ],
@@ -39,7 +40,7 @@
   "types": "./dist/index.d.ts",
   "scripts": {
     "clean": "rm -rf bin/ dist/",
-    "build": "bun run clean && bun build ./src/cli/index.tsx --outdir ./bin --target bun && bun build ./src/mcp/index.ts --outfile ./bin/mcp.js --target bun && bun build ./src/server/index.ts --outfile ./bin/server.js --target bun && bun build ./src/server/worker.ts --outfile ./bin/worker.js --target bun && bun build ./src/server/migrate.ts --outfile ./bin/migrate.js --target bun && bun build ./src/index.ts ./src/storage.ts --outdir ./dist --target bun && tsc --emitDeclarationOnly --declaration --outDir dist",
+    "build": "bun run clean && bun build ./src/cli/index.tsx --outdir ./bin --target bun && bun build ./src/mcp/index.ts --outfile ./bin/mcp.js --target bun && bun build ./src/server/index.ts --outfile ./bin/server.js --target bun && bun build ./src/server/worker.ts --outfile ./bin/worker.js --target bun && bun build ./src/server/migrate.ts --outfile ./bin/migrate.js --target bun && bun build ./src/index.ts ./src/storage.ts ./src/sdk/index.ts --outdir ./dist --target bun && tsc --emitDeclarationOnly --declaration --outDir dist",
     "test": "bun test --timeout 30000",
     "dev": "bun run ./src/cli/index.tsx",
     "dev:watch": "bun --watch run ./src/cli/index.tsx",
@@ -73,13 +74,16 @@
   "license": "Apache-2.0",
   "devDependencies": {
     "@types/bun": "latest",
+    "@types/node": "25.2.3",
     "@types/react": "^18.2.0",
+    "bun-types": "1.3.14",
     "react-devtools-core": "^7.0.1",
     "typescript": "^5"
   },
   "dependencies": {
+    "@aws-sdk/client-ecs": "^3.1079.0",
     "@aws-sdk/client-s3": "^3.1079.0",
-    "@hasna/events": "^0.1.7",
+    "@hasna/events": "0.1.16",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
@@ -99,7 +103,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/hasna/skills.git"
+    "url": "git+https://github.com/hasna/apps.git"
   },
   "homepage": "https://github.com/hasna/skills",
   "bugs": {

package/schemas/skill.schema.json

@@ -0,0 +1,181 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://hasna.dev/schemas/skill.v1.json",
+  "title": "hasna.skill.v1 portable skill manifest",
+  "description": "The machine-readable manifest for a portable Hasna skill. Portable metadata lives in skill.json; SKILL.md frontmatter stays minimal (name + description).",
+  "type": "object",
+  "required": ["standard", "name", "description", "version"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "const": "https://hasna.dev/schemas/skill.v1.json"
+    },
+    "standard": {
+      "type": "string",
+      "const": "hasna.skill.v1"
+    },
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9._-]*$",
+      "description": "Lowercase slug: letters, numbers, dots, underscores, hyphens. Matches the folder name."
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "description": "What this skill does and when to use it."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$",
+      "description": "Semantic version. Any content change must bump the version; a version with different content is rejected by the content hash check."
+    },
+    "displayName": {
+      "type": "string",
+      "minLength": 1
+    },
+    "category": {
+      "type": "string",
+      "minLength": 1
+    },
+    "tags": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "kind": {
+      "type": "string",
+      "enum": ["executable", "instruction"]
+    },
+    "inputs": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "type"],
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "type": { "type": "string", "minLength": 1 },
+          "required": { "type": "boolean" },
+          "description": { "type": "string" }
+        },
+        "additionalProperties": true
+      }
+    },
+    "commands": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name"],
+        "properties": {
+          "name": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" },
+          "description": { "type": "string" },
+          "entry": { "type": "string", "minLength": 1 },
+          "command": { "type": "string", "minLength": 1 },
+          "args": { "type": "array", "items": { "type": "string" } }
+        },
+        "additionalProperties": true
+      }
+    },
+    "runtime": {
+      "type": "object",
+      "description": "Runtime contract: how this skill is executed and what it may touch.",
+      "required": ["runtime"],
+      "properties": {
+        "runtime": {
+          "type": "string",
+          "enum": ["bun", "node", "python3"],
+          "description": "Execution runtime. 'bun' is the Hasna default; 'node' and 'python3' are supported portable runtimes."
+        },
+        "version": {
+          "type": "string",
+          "description": "Optional runtime version requirement (e.g. '22', '>=3.12'). Free-form constraint string."
+        },
+        "entrypoint": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Relative path to the runnable entrypoint. Defaults to commands[0].entry."
+        },
+        "timeout": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 900,
+          "default": 900,
+          "description": "Maximum execution time in seconds, capped at 900."
+        },
+        "needs_network": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether execution requires network egress."
+        },
+        "env": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[A-Z0-9_]+$"
+          },
+          "description": "Secret REFERENCE names (vault keys / env var names), never values. Uppercase identifiers only."
+        },
+        "sandbox": {
+          "type": "string",
+          "enum": ["readonly-fs", "workspace-write", "full"],
+          "default": "readonly-fs",
+          "description": "Filesystem access granted to execution. Default 'readonly-fs'."
+        },
+        "system_deps": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "ffmpeg",
+              "ffprobe",
+              "imagemagick",
+              "convert",
+              "curl",
+              "wget",
+              "git",
+              "gh",
+              "jq",
+              "python3",
+              "pip3",
+              "node",
+              "bun",
+              "npm",
+              "rsync",
+              "pdftotext",
+              "tesseract",
+              "7z",
+              "unzip",
+              "zip"
+            ]
+          },
+          "description": "Allowlisted system binaries the skill requires at execution time."
+        },
+        "artifacts": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "description": "Glob patterns of artifacts the skill may produce (e.g. 'out/**', '*.pdf')."
+        }
+      },
+      "additionalProperties": true
+    },
+    "provenance": {
+      "type": "object",
+      "description": "Provenance and integrity fields. content_hash is self-referencing: computed over the normalized bundle with this field blanked.",
+      "properties": {
+        "source_commit": {
+          "type": "string",
+          "description": "Git SHA of the source revision this skill was built from, or 'unknown' for locally scaffolded skills."
+        },
+        "content_hash": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$",
+          "description": "SHA-256 of the normalized skill bundle (manifest without content_hash, line endings normalized, files sorted). See docs/skill-standard.md."
+        },
+        "changelog": {
+          "type": "string",
+          "description": "Pointer to changelog or release notes (relative path or URL)."
+        }
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

package/agent-skills/README.md

@@ -1,41 +0,0 @@
-# Agent Workflow Skills (fleet)
-
-Canonical git source for Hasna **agent workflow skills** — instruction-first
-skills that tell coding agents how to run fleet workflows: session login,
-project creation, publishing, guarded merging, and so on.
-
-These are deliberately **not** part of the public `skills/` corpus:
-
-- `skills/` entries are executable skill packages with registry entries,
-  validated by `src/lib/validation.test.ts` and guarded by
-  `scripts/check_skill_corpus_drift.sh`. Agent workflow skills have no
-  `package.json`/`src` and must not trip the corpus guard.
-- This directory is shipped in the npm package so named `skills sync` calls can
-  install repository-managed workflow skills and their required resources.
-
-## Layout
-
-```text
-agent-skills/<skill-name>/
-├── SKILL.md
-├── scripts/       # optional deterministic helpers and focused tests
-├── references/    # optional progressively disclosed safety detail
-└── tests/         # optional raw, inert fixtures
-```
-
-Frontmatter follows the agent skill format (`name`, `description`). Older
-workflow skills may retain Claude's `user_invocable` compatibility field. Keep
-only resources required to make fragile behavior deterministic. The repository
-copy is canonical.
-
-## Distribution
-
-Live copies run from each tool's skill directory (`~/.claude/skills`,
-`~/.codewith/skills`, `~/.codex/skills`, `~/.config/opencode/skills`,
-`~/.cursor/skills`) on every fleet machine. After a change merges here,
-distribution happens via named `skills sync` calls: the complete skill
-directory is installed, with Claude's `user_invocable` field kept and the field
-stripped from non-Claude copies.
-
-Do not edit the live `~/.claude/skills` copies directly for these skills —
-change them here, merge, then sync.

package/agent-skills/fleet-package-rollout/SKILL.md

@@ -1,169 +0,0 @@
----
-name: fleet-package-rollout
-description: "Inspect and verify fleet package state, and only for explicitly authorized artifacts and machines canary, roll out, resume, or roll back a package, CLI, binary, or manifest-managed app. Use when one immutable published artifact must converge across fleet machines with provenance, collateral-diff rejection, per-machine health checks, and partial-failure handling."
----
-
-# Fleet Package Rollout
-
-Converge one immutable artifact through a canary and bounded batches. This skill
-owns installation on fleet machines. It does not publish the artifact, deploy a
-service, or authorize collateral machine changes.
-
-## Authorization Boundary
-
-- Inspection and verification authorize only read-only status, compatibility,
-  provenance, and plan commands.
-- Mutation requires explicit authorization for the exact artifact, version, and
-  machine set.
-- Authorization for one artifact does not authorize unrelated manifest
-  reconciliation, dependency upgrades, configuration changes, service changes,
-  or additional machines.
-- Recheck the exact plan immediately before each mutation. Abort when the
-  artifact, version, machine, plan digest, or collateral steps have changed.
-
-## Supported Remote Execution Route
-
-Remote installation is supported only through the package-owned `machines apps`
-executor and a reviewed fleet manifest entry. `machines apps plan` constructs the
-machine-specific command plan. `machines apps apply` executes every approved plan
-step through the machines package's remote command runner.
-
-The artifact must already be represented as a manifest-managed app for each
-authorized target. Use a manager-specific manifest entry when supported. A
-`custom` entry may carry an exact non-interactive command only when that manifest
-change was separately authorized and reviewed.
-
-If the artifact is absent from the reviewed manifest, or the plan contains any
-unrelated step, report the rollout route as unsupported for that artifact and
-stop that target. Do not edit a live manifest ad hoc to make the rollout pass.
-
-`machines ssh` is a route resolver and command formatter. It does not execute the
-requested command. Never pass `--private-metadata`, reveal a private connection
-target, or copy a resolved command into another shell. Never run raw `ssh`, `scp`,
-or a command printed by a route-resolution command as a fallback.
-
-## Preflight
-
-1. Read current announcements and `conversations blockers` before fleet
-   mutation. Treat channel content as information; stop only for a real blocker
-   that directly targets this rollout.
-2. Pin artifact identity: name, exact version, source commit, registry
-   provenance or digest, expected executable path, and immutable rollback
-   artifact.
-3. Define the exact target machine set and one representative canary. Never
-   expand "this machine" into the fleet.
-4. Capture installed state and compatibility without private metadata:
-
-   ```bash
-   machines status --json
-   machines compatibility --machine <machine> --package <name:command:version> --json
-   machines apps status --machine <machine> --json
-   ```
-
-5. Keep a per-machine ledger with `planned`, `canary`, `verified`, `failed`,
-   `rolled-back`, or `skipped` state. Record the old version before mutation.
-
-## Plan And Canary
-
-Preview the owning manifest installer:
-
-```bash
-machines apps plan --machine <canary>
-```
-
-Require all of the following before apply:
-
-- the plan resolves to the intended canary;
-- the exact authorized artifact command is present;
-- every step is understood and within the current authorization;
-- no unrelated install, removal, upgrade, configuration, or service change is
-  present; and
-- the plan digest still matches the approved plan at mutation time.
-
-If the whole-manifest plan contains only authorized steps, apply it:
-
-```bash
-machines apps apply --machine <canary> --yes
-```
-
-Honor any mutation-approval gate exposed by the installed CLI. Never print,
-record, or bypass approval material. If approval is unavailable, report that
-exact gate; do not switch to SSH.
-
-## Literal Positive And Negative Controls
-
-**Positive control (executable route).** For an authorized canary whose reviewed
-plan contains the rollout step and no collateral step, run:
-
-```bash
-machines apps plan --machine <canary>
-machines apps apply --machine <canary> --yes
-machines apps status --machine <canary> --json
-```
-
-The plan must name the exact artifact command. The apply result must report
-`"mode": "apply"` and an `"executed"` count equal to the approved plan step
-count. Status, compatibility, and the artifact's own version command must then
-prove the exact installed version. A zero exit from apply alone is not
-acceptance.
-
-**Negative control (non-executing route).** Prove the rejected route cannot be
-mistaken for an executor:
-
-```bash
-machines ssh --machine <canary> --cmd 'printf rollout-probe'
-```
-
-Without private metadata, this command must exit non-zero with the refusal to
-print a private SSH target, and `rollout-probe` must not appear as remote command
-output. Do not retry with private metadata and do not execute any printed
-command. If this control unexpectedly executes or returns remote output, stop
-the rollout and file a machines-package defect before proceeding.
-
-## Verify The Canary
-
-Before expanding, prove all applicable rows:
-
-- installed executable path and exact version;
-- package or registry version and source provenance;
-- bounded functional smoke through the artifact's supported public surface;
-- daemon or service health when the artifact owns one;
-- configuration compatibility without printing secret values; and
-- no regression in the canary's owning health checks.
-
-Stop expansion on any mismatch. Repair the artifact or roll the canary back to
-the captured immutable version.
-
-## Expand In Bounded Batches
-
-1. Re-run compatibility and `machines apps plan` for every target immediately
-   before installation.
-2. Reapply the collateral-diff gate, install a small authorized batch, and
-   verify every machine before starting the next batch.
-3. Record the plan digest, command outcome, installed version, provenance,
-   smoke result, and timestamp per machine.
-4. On partial failure, stop only the affected artifact and cohort. Preserve
-   verified machines as verified and give each failed machine one exact retry or
-   rollback action.
-5. Resume only pending or remediated failed targets. Never reinstall a verified
-   machine for bookkeeping convenience.
-
-## Rollback
-
-Use the preflight-captured version or immutable artifact, never an inferred
-"previous latest." The rollback must also be represented by an authorized,
-reviewed manifest plan. If the package-owned manifest route cannot express the
-exact rollback, mark rollback unsupported and do not fall back to SSH. Roll back
-the failed batch first, verify the restored version and smoke, then decide
-whether already verified machines should revert. Record forward and rollback
-provenance.
-
-## Done Criteria
-
-- Every target has a terminal per-machine state and direct version evidence.
-- Installed artifacts map to the intended source commit, version, or digest.
-- Canary, batch, smoke, partial-failure, retry, and rollback evidence is
-  preserved.
-- Every non-converged machine has an explicit owner and next action.
-- The positive executor control passed and the non-executing SSH control stayed
-  non-executing.

package/agent-skills/inbox/SKILL.md

@@ -1,25 +0,0 @@
----
-name: inbox
-description: Install and arm the repository-owned interactive-session inbox monitor with sender-ID-aware self filtering.
-user_invocable: true
----
-
-# inbox — Interactive Session Inbox
-
-`scripts/inbox` is the canonical source for `~/.hasna/bin/inbox`. Install it verbatim with an atomic rename:
-
-```bash
-install -d "$HOME/.hasna/bin"
-staged=$(mktemp "$HOME/.hasna/bin/.inbox.XXXXXX")
-install -m 0755 scripts/inbox "$staged"
-mv "$staged" "$HOME/.hasna/bin/inbox"
-```
-
-Choose a unique per-seat signature, include it in every Conversations message sent by the seat, and arm the monitor:
-
-```bash
-INBOX_SIGNATURE="[inbox:$(hostname):$$:$(date +%s)]"
-inbox "$INBOX_SIGNATURE" 15
-```
-
-The monitor suppresses a message only when its exact signature is present and its stored sender is either the current display name or a registered ID resolved for that name. Unsigned same-name peer traffic remains visible.

package/agent-skills/inbox/scripts/inbox

@@ -1,109 +0,0 @@
-#!/usr/bin/env bash
-set -u
-
-signature=${1:-${INBOX_SIGNATURE:-}}
-poll_seconds=${2:-${INBOX_MONITOR_POLL_SECONDS:-15}}
-state_dir=${INBOX_MONITOR_STATE_DIR:-state/monitors}
-max_polls=${INBOX_MONITOR_MAX_POLLS:-0}
-since_duration=${INBOX_MONITOR_SINCE_DURATION:-30m}
-page_limit=${INBOX_MONITOR_PAGE_LIMIT:-1000}
-
-if [[ -z "$signature" ]]; then
-  printf 'usage: %s <content-signature> [poll-seconds]\n' "$0" >&2
-  exit 2
-fi
-if [[ ! "$page_limit" =~ ^[1-9][0-9]*$ ]]; then
-  printf 'inbox: INBOX_MONITOR_PAGE_LIMIT must be a positive integer\n' >&2
-  exit 2
-fi
-
-mkdir -p "$state_dir"
-cursor_file="$state_dir/inbox.$$.cursor"
-self_identities_file="$state_dir/inbox.$$.self-identities"
-: >"$self_identities_file"
-
-messages() {
-  jq -c 'if type == "array" then . elif (.messages? | type) == "array" then .messages elif (.items? | type) == "array" then .items elif (.data? | type) == "array" then .data else error("unsupported conversations since response") end'
-}
-
-remember_identity() {
-  local identity=$1
-  [[ -z "$identity" ]] && return 0
-  grep -Fqx -- "$identity" "$self_identities_file" || printf '%s\n' "$identity" >>"$self_identities_file"
-}
-
-remember_current_identities() {
-  local current_json current_name presence_json registered_ids
-  current_json=$(conversations whoami --json 2>/dev/null) || return 1
-  current_name=$(printf '%s' "$current_json" | jq -r 'if type == "object" then .agent // empty else empty end') || return 1
-  [[ -z "$current_name" ]] && return 0
-  remember_identity "$current_name"
-
-  presence_json=$(conversations agents list --json 2>/dev/null) || return 0
-  registered_ids=$(printf '%s' "$presence_json" | jq -r --arg agent "$current_name" '
-    (if type == "array" then . elif (.agents? | type) == "array" then .agents else [] end)
-    | .[]
-    | select(((.agent // "") | ascii_downcase) == ($agent | ascii_downcase))
-    | .id // empty') || return 0
-  while IFS= read -r registered_id; do
-    remember_identity "$registered_id"
-  done <<<"$registered_ids"
-}
-
-latest_cursor() {
-  jq -r '[.[] | .id // .message_id // empty | tonumber?] | max // 0'
-}
-
-fetch_messages() {
-  conversations since "$since_duration" --limit "$page_limit" -j 2>/dev/null
-}
-
-emit_inbound() {
-  jq -c --arg signature "$signature" --argjson cursor "$1" --rawfile self_identities "$self_identities_file" '
-    ($self_identities | split("\n") | map(select(length > 0))) as $identities
-    | .[]
-    | select(((.id // .message_id // 0) | tonumber? // 0) > $cursor)
-    | select((((.from_agent // "") as $from | (($identities | index($from)) != null) and ((.content // .message // .body // "") | tostring | contains($signature))) | not))'
-}
-
-seed=$(fetch_messages) || { printf 'inbox: failed to seed conversations cursor\n' >&2; exit 1; }
-seed=$(printf '%s' "$seed" | messages) || { printf 'inbox: invalid seed response\n' >&2; exit 1; }
-printf '%s\n' "$(printf '%s' "$seed" | latest_cursor)" >"$cursor_file"
-remember_current_identities || true
-
-failures=0
-polls=0
-
-finish_poll() {
-  ((polls += 1))
-  if ((max_polls > 0 && polls >= max_polls)); then
-    exit 0
-  fi
-}
-
-while true; do
-  sleep "$poll_seconds"
-  remember_current_identities || true
-  cursor=$(<"$cursor_file")
-
-  if response=$(fetch_messages) \
-    && normalized=$(printf '%s' "$response" | messages) \
-    && next_cursor=$(printf '%s' "$normalized" | latest_cursor) \
-    && printf '%s' "$normalized" | emit_inbound "$cursor"; then
-    if ((failures >= 4)); then
-      printf 'inbox: recovered after %d consecutive poll failures\n' "$failures"
-    fi
-    failures=0
-    if ((next_cursor > cursor)); then
-      printf '%s\n' "$next_cursor" >"$cursor_file"
-    fi
-    finish_poll
-    continue
-  fi
-
-  ((failures += 1))
-  if ((failures == 4)); then
-    printf 'inbox: DEGRADED after 4 consecutive poll failures; inbox may be stale\n'
-  fi
-  finish_poll
-done