@hasna/skills 0.2.1 → 0.4.0

package/README.md

@@ -11,7 +11,7 @@ Skills library for AI coding agents — discover, pin, and run reusable capabili
 bun install -g @hasna/skills
 ```
 
-Requires [Bun](https://bun.sh/) 1.0+.
+Requires [Bun](https://bun.sh/) 1.3+.
 
 ## Quick Start
 
@@ -19,11 +19,12 @@ Requires [Bun](https://bun.sh/) 1.0+.
 # Browse skills interactively
 skills
 
-# Point the CLI at a Skills API server for server-owned (premium) skill runs
-skills setup --api-url https://skills.example.com
-skills auth login --api-key "$SKILLS_API_KEY"
+# Sign in. With a credential and no URL, the CLI talks to the fleet gateway;
+# point it at your own instance first if you run one.
+skills setup --api-url https://skills.example.com   # only for your own instance
+skills auth login --api-key "$HASNA_SKILLS_API_KEY"
 
-# With no API URL configured, skills simply run on this machine
+# With no credential and no URL, skills simply run on this machine
 skills list
 
 # Optionally pin a skill preference in this project
@@ -54,21 +55,16 @@ create local run metadata, and then expose status and artifact commands. They
 do not fall back to bundled local execution when auth is missing or the server
 runtime is unavailable.
 
-Routing is config-driven and local is the default: a run is sent to the API
-only when an origin is configured (`apiUrl` or `$SKILLS_API_URL`), a credential
-is present (`SKILLS_API_KEY` or the auth store), and the skill carries the
-server-owned marker. Every other skill runs on this machine, whether or not an
-API is configured. No skill in the OSS catalog is server-owned today; the
+Routing is credential-driven and local is the default: a run is sent to the API
+only when a credential resolves (see **Credentials** below) and the skill carries
+the server-owned marker. Every other skill runs on this machine, whether or not
+a credential exists. No skill in the OSS catalog is server-owned today; the
 marker arrives with skills synced from a Skills API deployment. A server-owned
-skill run without the origin or the credential fails closed with an error
-naming the missing setup — it never silently runs locally.
-
-Use `SKILLS_API_KEY` or `skills auth login --api-key` for server-side
-execution:
+skill run without a credential fails closed with an error naming the missing
+setup — it never silently runs locally.
 
 ```bash
-skills setup --api-url https://skills.example.com
-skills auth login --api-key "$SKILLS_API_KEY"
+skills auth login --api-key "$HASNA_SKILLS_API_KEY"
 skills run <server-owned-skill> --brief "minimal geometric owl mark"
 skills runs status <run-id>
 skills exports download <run-id>
@@ -78,11 +74,73 @@ Browser/device-code and email-code login commands are retained for compatible
 deployments. A Skills deployment can bootstrap with a provisioned API key via
 `skills auth login --api-key`.
 
