@hasna/instructions 0.5.5 → 0.6.0

package/README.md

@@ -124,7 +124,8 @@ Surfaces:
 - `GET /openapi.json`, `GET /v1/openapi.json` → the OpenAPI 3.1 document the SDK
   is generated from.
 - `/v1/*` — versioned cloud API (configs, profiles, snapshots, stats).
-- `/api/*` — the local dashboard/REST surface.
+- No `/api/*` — the former local REST surface is not mounted (the removed
+  bundled dashboard was its only consumer).
 
 ### Server data backend (postgresql)
 
@@ -144,25 +145,70 @@ contracts issue-key --app instructions --scopes 'instructions:*'
 
 Env: `HASNA_INSTRUCTIONS_DATABASE_URL` (DSN) and
 `HASNA_INSTRUCTIONS_API_SIGNING_KEY` (HMAC signing secret; `HASNA_API_SIGNING_KEY`
-and `API_KEY_SIGNING_SECRET` are also accepted). Client apps use
-`INSTRUCTIONS_API_URL` + `INSTRUCTIONS_API_KEY` — never a DSN.
+and `API_KEY_SIGNING_SECRET` are also accepted). Client apps never carry a DSN —
+they resolve `HASNA_INSTRUCTIONS_API_KEY` (or the Keychain / credentials-file
+tiers) through the one `@hasna/contracts` client resolver, and the authority
+defaults to the fleet gateway `https://api.hasna.com/instructions`.
 
 ## SDK
 
-`@hasna/instructions-sdk` ships a zero-dependency typed client. The versioned
-`InstructionsV1Client` is generated from the serve OpenAPI document
-(`bun run generate:sdk`).
+The importable module ships INSIDE `@hasna/instructions` at the `./sdk` export
+(one package per app — there is no split `@hasna/instructions-sdk`). It is a
+self-contained bundle (node builtins only; the `@hasna/contracts` resolver is
+inlined at build time). The versioned `InstructionsV1Client` is generated from
+the serve OpenAPI document (`bun run generate:sdk` → `src/sdk/v1.generated.ts`).
 
-## Client transports
+```typescript
+import { createInstructionsV1ClientFromEnv } from "@hasna/instructions/sdk";
+
+const client = createInstructionsV1ClientFromEnv(); // Keychain -> disk -> HASNA_INSTRUCTIONS_API_KEY
+const { configs = [] } = await client.listConfigs({ category: "rules" });
+```
 
