@hasna/instructions 0.6.1 → 0.7.1

package/README.md

@@ -18,9 +18,15 @@ bun add --global @hasna/instructions
 
 ```bash
 instructions --help
-instructions init
+
+# Hosted-by-default: resolves the approved key and uses
+# https://api.hasna.com/instructions/v1.
+instructions status
 instructions list
-instructions profile resolve
+
+# Explicit on-box SQLite mode; there is never an implicit fallback.
+HASNA_INSTRUCTIONS_LOCAL=1 instructions init
+HASNA_INSTRUCTIONS_LOCAL=1 instructions list
 ```
 
 ## Migrating from `@hasna/configs`
@@ -29,13 +35,30 @@ This package was formerly `@hasna/configs`. The `configs` CLI alias and
 `configs-mcp` alias remain available for existing integrations; new usage can
 use the `instructions` names.
 
+Historical on-box rows can be migrated without overwriting the current store:
+
+```bash
+export HASNA_INSTRUCTIONS_LOCAL=1
+instructions migrate-legacy --confirm-local --json          # no-write plan
+instructions migrate-legacy --confirm-local --apply --json  # backup + transaction
+```
+
+The source defaults to `~/.hasna/configs/configs.db`; the destination defaults
+to the current `instructions.db`. A non-empty destination is refused unless
+`--merge-preserve-destination` is explicit, and that merge never overwrites an
+existing row.
+
 ## CLI Usage
 
 ```bash
 instructions --help
-instructions list                    # compact, paged summary
-instructions list --verbose          # expanded metadata, still paged
-instructions list --json             # full machine-readable records
+instructions list                                      # compact, paged summary
+instructions list --verbose                            # expanded metadata, still paged
+instructions list --json                               # legacy complete full-record array
+instructions list --json --detail compact --limit 20   # bounded identity envelope
+instructions list --json --detail compact --fields id,slug,name,version
+instructions list --json --detail full --limit 20      # explicit bounded content read
+instructions list --json --detail compact --all        # explicit complete metadata read
 instructions show <slug>             # full metadata + content
 instructions inspect <slug>          # alias for show
 instructions profile resolve
@@ -49,7 +72,9 @@ small. Human output is capped at 20 rows unless you pass `--limit`; use
 `--cursor` to continue from the next page. Detail is explicit:
 
 - `--verbose` expands list rows with descriptions, tags, and paths.
-- `--json` preserves full machine-readable records for automation.
+- Legacy `--json` with no modern detail flags preserves the complete full-record array for automation. Explicit `--limit`/`--cursor` now bound that legacy array.
+- `--detail compact` returns a content-free `{ configs, _meta }` identity envelope through the already-deployed `/v1/configs?view=identity` projection. Add `--fields` (including immutable `id`), `--all`, or `--pretty` as needed.
+- `--detail full` is the explicit content-bearing envelope; it is bounded unless `--all` is supplied.
 - `show`/`inspect` and `snapshot show` print full config or snapshot content.
 
 `instructions report --json` emits the stable `schema_version: 1` report
@@ -109,8 +134,9 @@ instructions-mcp --http          # http://127.0.0.1:8807/mcp
 MCP_HTTP=1 instructions-mcp
 ```
 
-Health: `GET http://127.0.0.1:8807/health`. MCP is also mounted on
-`instructions-serve` at `/mcp`.
+Health: `GET http://127.0.0.1:8807/health`. The production
+`instructions-serve` process deliberately does **not** mount MCP; local MCP and
+the authenticated `/v1` service remain separate authorities.
 
 ## HTTP API server (`instructions-serve`)
 
@@ -120,14 +146,20 @@ instructions-serve
 
 Surfaces:
 