-`SKILLS_API_KEY` is the Skills API credential. It is not a provider
+`HASNA_SKILLS_API_KEY` is the Skills API credential. It is not a provider
 credential. Provider keys such as `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or
 `GEMINI_API_KEY` remain supported only for free/local OSS skills whose
 requirements explicitly document local provider use.
 
+## Credentials
+
+The credential and the service address are resolved by the shared client in
+[`@hasna/contracts`](https://www.npmjs.com/package/@hasna/contracts), the same
+ladder every Hasna CLI uses. Nothing here is resolved twice, and this package
+keeps no credential store of its own.
+
+**The credential, in precedence order, resolved fresh on every call:**
+
+| # | Tier | Where |
+|---|------|-------|
+| 1 | Explicit argument | `--api-key`, `--profile` |
+| 2 | Deliberate env pointer | `HASNA_SKILLS_API_KEY_OVERRIDE`, `HASNA_PROFILE`, `HASNA_SKILLS_API_KEY_REF` (a secrets-vault item key, never a value) |
+| 3 | macOS Keychain | generic-password item `hasna.credentials.skills.api-key`, account `$HASNA_STATION`, else `hostname -s`, else `$USER` |
+| 4 | Disk | `~/.hasna/skills/config/credentials` (mode 0400/0600; `HASNA_HOME` and `HASNA_CONFIG_HOME` relocate it; XDG is never consulted) |
+| 5 | Environment | `HASNA_SKILLS_API_KEY` — a legitimate tier, and deliberately *below* disk |
+
+Tier 5 sits below disk on purpose. A wrapper that injects `HASNA_SKILLS_API_KEY`
+into one child process re-reads its store every time and cannot go stale; a shell
+`export` can, and after a key rotation the file on disk is the correct one.
+
+`skills auth login` writes tier 4. A tier an operator set on purpose (1 and 2)
+never falls through to another identity: if it cannot be honoured, the command
+fails rather than acting as a different principal.
+
+`HASNA_SKILLS_API_KEY_REF` names a *vault item*, not a key, so it resolves in two
+steps: the item is fetched through the `@hasna/secrets` SDK on each call, which
+means a rotated item is picked up without a restart — and which means the SDK has
+to be installed in the process. Every way that fetch can fail (SDK absent, vault
+unreachable, item missing or empty) is terminal and exits non-zero; a pointer
+never falls through to another tier, and never to the local corpus.
+
+**The service address, in the same shape:**
+
+`HASNA_SKILLS_API_URL` → the Keychain item `hasna.credentials.skills.api-url` →
+`~/.hasna/skills/config/credentials` → the fleet gateway
+`https://api.hasna.com/skills`. The gateway default applies only once a
+credential has resolved, so an install with no credential names no host at all.
+`skills setup --api-url <origin>` writes the credentials file; the address is
+per-user, never per-project.
+
+The unprefixed `SKILLS_API_KEY` and `SKILLS_API_URL` spellings are still accepted
+as silent aliases one rung below the canonical names, for one release. Use the
+`HASNA_`-prefixed names. `SKILL_API_KEY` (singular) is no longer read at all.
+
+**Three outcomes, and no fourth:**
+
+- a credential resolves → **hosted**, against the configured URL or the gateway.
+  A credential that resolves but cannot produce a usable key — a deliberate
+  selection that cannot be honoured, a vault pointer whose item is missing, any
+  tier that yields a blank value — is a **loud failure** too, never a demotion;
+- no credential but a URL is configured → **loud failure**, exit non-zero. There
+  is no local fallback: answering from the bundled corpus while authentication is
+  unconfigured is a false green;
+- neither → **local**. Skills ships its corpus, so running on this machine is a
+  real mode; it prints one line on stderr saying so.
+
+The retired locations are not read: `auth.json` (in either the app directory or
+the legacy `~/.skills/`), the old fleet-env and per-machine cloud env folders
+under `~/.hasna`, and the XDG config directory. `~/.hasna` is a closed namespace
+of app folders, and `XDG_CONFIG_HOME` is not consulted at all.
+
 ## CLI Commands
 
 | Command | Alias | Description |
@@ -117,12 +175,12 @@ requirements explicitly document local provider use.
 | `skills billing status` | | Show server account plan and balance |
 | `skills billing checkout` | | Create a checkout session when billing is enabled |
 | `skills billing portal` | | Create a customer portal session when billing is enabled |
-| `skills credits buy <amount>` | | Create a credit-pack checkout session when billing is enabled |
+| `skills credits buy <pack-id>` | | Create a credit-pack checkout session when billing is enabled |
 | `skills setup-info` | | Version, pinned skills, agent configs, paths |
 | `skills export` | | Export pinned skills as JSON |
 | `skills import <file>` | | Pin skills from a JSON export |
 | `skills config set <key> <value>` | | Set default agent, scope, output format, or API origin |
-| `skills config unset <key>` | | Remove a configuration value (`skills config unset apiUrl` returns to running on this machine) |
+| `skills config unset <key>` | | Remove a configuration value (`skills config unset apiUrl` clears the stored service address and returns to running on this machine) |
 | `skills new <name>` | `scaffold` | Scaffold a portable skill under `~/.hasna/skills/installed/<name>` |
 | `skills port <path>` | `add` | Import an existing skill folder into the portable standard |
 | `skills create <name>` | | Scaffold a new custom skill directory |
@@ -146,7 +204,7 @@ requirements explicitly document local provider use.
 - `--brief` — One-line format
 - `--limit <n>` — Cap human rows where supported; use `--limit all` or `--limit 0` for every row
 - `--cursor <n>` — Continue human-output pagination from a numeric offset
-- `--remote` — Read browse/search data from `SKILLS_API_URL` or `config apiUrl`
+- `--remote` — Read browse/search data from the configured Skills instance (see **Credentials**)
 - `--dry-run` — Preview without applying changes
 - `--verbose` — Debug logging globally; richer human discovery rows where supported
 - `--no-color` — Disable ANSI colors
@@ -206,15 +264,16 @@ Stable command shapes:
 ## Remote Registry
 
 The npm package ships no bundled skill corpus. Discovery reads the local corpus