-Every CLI command, MCP tool, and SDK method routes through a single `ConfigStore`
-abstraction with two transports:
+`createInstructionsV1ClientFromEnv` resolves the credential through the same
+`@hasna/contracts` chain as the CLI and the MCP server — fresh on every
+request, so a rotated key heals a long-lived client without rebuilding it.
+`resolveInstructionsSdkTransport(options)` reports WHICH tier supplied the
+credential (never the value). An explicit `baseUrl` requires an explicit
+`apiKey` (hasna/apps#1794): the SDK never attaches the machine's fleet key to
+an authority the caller chose itself. No credential anywhere throws; there is
+no local mode and no unauthenticated client on this surface.
+
+## Client transports
 
-- **local** — on-box SQLite (`LocalConfigStore`), fully first-class. Used when no
-  API env vars are set.
-- **api** — HTTP `/v1` + bearer key (`CloudConfigStore`).
-  Activated by setting **both** `HASNA_INSTRUCTIONS_API_URL` and
-  `HASNA_INSTRUCTIONS_API_KEY`.
+Every CLI command, MCP tool, and SDK method resolves its credential and service
+authority through the ONE client resolver in `@hasna/contracts`
+(`hasna/apps#1720`) — the package owns no second chain. The tiers, fresh per
+call:
+
+| Tier | Credential | Authority |
+|---|---|---|
+| 1 — argument | `--api-key` / `--profile` | explicit `baseUrl` (SDK only) |
+| 2 — env pointer | `HASNA_INSTRUCTIONS_API_KEY_OVERRIDE`, `HASNA_PROFILE`, `HASNA_INSTRUCTIONS_API_KEY_REF` | — |
+| 3 — macOS Keychain | `hasna.credentials.instructions.api-key` (account `HASNA_STATION` → `hostname -s` → `$USER`) | `hasna.credentials.instructions.api-url` |
+| 4 — disk | `~/.hasna/instructions/config/credentials` (owner-only 0400/0600; `HASNA_HOME` / `HASNA_CONFIG_HOME` move the root) | same file's `HASNA_INSTRUCTIONS_API_URL` |
+| 5 — env | `HASNA_INSTRUCTIONS_API_KEY` | `HASNA_INSTRUCTIONS_API_URL` |
+
+With a credential resolved and nothing configuring the authority, the default is
+the fleet gateway `https://api.hasna.com/instructions`. The unprefixed
+`INSTRUCTIONS_API_URL` / `INSTRUCTIONS_API_KEY` names are accepted for one
+release as silent aliases one rung below the canonical `HASNA_INSTRUCTIONS_*`
+names.
+
+The two transports behind `ConfigStore`:
+
+- **api** — HTTP `/v1` through the shared authenticated transport
+  (`CloudConfigStore`). Runs fail loud with no credential: non-zero exit naming
+  the tiers consulted, no SQLite fallback, no local-fallback event.
+- **local** — on-box SQLite (`LocalConfigStore`), **opt-in only**:
+  `HASNA_INSTRUCTIONS_LOCAL=1`, honoured only when the environment configures
+  no authority and no credential. Every local run says `local mode` once on
+  stderr.
+
+Retired locations (`~/.hasna/fleet-env`, `~/.hasna/cloud`, `~/.config/hasna`,
+`$XDG_CONFIG_HOME`, a `~/.instructions/config.json` key store) are inputs
+nowhere, and no `*_MODE` / `*_STORAGE_MODE` switch selects anything — the
+transport is decided by what resolves, never by a mode word.
 
 Clients never hold a database DSN. The raw Postgres connection is a server-only
 concern (`instructions-serve`), selected by `HASNA_INSTRUCTIONS_DATABASE_URL`.
@@ -344,12 +390,9 @@ These profiles resolve machine variables like `{{WORKSPACE_ROOT}}`,
 `{{BUN_BIN_DIR}}`, `{{BUN_PATH}}`, and `{{PATH_PREFIX}}`, so synced configs can be
 portable across Linux and macOS arm64 machines.
 
-They also include project dashboard variables used by agent-managed project
+They also include the project channel variable used by agent-managed project
 workflows:
 
-- `{{PROJECT_DASHBOARD_DIR}}` -> `.hasna/project`
-- `{{PROJECT_DASHBOARD_RENDER_MANIFEST}}` -> `.hasna/project/dashboard/render.json`
-- `{{PROJECT_DASHBOARD_SNAPSHOTS_DIR}}` -> `.hasna/project/dashboard/snapshots`
 - `{{PROJECT_CHANNEL_PREFIX}}` -> `""` (no prefix; the channel is the normalized project slug)
 
 Existing profiles can be migrated in place without deleting or recreating them:
@@ -361,8 +404,9 @@ instructions profile update linux-arm64 \
 ```
 
 `instructions init` and `bun run seed` seed the
-`agent-managed-project-dashboard-standard` reference. It documents the standard
-`.hasna/project` layout, `projects dashboard *` commands, provider panel
+`agent-managed-project-dashboard-standard` reference. It documents the canonical
+per-workspace store layout (`~/.hasna/projects/workspaces/<workspace_id>/` — the
+only project-layout convention), `projects dashboard *` commands, provider panel
 commands, normalized project-slug channel naming, durable todos/goal workflow,
 and the rule that dashboards must show ids/statuses/evidence refs instead of raw
 private documents or secrets.

package/dist/cli/fail-closed-no-env.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=fail-closed-no-env.test.d.ts.map

package/dist/cli/fail-closed-no-env.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fail-closed-no-env.test.d.ts","sourceRoot":"","sources":["../../src/cli/fail-closed-no-env.test.ts"],"names":[],"mappings":""}