@hasna/machines 0.0.14 → 0.0.15

package/LICENSE

@@ -1,3 +1,4 @@
+
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
@@ -175,7 +176,7 @@
 
    END OF TERMS AND CONDITIONS
 
-   Copyright 2026 hasna
+   Copyright 2026 Hasna, Inc.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/README.md

@@ -8,6 +8,21 @@ Machine fleet management for developers — provision, sync, inspect, and operat
 - `machines-mcp`: MCP server exposing fleet tools to AI agents
 - `machines-agent`: lightweight local daemon for heartbeats and runtime reporting
 
+## HTTP mode
+
+Long-lived Streamable HTTP transport for shared agent connections (stdio remains the default):
+
+```bash
+machines-mcp --http
+# or: MCP_HTTP=1 machines-mcp
+# default port: 8821 (override with --port or MCP_HTTP_PORT)
+```
+
+Endpoints on `127.0.0.1` only:
+
+- `GET /health` → `{"status":"ok","name":"machines"}`
+- `POST /mcp` → MCP Streamable HTTP
+
 ## Manifest
 
 `machines.json` is the desired fleet declaration.
@@ -32,6 +47,78 @@ machines doctor --machine spark01
 machines self-test
 ```
 
+## Topology SDK
+
+`@hasna/machines` exposes a compact topology SDK for other open-core packages
+that need machine identity without importing CLI internals:
+
+```ts
+import { discoverMachineTopology, getLocalMachineTopology } from "@hasna/machines";
+
+const topology = discoverMachineTopology();
+const local = getLocalMachineTopology();
+```
+
+The SDK merges manifest entries, local heartbeats, SSH route hints, and
+`tailscale status --json` peers when Tailscale is available. Consumers such as
+`@hasna/knowledge` should treat this package as optional: dynamically import it
+when present, and fall back to local probes or app-local machine registries when
+it is absent.
+
+CLI and MCP expose the same topology view:
+
+```bash
+machines topology --json
+machines topology --no-tailscale --json
+```
+
+## Compatibility SDK
+
+Open-core consumers can use `@hasna/machines` to preflight a peer before
+attempting app-level sync:
+
+```ts
+import { checkMachineCompatibility } from "@hasna/machines";
+
+const report = checkMachineCompatibility({
+  machineId: "spark01",
+  commands: [{ command: "bun" }],
+  packages: [{ name: "@hasna/knowledge", command: "knowledge", expectedVersion: "0.2.29" }],
+  workspaces: [{ label: "open-knowledge", path: "/home/hasna/workspace/hasna/opensource/open-knowledge" }],
+});
+```
+
+The compatibility report checks command availability, package-backed CLI
+versions, workspace paths, and package metadata without printing secrets.
+`knowledge` uses this as an optional preflight before machine sync, and falls
+back to its own local checks if `@hasna/machines` is not installed.
+
+CLI and MCP expose the same shape:
+
+```bash
+machines compatibility --machine spark01 \
+  --command bun \
+  --package @hasna/knowledge:knowledge:0.2.29 \
+  --workspace open-knowledge=/home/hasna/workspace/hasna/opensource/open-knowledge \
+  --json
+```
+
+## Storage
+
+Machines stores runtime data locally in SQLite under the Hasna data directory and includes repo-owned PostgreSQL migrations for remote storage deployments.
+
+```bash
+machines storage status --json
+HASNA_MACHINES_DATABASE_URL=postgres://... machines storage push --tables agent_heartbeats --json
+machines storage pull --json
+machines storage sync --json
+```
+
+Configure database storage with `HASNA_MACHINES_DATABASE_URL` or fallback
+`MACHINES_DATABASE_URL`. Optional storage mode env vars are
+`HASNA_MACHINES_STORAGE_MODE` or `MACHINES_STORAGE_MODE` with `local`,
+`hybrid`, or `remote`.
+
 ## Applications and tooling
 
 ```bash