-cache (`~/.hasna/skills/installed`, filled by `skills pull`) and, when an API
-base URL is set, the server's registry. This is not a mode you select: pointing
-browse/search commands at a server's registry is one fact, an API base URL being
-set. To set it:
+cache (`~/.hasna/skills/installed`, filled by `skills pull`) and, when a
+credential resolves, the server's registry. This is not a mode you select:
+whether browse/search commands read a server's registry is one fact, whether a
+credential resolves (see [Credentials](#credentials)). To point at your own
+instance:
 
 ```bash
-export SKILLS_API_URL=https://your-server.example
-# or persist it:
-skills config set apiUrl https://your-server.example
+export HASNA_SKILLS_API_URL=https://your-server.example
+# or persist it in the credentials file the shared ladder reads:
+skills setup --api-url https://your-server.example
 # and to stop using it:
 skills config unset apiUrl
 
@@ -228,8 +287,9 @@ If the URL is an origin such as `https://your-server.example`, the CLI requests
 `/api/v1/skills`. If it already ends in `/api` or `/api/v1`, the CLI appends
 `/skills`.
 
-Authenticated registry listing and premium server-side execution use
-`SKILLS_API_KEY` or the credential saved by `skills auth login --api-key`.
+Authenticated registry listing and premium server-side execution use whichever
+credential the ladder resolves — most often the one saved by
+`skills auth login --api-key`.
 
 The typed `RemoteSkillsClient` also exposes pin, tag, and cursor-based
 incremental-sync methods (`listPins`/`pin`/`unpin`, `listTags`/`skillsByTag`,
@@ -306,16 +366,100 @@ skills mcp --register all       # Register with all supported agents
 
 ## Skills API
 
+Use a named profile for each independently operated instance. A commercial Skills instance
+and an internal instance have separate credentials, accounts,
+credits and data. Selecting one does not change another profile or the fleet
+resolver's existing defaults.
+
 ```bash
-skills setup --api-url https://skills.example.com
-skills auth login --api-key "$SKILLS_API_KEY"
-skills billing status
+# Configure the commercial instance before signing in.
+skills --profile customer setup --api-url https://skills.example.com/api/v1 --json
+skills --profile customer auth signup --email you@example.com --json
+skills --profile customer auth login --email you@example.com --code <CODE> --json
+skills --profile customer auth whoami --json
+skills --profile customer capabilities --json
+skills --profile customer list --remote --json
+
+# Quote without spending. Put CLI flags before the skill name.
+skills --profile customer quote --json blog-article --topic "Your topic"
+skills --profile customer run --remote --yes --wait --json --idempotency-key article-001 blog-article --topic "Your topic"
+skills --profile customer runs status <run-id> --json
+skills --profile customer runs logs <run-id> --json
+skills --profile customer runs artifacts <run-id> --json
+skills --profile customer exports download <run-id> --json
+
+skills --profile customer billing status --json
+skills --profile customer billing usage --json
+skills --profile customer billing invoices --json
+skills --profile customer credits packs --json
+skills --profile customer credits buy <pack-id> --json
+skills --profile customer billing portal --json
+skills --profile customer auth keys list --email you@example.com --code <FRESH-CODE> --json
+# Request a fresh OTP, then create a separately scoped key (shown once).
+skills --profile customer auth signup --email you@example.com --json
+skills --profile customer auth keys create automation --email you@example.com --code <CODE> --scope runs:read --json
+skills --profile customer auth logout --json
 ```
 
-Account, run, log, artifact, and optional billing commands use the configured
-Skills API. The public package stores only local configuration
-and CLI credentials. Artifacts can be stored in S3 when `HASNA_SKILLS_S3_BUCKET`
-is configured.
+An origin, a full `/api/v1` base and a base with a path prefix normalize to the
+same routes. `HASNA_PROFILE=customer` selects the same profile as `--profile`.
+`HASNA_SKILLS_API_URL` (or the compatible `SKILLS_API_URL`) is an explicit URL
+override, not permission to send a saved key to a different instance. Stored
+keys retain their original instance binding; sign in to a separate profile to
+switch instances. `HASNA_HOME` / `HASNA_CONFIG_HOME` isolate credential state;
+`HASNA_SKILLS_DIR` separately isolates corpus/configuration data. They do not
+require changing `HOME`.
+
+A paid remote run requires explicit approval. Interactive runs ask before
+submission; JSON and other noninteractive runs require `--yes`. The approved
+quote becomes the server-enforced credit ceiling. A changed price above that
+ceiling fails before admission. A compatible server must advertise bounded
+approval; older or unsupported APIs return errors, not local results. Reuse the
+same idempotency key only for an identical submission to safely recover an
+interrupted response. `runs cancel` and `runs resume` call the server's lifecycle
+operations and can be refused when the current state does not allow them.
+
+`run --remote --file input.txt ...` declares upload hashes before admission and
+uploads bytes without forwarding the account key to storage. Failed uploads
+request cancellation. Upload support must be advertised by the server.
+Downloads verify authenticated size and SHA-256 metadata before writing files;
+existing files and unsafe paths are refused. CLI/SDK downloads are bounded to
+64 MiB; MCP inline artifacts and input files are limited to 1 MiB. Listing, creating and revoking API keys require fresh email OTP reauthentication; an existing
+API key cannot grant new key authority. Checkout
+commands return external links; payment confirmation remains in the browser.
+
+The MCP server uses the same account, quote, run and artifact client. Agent
+hosts must launch `skills-mcp --stdio`; the standalone default is loopback HTTP.
+Configure its environment with the selected `HASNA_PROFILE` and isolated state
+paths. `run_skill` accepts `remote:true`, `maxCredits`, `idempotency_key`, and
+optional inline `files:[{name,base64,contentType}]`. An omitted ceiling permits
+only free execution. `quote_skill` never submits a run.
+
+```ts
+import { RemoteSkillsAuthClient, createRemoteSkillsClient } from "@hasna/skills/sdk";
+
+// Auth transports never write credentials; the embedding application owns storage.
+const auth = new RemoteSkillsAuthClient("https://skills.example.com/api/v1");
+await auth.requestCode("you@example.com");
+// await auth.verifyCode("you@example.com", code);
+
+// Uses the same selected profile and credential binding as CLI/MCP.
+const client = await createRemoteSkillsClient(process.env);
+if (!client) throw new Error("Configure an instance and sign in first");
+const quote = await client.quoteRun("blog-article", {}, ["--topic", "Your topic"]);
+// Obtain explicit user approval of quote.pricing.costCents before this call.
+const run = await client.submitQuotedRun("blog-article", {}, ["--topic", "Your topic"], {
+  maxCredits: quote.pricing.costCents,
+  idempotencyKey: "article-001",
+});
+```
+
+`submitRun` remains a low-level compatibility transport. New paid integrations
+should use `submitQuotedRun` or `submitQuotedRunWithFiles` so capability and
+approval checks run before submission. Credit counts are integers; `maxCostCents`
+is a legacy spelling for the same credit ceiling. Missing billing capabilities
+on an internal instance are explicit unsupported responses; this package does
+not add a billing engine to the OSS server.
 
 ### Server database
 
@@ -324,11 +468,15 @@ different product: the schema, the organization scoping, and the run lifecycle a
 identical either way.
 
 ```bash
-skills-server                                            # SQLite at ~/.hasna/skills/server.db
-HASNA_SKILLS_DATABASE_URL=<path>/server.db skills-server
-HASNA_SKILLS_DATABASE_URL=postgres://user:CHANGEME@host/skills skills-server
+skills-serve                                              # SQLite at ~/.hasna/skills/server.db
+HASNA_SKILLS_DATABASE_URL=<path>/server.db skills-serve
+HASNA_SKILLS_DATABASE_URL=postgres://user:CHANGEME@host/skills skills-serve
 ```
 
+> **Bin naming:** the canonical server bin is `skills-serve`; `skills-server` remains
+> installed as a deprecated alias for one release (same entrypoint). `skills-worker`
+> and `skills-migrate` are additional documented surfaces.
+
 | `HASNA_SKILLS_DATABASE_URL` | Backend | Survives restart |
 | --- | --- | --- |
 | *(unset)* | SQLite at `<data dir>/server.db` | yes |
@@ -368,8 +516,8 @@ SQLite file, so it stays usable as a deploy gate.
 
 `HASNA_SKILLS_DATABASE_URL` and `DATABASE_URL` are server-only. CLI, MCP, and SDK
 clients never read them and never open a database connection: a client reaches
-the cloud only through `SKILLS_API_URL` plus an API key (the `apiKey` stored by
-`skills auth`, or `SKILLS_API_KEY`). The one exception is the repo-native storage
+the cloud only through the resolved API URL plus the resolved API key (see
+[Credentials](#credentials)). The one exception is the repo-native storage
 sync under [Storage Boundary](#storage-boundary), an operator tool that
 intentionally reads the same variables.
 
@@ -387,7 +535,7 @@ Three things the server will not do:
 against the same file — nothing more. A container without a persistent volume gets a
 database in its own ephemeral layer, and two replicas each get their *own* database
 rather than sharing one. Multi-replica and container deployments want Postgres; both
-`skills-server` and `skills-worker` print the database they opened on startup, so a
+`skills-serve` and `skills-worker` print the database they opened on startup, so a
 split-brain SQLite setup shows up as two different paths in the logs.
 
 <a id="storage-boundary"></a>
@@ -452,7 +600,7 @@ skills/                      # Public skill contracts and local OSS skills
 |---|---|---|
 | Catalog skills | 86 | `SKILLS.length` (`src/lib/registry-data/`) |
 | Categories | 17 | `CATEGORIES` (`src/lib/registry-types.ts`) |
-| MCP tools | 37 | `tools/list` against a live `buildServer()` |
+| MCP tools | 56 | `tools/list` against a live `buildServer()` |
 
 Every number in this table is re-derived from the source tree on each test run by
 `src/lib/readme-derived-counts.test.ts`, so a drifted figure fails a test rather