-- `GET /health`, `GET /ready`, `GET /version` → `{ status, version, mode }`
+- `GET /health`, `GET /ready`, `GET /version` → `{ status, version, backend }`
 - `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).
 - No `/api/*` — the former local REST surface is not mounted (the removed
   bundled dashboard was its only consumer).
 
-### Server data backend (postgresql)
+### Server data backend (PostgreSQL, fail closed)
+
+`instructions-serve` requires `HASNA_INSTRUCTIONS_DATABASE_URL` (or its documented
+alias) for a usable `/v1` service. Without a DSN, `/health` remains a liveness
+probe but reports `backend: "unconfigured"`; `/ready` returns 503 and `/v1`
+returns a stable unavailable error. It never exposes local SQLite over the
+service boundary.
 
 When `HASNA_INSTRUCTIONS_DATABASE_URL` is set the `/v1` API reads/writes the
 shared Postgres **directly** (no local sync/cache in the service) and every
@@ -150,6 +182,16 @@ 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`.
 
+Collection responses are producer-bounded with `limit`/`cursor` envelopes.
+Current clients follow every page; `view=identity` returns an allowlisted
+metadata-only projection for configs, profiles, and machines, without loading
+instruction content or private profile fields. Retryable create and binding
+writes may send `Idempotency-Key`; PostgreSQL stores the authenticated
+principal, operation, canonical request digest, and first committed response in
+the same transaction as the domain mutation. A same-body retry replays that
+response, while key reuse with different bytes returns
+`409 IDEMPOTENCY_KEY_REUSED`.
+
 ## SDK
 
 The importable module ships INSIDE `@hasna/instructions` at the `./sdk` export
@@ -215,6 +257,95 @@ 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`.
 
+
+
+## Domain export and import
+
+`instructions export` writes a restorable Instructions domain archive v2. The
+archive contains config content and every retained config snapshot, profiles,
+ordered profile membership and config-binding metadata, profile asset bindings,
+and registered machines. Relationships are recorded by stable config/profile
+slugs and machine hostnames, so import can map them safely onto destination IDs.
+
+```bash
+instructions export --output ./instructions-domain.tar.gz
+instructions import ./instructions-domain.tar.gz # exact recovery into an empty destination
+```
+
+V2 is deliberately a recovery format, not a merge format. Import validates the
+complete archive and requires a destination with zero configs, profiles, and
+machines before the first mutation. `--overwrite` is rejected for v2 before
+destination inspection or mutation. Any validation, mutation, or readback
+failure throws and makes the CLI exit nonzero; discard that attempted
+destination and retry from a newly empty database.
+
+The manifest contains deterministic per-collection counts and SHA-256 logical
+hashes for pre/post deployment comparison without placing instruction content
+in logs. Exact deployment integrity includes config `created_at`, `updated_at`,
+and `synced_at`; snapshot `created_at`; profile `created_at` and `updated_at`;
+and machine `created_at` plus the exact `last_applied_at` value. After recovery,
+import reads the complete domain back through `ConfigStore` and verifies every
+field that interface can reproduce: config data and versions, retained snapshot
+contents, profiles, ordered bindings, asset mappings, machines, and whether a
+machine was ever applied.
+
+`ConfigStore` cannot assign archived config/profile/snapshot/machine creation or
+update timestamps, nor an exact machine `last_applied_at`; generated destination
+IDs are also intentionally remapped by stable slugs and hostnames. These values
+remain protected in the archive's exact integrity hashes but are not recreated
+by recovery. ConfigStore also has no cross-entity transaction, so an operational
+failure may leave a partial destination; the nonzero result is terminal and that
+destination must not be reused. Legacy v1 config-only archives remain importable,
+including their historical skip/overwrite conflict behavior.
+
+API keys and idempotency receipts are intentionally excluded: they are security
+and transport state that must be provisioned independently. Feedback is also
+excluded because it is product telemetry, not part of the Instructions
+configuration domain.
+
+## Native S3 backup storage
+
+S3 is an **adjunct immutable backup plane**, never a database selector. SQLite
+remains the explicit local authority and PostgreSQL remains the hosted `/v1`
+authority. Setting S3 variables alone never opens SQLite, never selects HTTP,
+and never changes CRUD routing.
+
+```bash
+export HASNA_INSTRUCTIONS_S3_BUCKET=your-private-bucket
+export HASNA_INSTRUCTIONS_AWS_REGION=us-east-1
+# Optional: HASNA_INSTRUCTIONS_S3_PREFIX (default: instructions/)
+# Optional local/S3-compatible endpoint and explicit static credentials.
+
+instructions storage status --json
+instructions export --output ./instructions-backup.tar.gz
+instructions storage backup push ./instructions-backup.tar.gz   --id 2026-09-15-pre-deploy --dry-run --json
+instructions storage backup push ./instructions-backup.tar.gz   --id 2026-09-15-pre-deploy --json
+instructions storage backup verify 2026-09-15-pre-deploy --json
+instructions storage backup pull 2026-09-15-pre-deploy   --output ./restored-instructions.tar.gz --json
+```
+
+Each backup uses traversal-safe deterministic keys, an atomically created
+payload, and an atomically created manifest containing SHA-256, byte size,
+content type, and creation time. Native S3 creation uses `If-None-Match: *`;
+concurrent different-byte writers cannot replace the winner, identical replay
+is idempotent, and an injected store without conditional-create support fails
+closed. Pulls verify the payload before an owner-only local file is written.
+Production backup buckets must enable versioning, encryption, public-access
+blocking, and S3 Object Lock with a default retention period. AWS runtime
+credentials may come from Bun's standard AWS chain (including an ECS task role);
+explicit static credentials are optional and must be a complete pair. Status
+never prints credential values or the bucket name.
+
+The production deployment runs the immutable predeploy backup push and verify
+as direct Bun commands in the exact candidate image. The GitHub runner alone
+parses the push receipt, then supplies the recorded payload and manifest version
+IDs to verification; it also checks the receipt digest and size, COMPLIANCE
+Object Lock retention for both versions, and an exact versioned-payload
+readback. Every backup gate completes before any ECR push, database migration,
+or ECS update.
+
+The public importable surface is available at `@hasna/instructions/storage`.
+
 ## Data Directory
 
 Local data (the SQLite store and backups) lives under the configs store home,

package/dist/chunks/{apply-ynfn1av7.js → apply-c3sd4agz.js}

@@ -3,20 +3,22 @@ import {
   applyConfig,
   applyConfigs,
   applyConfigsWithReport,
+  compactPathForConfigHome,
   expandPath,
   getConfigHome,
   normalizeTargetPath,
   previewConfigs
-} from "./index-axhwg61p.js";
-import"./index-v7dkb384.js";
+} from "./index-ypcef3a2.js";
+import"./index-aj66f6xr.js";
 import"./index-35z65jsa.js";
-import"./index-pkscjnj5.js";
+import"./index-3djthcm6.js";
 import"./index-nnwp92tk.js";
 export {
   previewConfigs,
   normalizeTargetPath,
   getConfigHome,
   expandPath,
+  compactPathForConfigHome,
   applyConfigsWithReport,
   applyConfigs,
   applyConfig

package/dist/chunks/{apply-sfzja1f3.js → apply-pnn7a3y7.js}

@@ -3,19 +3,22 @@ import {
   applyConfig,
   applyConfigs,
   applyConfigsWithReport,
+  compactPathForConfigHome,
   expandPath,
   getConfigHome,
   normalizeTargetPath,
   previewConfigs
-} from "./index-e9epbsvs.js";
-import"./index-1hpwskwd.js";
-import"./index-pkscjnj5.js";
+} from "./index-r7nfef2g.js";
+import"./index-6jncnnw7.js";
+import"./index-n3fjspr0.js";
+import"./index-fpeyzn3n.js";
 import"./index-bsan4c16.js";
 export {
   previewConfigs,
   normalizeTargetPath,
   getConfigHome,
   expandPath,
+  compactPathForConfigHome,
   applyConfigsWithReport,
   applyConfigs,
   applyConfig

package/dist/chunks/database-wstmr56z.js

@@ -0,0 +1,23 @@
+// @bun
+import {
+  getDatabase,
+  insertFeedback,
+  resetDatabase,
+  resetLocalDatabase
+} from "./index-5d7zdftc.js";
+import {
+  now,
+  slugify,
+  uuid
+} from "./index-ma2xmp6c.js";
+import"./index-fpeyzn3n.js";
+import"./index-bsan4c16.js";
+export {
+  uuid,
+  slugify,
+  resetLocalDatabase,
+  resetDatabase,
+  now,
+  insertFeedback,
+  getDatabase
+};

package/dist/chunks/{index-pkscjnj5.js → index-3djthcm6.js}

@@ -28,7 +28,6 @@ var ASSET_DESTINATION_STRATEGIES = ["emit-file", "install-local", "install-marke
 var ASSET_SCOPES = ["global", "project", "session"];
 var ASSET_UNINSTALL_POLICIES = ["remove-managed", "retain"];
 var ASSET_ROLLBACK_POLICIES = ["snapshot", "installer-receipt", "none"];
-
 class ConfigNotFoundError extends Error {
   constructor(id) {
     super(`Config not found: ${id}`);

package/dist/chunks/index-5d7zdftc.js

@@ -0,0 +1,186 @@
+// @bun
+import {
+  getRawStoreRoot,
+  hasInstructionsEnvAuthorityIntent
+} from "./index-fpeyzn3n.js";
+
+// src/db/database.ts
+import { Database } from "bun:sqlite";
+import { existsSync, mkdirSync, rmSync } from "fs";
+import { join } from "path";
+function getDbPath() {
+  if (process.env["HASNA_INSTRUCTIONS_DB_PATH"]) {
+    return process.env["HASNA_INSTRUCTIONS_DB_PATH"];
+  }
+  const dir = getRawStoreRoot();
+  mkdirSync(dir, { recursive: true });
+  return join(dir, "instructions.db");
+}
+var MIGRATIONS = [
+  `
+  CREATE TABLE IF NOT EXISTS configs (
+    id TEXT PRIMARY KEY,
+    name TEXT NOT NULL,
+    slug TEXT NOT NULL UNIQUE,
+    kind TEXT NOT NULL DEFAULT 'file',
+    category TEXT NOT NULL,
+    agent TEXT NOT NULL DEFAULT 'global',
+    target_path TEXT,
+    format TEXT NOT NULL DEFAULT 'text',
+    content TEXT NOT NULL DEFAULT '',
+    description TEXT,
+    tags TEXT NOT NULL DEFAULT '[]',
+    is_template INTEGER NOT NULL DEFAULT 0,
+    version INTEGER NOT NULL DEFAULT 1,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL,
+    synced_at TEXT
+  );
+
+  CREATE TABLE IF NOT EXISTS config_snapshots (
+    id TEXT PRIMARY KEY,
+    config_id TEXT NOT NULL REFERENCES configs(id) ON DELETE CASCADE,
+    content TEXT NOT NULL,
+    version INTEGER NOT NULL,
+    created_at TEXT NOT NULL
+  );
+
+  CREATE TABLE IF NOT EXISTS profiles (
+    id TEXT PRIMARY KEY,
+    name TEXT NOT NULL,
+    slug TEXT NOT NULL UNIQUE,
+    description TEXT,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+  );
+
+  CREATE TABLE IF NOT EXISTS profile_configs (
+    profile_id TEXT NOT NULL REFERENCES profiles(id) ON DELETE CASCADE,
+    config_id TEXT NOT NULL REFERENCES configs(id) ON DELETE CASCADE,
+    sort_order INTEGER NOT NULL DEFAULT 0,
+    PRIMARY KEY (profile_id, config_id)
+  );
+
+  CREATE TABLE IF NOT EXISTS machines (
+    id TEXT PRIMARY KEY,
+    hostname TEXT NOT NULL UNIQUE,
+    os TEXT,
+    last_applied_at TEXT,
+    created_at TEXT NOT NULL
+  );
+
+  CREATE TABLE IF NOT EXISTS schema_version (
+    version INTEGER PRIMARY KEY
+  );
+
+  INSERT OR IGNORE INTO schema_version (version) VALUES (1);
+  `,
+  `
+  ALTER TABLE profiles ADD COLUMN selectors TEXT NOT NULL DEFAULT '{}';
+  ALTER TABLE profiles ADD COLUMN variables TEXT NOT NULL DEFAULT '{}';
+  ALTER TABLE machines ADD COLUMN arch TEXT;
+  `,
+  `
+  ALTER TABLE configs ADD COLUMN outputs TEXT NOT NULL DEFAULT '[]';
+  `,
+  `
+  ALTER TABLE profile_configs ADD COLUMN binding TEXT NOT NULL DEFAULT '{"schema":"hasna.instructions.profile-config-binding/v1","activation":{"mode":"always"},"required":true,"fallback":"fail"}';
+  `,
+  `
+  CREATE TABLE IF NOT EXISTS profile_assets (
+    profile_id TEXT NOT NULL REFERENCES profiles(id) ON DELETE CASCADE,
+    source_config_id TEXT NOT NULL REFERENCES configs(id) ON DELETE CASCADE,
+    asset_key TEXT NOT NULL,
+    sort_order INTEGER NOT NULL DEFAULT 0,
+    binding TEXT NOT NULL,
+    PRIMARY KEY (profile_id, asset_key)
+  );
+  CREATE INDEX IF NOT EXISTS profile_assets_source_config_idx ON profile_assets (source_config_id);
+  `
+];
+var _db = null;
+function getDatabase(path) {
+  if (_db)
+    return _db;
+  if (!path && hasInstructionsEnvAuthorityIntent(process.env)) {
+    throw new Error("instructions: refusing to open the on-box SQLite store \u2014 the environment configures a hosted " + "Instructions authority or credential (HASNA_INSTRUCTIONS_*), and reading or writing the local store " + "here would silently drift from the shared dataset. Pass an explicit database path (or an injected " + "Database) to work against the on-box store deliberately.");
+  }
+  const dbPath = path || getDbPath();
+  const db = new Database(dbPath);
+  db.run("PRAGMA journal_mode = WAL");
+  db.run("PRAGMA foreign_keys = ON");
+  applyMigrations(db);
+  ensureFeedbackTable(db);
+  _db = db;
+  return db;
+}
+function resetDatabase() {
+  if (_db) {
+    try {
+      _db.close();
+    } catch {}
+  }
+  _db = null;
+}
+function resetLocalDatabase() {
+  resetDatabase();
+  const dbPath = getDbPath();
+  if (dbPath === ":memory:")
+    return;
+  for (const p of [dbPath, `${dbPath}-wal`, `${dbPath}-shm`]) {
+    if (existsSync(p))
+      rmSync(p);
+  }
+}
+function applyMigrations(db) {
+  let currentVersion = 0;
+  try {
+    const row = db.query("SELECT version FROM schema_version ORDER BY version DESC LIMIT 1").get();
+    currentVersion = row?.version ?? 0;
+  } catch {
+    currentVersion = 0;
+  }
+  const applyOne = db.transaction((index) => {
+    if (!migrationEffectAlreadyPresent(db, index))
+      db.exec(MIGRATIONS[index]);
+    db.run(`INSERT OR REPLACE INTO schema_version (version) VALUES (${index + 1})`);
+  });
+  for (let i = currentVersion;i < MIGRATIONS.length; i++)
+    applyOne(i);
+}
+function migrationEffectAlreadyPresent(db, index) {
+  if (index !== 3)
+    return false;
+  return db.query("PRAGMA table_info(profile_configs)").all().some((column) => column.name === "binding");
+}
+function ensureFeedbackTable(db) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS feedback (
+      id TEXT PRIMARY KEY DEFAULT (lower(hex(randomblob(16)))),
+      message TEXT NOT NULL,
+      email TEXT,
+      category TEXT DEFAULT 'general',
+      version TEXT,
+      machine_id TEXT,
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    )
+  `);
+  const existing = new Set(db.query("PRAGMA table_info(feedback)").all().map((r) => r.name));
+  const required = [
+    ["email", "TEXT"],
+    ["category", "TEXT DEFAULT 'general'"],
+    ["version", "TEXT"],
+    ["machine_id", "TEXT"],
+    ["created_at", "TEXT"]
+  ];
+  for (const [name, def] of required) {
+    if (!existing.has(name))
+      db.exec(`ALTER TABLE feedback ADD COLUMN ${name} ${def}`);
+  }
+}
+function insertFeedback(input, db) {
+  const d = db || getDatabase();
+  d.run("INSERT INTO feedback (message, email, category, version) VALUES (?, ?, ?, ?)", [input.message, input.email ?? null, input.category ?? "general", input.version ?? null]);
+}
+
+export { getDatabase, resetDatabase, resetLocalDatabase, insertFeedback };