@hasna/machines 0.0.18 → 0.0.20

package/README.md

@@ -49,13 +49,20 @@ 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. Consumers that only
-need the stable app-to-app contract should import `@hasna/machines/consumer`:
+`@hasna/machines` exposes a compact consumer SDK for other open-core packages
+that need machine identity without importing CLI, MCP, agent, installer, or
+storage-heavy internals. Consumers that only need the stable app-to-app contract
+should import `@hasna/machines/consumer`:
 
 ```ts
-import { discoverMachineTopology, getLocalMachineTopology, resolveMachineRoute } from "@hasna/machines/consumer";
-
+import {
+  MACHINES_CONSUMER_CONTRACT,
+  discoverMachineTopology,
+  getLocalMachineTopology,
+  resolveMachineRoute,
+} from "@hasna/machines/consumer";
+
+console.log(MACHINES_CONSUMER_CONTRACT.schema_version);
 const topology = discoverMachineTopology();
 const local = getLocalMachineTopology();
 const route = resolveMachineRoute("spark01");
@@ -67,9 +74,11 @@ The SDK merges manifest entries, local heartbeats, SSH route hints, and
 when present, and fall back to local probes or app-local machine registries when
 it is absent.
 
-Topology, route, and compatibility JSON include `schema_version`, package
-version metadata, and capability flags. The current consumer contract version is
-`1`.
+Topology, route, workspace, and compatibility JSON include `schema_version`,
+package version metadata, and capability flags. The current consumer contract
+version is `1`; the exported `MACHINES_CONSUMER_CONTRACT` records the stable
+entrypoint, envelope names, and stable exports used by downstream apps such as
+`@hasna/knowledge`.
 
 CLI and MCP expose the same topology view:
 
@@ -79,6 +88,31 @@ machines topology --no-tailscale --json
 machines route --machine spark01 --json
 ```
 
+Consumers that need repo paths can resolve trust-aware workspace mappings
+without importing the full machines app:
+
+```ts
+import { resolveMachineWorkspace } from "@hasna/machines/consumer";
+
+const workspace = resolveMachineWorkspace({
+  machineId: "spark01",
+  projectId: "open-knowledge",
+  repoName: "open-knowledge",
+});
+
+console.log(workspace.paths.project_root.path);
+console.log(workspace.paths.open_files_root.path);
+```
+
+The resolver returns the machine workspace root, project repo root,
+open-files root, current/primary flags, trust/auth status, and redacted
+diagnostics. It uses explicit manifest metadata first and deterministic
+workspace inference second; consumers can still pass manual overrides.
+
+```bash
+machines workspace resolve --machine spark01 --project open-knowledge --repo open-knowledge --json
+```
+
 ## Compatibility SDK
 
 Open-core consumers can use `@hasna/machines` to preflight a peer before
@@ -131,6 +165,20 @@ Configure database storage with `HASNA_MACHINES_DATABASE_URL` or fallback
 `HASNA_MACHINES_STORAGE_MODE` or `MACHINES_STORAGE_MODE` with `local`,
 `hybrid`, or `remote`.
 
+Machine backups are preview-only unless `--apply --yes` is passed. The backup
+target can be explicit or environment-backed:
+
+```bash
+machines backup --bucket fleet-backups --prefix machines --json
+HASNA_MACHINES_S3_BUCKET=hasna-xyz-opensource-machines-prod machines backup --json
+```
+
+`--bucket` and `--prefix` always win. Without `--bucket`, the backup command
+uses `HASNA_MACHINES_S3_BUCKET` or fallback `MACHINES_S3_BUCKET`; prefix uses
+`HASNA_MACHINES_S3_PREFIX`, fallback `MACHINES_S3_PREFIX`, or `machines`.
+This keeps the open-source CLI local/self-hosted by default while allowing
+Hasna deployments to route app-owned backups through canonical storage metadata.
+
 ## Applications and tooling
 
 ```bash

package/dist/cli/index.js

@@ -2286,7 +2286,7 @@ class PgAdapterAsync {
 var init_remote_storage = () => {};
 
 // src/storage-sync.ts
-function readEnv(name) {
+function readEnv2(name) {
   const value = process.env[name]?.trim();
   return value || undefined;
 }
@@ -2298,7 +2298,7 @@ function normalizeStorageMode(value) {
 }
 function getStorageDatabaseEnvName() {
   for (const name of STORAGE_DATABASE_ENV) {
-    if (readEnv(name))
+    if (readEnv2(name))
       return name;
   }
   return null;
@@ -2309,10 +2309,10 @@ function getStorageDatabaseEnv() {
 }
 function getStorageDatabaseUrl() {
   const env2 = getStorageDatabaseEnv();
-  return env2 ? readEnv(env2.name) ?? null : null;
+  return env2 ? readEnv2(env2.name) ?? null : null;
 }
 function getStorageMode() {
-  const mode = normalizeStorageMode(readEnv(MACHINES_STORAGE_MODE_ENV)) ?? normalizeStorageMode(readEnv(MACHINES_STORAGE_MODE_FALLBACK_ENV));
+  const mode = normalizeStorageMode(readEnv2(MACHINES_STORAGE_MODE_ENV)) ?? normalizeStorageMode(readEnv2(MACHINES_STORAGE_MODE_FALLBACK_ENV));
   if (mode)
     return mode;
   return getStorageDatabaseUrl() ? "hybrid" : "local";
@@ -7113,6 +7113,7 @@ var machineSchema = exports_external.object({
   workspacePath: exports_external.string(),
   bunPath: exports_external.string().optional(),
   tags: exports_external.array(exports_external.string()).optional(),
+  metadata: exports_external.record(exports_external.unknown()).optional(),
   packages: exports_external.array(packageSchema).optional(),
   apps: exports_external.array(appSchema).optional(),
   files: exports_external.array(fileSchema).optional()
@@ -7344,9 +7345,52 @@ function runSetup(machineId, options = {}) {
 // src/commands/backup.ts
 import { homedir as homedir2 } from "os";
 import { join as join3 } from "path";
+var MACHINES_BACKUP_BUCKET_ENV = "HASNA_MACHINES_S3_BUCKET";
+var MACHINES_BACKUP_BUCKET_FALLBACK_ENV = "MACHINES_S3_BUCKET";
+var MACHINES_BACKUP_PREFIX_ENV = "HASNA_MACHINES_S3_PREFIX";
+var MACHINES_BACKUP_PREFIX_FALLBACK_ENV = "MACHINES_S3_PREFIX";
+var DEFAULT_BACKUP_PREFIX = "machines";
 function quote2(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
+function readEnv(name) {
+  const value = process.env[name]?.trim();
+  return value || undefined;
+}
+function readBackupBucketEnv() {
+  const primary = readEnv(MACHINES_BACKUP_BUCKET_ENV);
+  if (primary)
+    return { bucket: primary, bucketSource: MACHINES_BACKUP_BUCKET_ENV };
+  const fallback = readEnv(MACHINES_BACKUP_BUCKET_FALLBACK_ENV);
+  if (fallback)
+    return { bucket: fallback, bucketSource: MACHINES_BACKUP_BUCKET_FALLBACK_ENV };
+  return null;
+}
+function readBackupPrefixEnv() {
+  const primary = readEnv(MACHINES_BACKUP_PREFIX_ENV);
+  if (primary)
+    return { prefix: primary, prefixSource: MACHINES_BACKUP_PREFIX_ENV };
+  const fallback = readEnv(MACHINES_BACKUP_PREFIX_FALLBACK_ENV);
+  if (fallback)
+    return { prefix: fallback, prefixSource: MACHINES_BACKUP_PREFIX_FALLBACK_ENV };
+  return null;
+}
+function resolveBackupTarget(options = {}) {
+  const explicitBucket = options.bucket?.trim();
+  const envBucket = explicitBucket ? null : readBackupBucketEnv();
+  const bucket = explicitBucket || envBucket?.bucket;
+  if (!bucket) {
+    throw new Error(`Missing S3 backup bucket. Pass --bucket or set ${MACHINES_BACKUP_BUCKET_ENV} or ${MACHINES_BACKUP_BUCKET_FALLBACK_ENV}.`);
+  }
+  const explicitPrefix = options.prefix?.trim();
+  const envPrefix = explicitPrefix ? null : readBackupPrefixEnv();
+  return {
+    bucket,
+    prefix: explicitPrefix || envPrefix?.prefix || DEFAULT_BACKUP_PREFIX,
+    bucketSource: explicitBucket ? "argument" : envBucket.bucketSource,
+    prefixSource: explicitPrefix ? "argument" : envPrefix?.prefixSource || "default"
+  };
+}
 function defaultBackupSources() {
   const home = homedir2();
   return [
@@ -7355,7 +7399,8 @@ function defaultBackupSources() {
     join3(home, ".secrets")
   ];
 }
-function buildBackupPlan(bucket, prefix = "machines") {
+function buildBackupPlan(bucket, prefix) {
+  const target = resolveBackupTarget({ bucket, prefix });
   const archivePath = join3(homedir2(), ".hasna", "machines", "backup.tgz");
   const sources = defaultBackupSources();
   const steps = [
@@ -7368,7 +7413,7 @@ function buildBackupPlan(bucket, prefix = "machines") {
     {
       id: "backup-upload",
       title: "Upload archive to S3",
-      command: `aws s3 cp ${quote2(archivePath)} s3://${bucket}/${prefix}/$(hostname)-backup.tgz`,
+      command: `aws s3 cp ${quote2(archivePath)} s3://${target.bucket}/${target.prefix}/$(hostname)-backup.tgz`,
       manager: "custom"
     }
   ];
@@ -7379,7 +7424,7 @@ function buildBackupPlan(bucket, prefix = "machines") {
     executed: 0
   };
 }
-function runBackup(bucket, prefix = "machines", options = {}) {
+function runBackup(bucket, prefix, options = {}) {
   const plan = buildBackupPlan(bucket, prefix);
   if (!options.apply)
     return plan;
@@ -7583,6 +7628,16 @@ import { spawnSync } from "child_process";
 init_paths();
 var MACHINES_CONSUMER_CONTRACT_VERSION = 1;
 var MACHINES_PACKAGE_NAME = "@hasna/machines";
+var MACHINES_CONSUMER_CAPABILITIES = {
+  topology: true,
+  compatibility: true,
+  route_resolution: true,
+  cli_json_fallback: true,
+  workspace_path_mapping: true
+};
+function getMachinesConsumerCapabilities() {
+  return { ...MACHINES_CONSUMER_CAPABILITIES };
+}
 function normalizePlatform2(value = platform3()) {
   const normalized = value.toLowerCase();
   if (normalized === "darwin" || normalized === "macos")
@@ -7783,12 +7838,7 @@ function discoverMachineTopology(options = {}) {
       name: MACHINES_PACKAGE_NAME,
       version: getPackageVersion()
     },
-    capabilities: {
-      topology: true,
-      compatibility: true,
-      route_resolution: true,
-      cli_json_fallback: true
-    },
+    capabilities: getMachinesConsumerCapabilities(),
     generated_at: now.toISOString(),
     local_machine_id: localMachineId,
     local_hostname: hostname3(),
@@ -7912,6 +7962,215 @@ function resolveMachineRoute(machineId, options = {}) {
     warnings
   };
 }
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function metadataString(metadata, keys) {
+  for (const key of keys) {
+    const value = metadata[key];
+    if (typeof value === "string" && value.trim())
+      return value.trim();
+  }
+  return null;
+}
+function metadataBoolean(metadata, keys) {
+  for (const key of keys) {
+    const value = metadata[key];
+    if (typeof value === "boolean")
+      return value;
+  }
+  return null;
+}
+function metadataStringArray(metadata, keys) {
+  for (const key of keys) {
+    const value = metadata[key];
+    if (Array.isArray(value))
+      return value.filter((entry) => typeof entry === "string");
+  }
+  return [];
+}
+function readMappedPath(input) {
+  for (const containerName of input.containers) {
+    const container = input.metadata[containerName];
+    if (!isRecord(container))
+      continue;
+    for (const key of input.keys) {
+      const value = container[key];
+      if (typeof value === "string" && value.trim())
+        return value.trim();
+      if (isRecord(value)) {
+        const path = metadataString(value, ["path", "root", "workspacePath", "workspace_path"]);
+        if (path)
+          return path;
+      }
+    }
+  }
+  return null;
+}
+function trimTrailingSlash(value) {
+  return value.replace(/\/+$/, "");
+}
+function joinPath(left, right) {
+  return `${trimTrailingSlash(left)}/${right.replace(/^\/+/, "")}`;
+}
+function inferRepoRoot(workspaceRoot, repoName) {
+  if (!workspaceRoot || !repoName)
+    return null;
+  const root = trimTrailingSlash(workspaceRoot);
+  if (root.endsWith(`/${repoName}`) || root === repoName)
+    return root;
+  if (root.endsWith("/workspace") || root.endsWith("/Workspace")) {
+    return joinPath(root, `hasna/opensource/${repoName}`);
+  }
+  return joinPath(root, repoName);
+}
+function projectPathFromMetadata(metadata, projectId, repoName) {
+  const keys = [projectId, repoName].filter((value) => Boolean(value));
+  return readMappedPath({
+    metadata,
+    containers: ["workspace_paths", "workspacePaths", "repo_paths", "repoPaths", "project_paths", "projectPaths", "projects"],
+    keys
+  });
+}
+function openFilesPathFromMetadata(metadata, projectId, repoName) {
+  const direct = metadataString(metadata, ["open_files_root", "openFilesRoot", "open_files_path", "openFilesPath"]);
+  if (direct)
+    return direct;
+  const keys = [projectId, repoName, "open-files", "open_files", "default"].filter((value) => Boolean(value));
+  return readMappedPath({
+    metadata,
+    containers: ["open_files_roots", "openFilesRoots", "open_files_paths", "openFilesPaths"],
+    keys
+  });
+}
+function trustStatus(machine) {
+  if (!machine)
+    return "unknown";
+  const explicit = metadataString(machine.metadata, ["trust_status", "trustStatus"]);
+  if (explicit === "trusted" || explicit === "untrusted" || explicit === "unknown")
+    return explicit;
+  const trusted = metadataBoolean(machine.metadata, ["trusted", "syncTrusted", "sync_trusted"]);
+  if (trusted === true)
+    return "trusted";
+  if (trusted === false)
+    return "untrusted";
+  if (machine.route_hints.some((hint) => hint.kind === "local"))
+    return "trusted";
+  if (machine.tags.includes("trusted"))
+    return "trusted";
+  return "unknown";
+}
+function authStatus(machine) {
+  if (!machine)
+    return "unknown";
+  const explicit = metadataString(machine.metadata, ["auth_status", "authStatus"]);
+  if (explicit === "authenticated" || explicit === "unauthenticated" || explicit === "unknown")
+    return explicit;
+  const authenticated = metadataBoolean(machine.metadata, ["authenticated", "sshAuthorized", "ssh_authorized"]);
+  if (authenticated === true)
+    return "authenticated";
+  if (authenticated === false)
+    return "unauthenticated";
+  if (machine.route_hints.some((hint) => hint.kind === "local"))
+    return "authenticated";
+  return "unknown";
+}
+function primaryMachine(machine, projectId, primaryMachineId) {
+  if (!machine)
+    return false;
+  if (primaryMachineId)
+    return machine.machine_id === primaryMachineId;
+  if (metadataBoolean(machine.metadata, ["primary", "primary_machine", "primaryMachine"]) === true)
+    return true;
+  const primaryProjects = metadataStringArray(machine.metadata, ["primary_projects", "primaryProjects"]);
+  if (primaryProjects.includes(projectId))
+    return true;
+  return machine.tags.includes("primary");
+}
+function metadataKeysForDiagnostics(metadata) {
+  return Object.keys(metadata).filter((key) => !/(secret|token|key|password|credential)/i.test(key)).sort();
+}
+function resolveMachineWorkspace(options) {
+  const topology = options.topology ?? discoverMachineTopology(options);
+  const warnings = [...topology.warnings];
+  const { machine, matchedBy } = findRouteMachine(topology, options.machineId);
+  const generatedAt = (options.now ?? new Date).toISOString();
+  const repoName = options.repoName ?? options.projectId;
+  const openFilesRepoName = options.openFilesRepoName ?? "open-files";
+  if (!machine) {
+    warnings.push(`machine_not_found:${options.machineId}`);
+    return {
+      schema_version: MACHINES_CONSUMER_CONTRACT_VERSION,
+      package: topology.package,
+      ok: false,
+      requested_machine_id: options.machineId,
+      machine_id: null,
+      generated_at: generatedAt,
+      project: { project_id: options.projectId, repo_name: repoName, canonical: Boolean(options.projectId) },
+      machine: { current: false, primary: false, trust_status: "unknown", auth_status: "unknown" },
+      paths: {
+        workspace_root: { path: null, source: "unresolved" },
+        project_root: { path: null, source: "unresolved" },
+        open_files_root: { path: null, source: "unresolved" }
+      },
+      evidence: {
+        topology: true,
+        matched_by: matchedBy,
+        manifest_declared: null,
+        metadata_keys: []
+      },
+      warnings
+    };
+  }
+  const metadata = machine.metadata;
+  const workspaceRootPath = options.workspaceRoot ?? machine.workspace_path;
+  const workspaceRootSource = options.workspaceRoot ? "argument" : machine.workspace_path ? "manifest" : "unresolved";
+  const metadataProjectRoot = projectPathFromMetadata(metadata, options.projectId, repoName);
+  const inferredProjectRoot = inferRepoRoot(workspaceRootPath, repoName);
+  const projectRootPath = options.projectRoot ?? metadataProjectRoot ?? inferredProjectRoot;
+  const projectRootSource = options.projectRoot ? "argument" : metadataProjectRoot ? "manifest_metadata" : inferredProjectRoot ? "inferred" : "unresolved";
+  const metadataOpenFilesRoot = openFilesPathFromMetadata(metadata, options.projectId, openFilesRepoName);
+  const inferredOpenFilesRoot = inferRepoRoot(workspaceRootPath, openFilesRepoName);
+  const openFilesRootPath = options.openFilesRoot ?? metadataOpenFilesRoot ?? inferredOpenFilesRoot;
+  const openFilesRootSource = options.openFilesRoot ? "argument" : metadataOpenFilesRoot ? "manifest_metadata" : inferredOpenFilesRoot ? "inferred" : "unresolved";
+  if (projectRootSource === "inferred")
+    warnings.push(`project_root_inferred:${options.projectId}`);
+  if (openFilesRootSource === "inferred")
+    warnings.push(`open_files_root_inferred:${options.projectId}`);
+  if (!projectRootPath)
+    warnings.push(`project_root_unresolved:${options.projectId}`);
+  return {
+    schema_version: MACHINES_CONSUMER_CONTRACT_VERSION,
+    package: topology.package,
+    ok: Boolean(projectRootPath),
+    requested_machine_id: options.machineId,
+    machine_id: machine.machine_id,
+    generated_at: generatedAt,
+    project: {
+      project_id: options.projectId,
+      repo_name: repoName,
+      canonical: Boolean(options.projectId && repoName)
+    },
+    machine: {
+      current: machine.machine_id === topology.local_machine_id,
+      primary: primaryMachine(machine, options.projectId, options.primaryMachineId),
+      trust_status: trustStatus(machine),
+      auth_status: authStatus(machine)
+    },
+    paths: {
+      workspace_root: { path: workspaceRootPath, source: workspaceRootSource },
+      project_root: { path: projectRootPath, source: projectRootSource },
+      open_files_root: { path: openFilesRootPath, source: openFilesRootSource }
+    },
+    evidence: {
+      topology: true,
+      matched_by: matchedBy,
+      manifest_declared: machine.manifest_declared,
+      metadata_keys: metadataKeysForDiagnostics(metadata)
+    },
+    warnings
+  };
+}
 
 // src/commands/ssh.ts
 function shellQuote(value) {
@@ -9011,12 +9270,7 @@ function checkMachineCompatibility(options = {}) {
       name: MACHINES_PACKAGE_NAME,
       version: getPackageVersion()
     },
-    capabilities: {
-      topology: true,
-      compatibility: true,
-      route_resolution: true,
-      cli_json_fallback: true
-    },
+    capabilities: getMachinesConsumerCapabilities(),
     ok: summary.fail === 0,
     machine_id: machineId,
     source: checks[0]?.source ?? "local",
@@ -10514,6 +10768,22 @@ function renderCompatibilityResult(result) {
   ].join(`
 `);
 }
+function renderWorkspaceResolution(result) {
+  return renderKeyValueTable([
+    ["machine", result.machine_id ?? result.requested_machine_id],
+    ["ok", String(result.ok)],
+    ["project", result.project.project_id],
+    ["repo", result.project.repo_name ?? "unknown"],
+    ["current", String(result.machine.current)],
+    ["primary", String(result.machine.primary)],
+    ["trust", result.machine.trust_status],
+    ["auth", result.machine.auth_status],
+    ["workspace root", `${result.paths.workspace_root.path ?? "unresolved"} (${result.paths.workspace_root.source})`],
+    ["project root", `${result.paths.project_root.path ?? "unresolved"} (${result.paths.project_root.source})`],
+    ["open-files root", `${result.paths.open_files_root.path ?? "unresolved"} (${result.paths.open_files_root.source})`],
+    ["warnings", result.warnings.join(", ") || "none"]
+  ]);
+}
 function renderFleetStatus(status) {
   return [
     renderKeyValueTable([
@@ -10664,11 +10934,28 @@ program2.command("compatibility").description("Check remote package, command, an
   if (!result.ok && !options.json)
     process.exitCode = 1;
 });
+var workspaceCommand = program2.command("workspace").description("Resolve sync-safe workspace paths for open-* consumers");
+workspaceCommand.command("resolve").description("Resolve repo and open-files roots for a machine/project").requiredOption("--machine <id>", "Machine identifier").requiredOption("--project <id>", "Canonical project id").option("--repo <name>", "Repository name; defaults to project id").option("--open-files-repo <name>", "Open-files repository name", "open-files").option("--primary-machine <id>", "Primary machine id for the project").option("--workspace-root <path>", "Override the machine workspace root").option("--project-root <path>", "Override the resolved project root").option("--open-files-root <path>", "Override the resolved open-files root").option("--no-tailscale", "Skip tailscale status probing").option("-j, --json", "Print JSON output", false).action((options) => {
+  const result = resolveMachineWorkspace({
+    machineId: options.machine,
+    projectId: options.project,
+    repoName: options.repo,
+    openFilesRepoName: options.openFilesRepo,
+    primaryMachineId: options.primaryMachine,
+    workspaceRoot: options.workspaceRoot,
+    projectRoot: options.projectRoot,
+    openFilesRoot: options.openFilesRoot,
+    includeTailscale: options.tailscale !== false
+  });
+  printJsonOrText(result, renderWorkspaceResolution(result), options.json);
+  if (!result.ok && !options.json)
+    process.exitCode = 1;
+});
 program2.command("diff").description("Show manifest differences between two machines").requiredOption("--left <id>", "Left machine identifier").option("--right <id>", "Right machine identifier (defaults to current machine)").option("-j, --json", "Print JSON output", false).action((options) => {
   const result = diffMachines(options.left, options.right);
   console.log(JSON.stringify(result, null, 2));
 });
-program2.command("backup").description("Create and optionally upload a machine backup archive").requiredOption("--bucket <name>", "S3 bucket name").option("--prefix <prefix>", "S3 key prefix", "machines").option("--apply", "Execute backup commands instead of previewing the plan", false).option("--yes", "Confirm execution when using --apply", false).option("-j, --json", "Print JSON output", false).action((options) => {
+program2.command("backup").description("Create and optionally upload a machine backup archive").option("--bucket <name>", "S3 bucket name; defaults to HASNA_MACHINES_S3_BUCKET or MACHINES_S3_BUCKET").option("--prefix <prefix>", "S3 key prefix; defaults to HASNA_MACHINES_S3_PREFIX, MACHINES_S3_PREFIX, or machines").option("--apply", "Execute backup commands instead of previewing the plan", false).option("--yes", "Confirm execution when using --apply", false).option("-j, --json", "Print JSON output", false).action((options) => {
   const result = options.apply ? runBackup(options.bucket, options.prefix, { apply: true, yes: options.yes }) : buildBackupPlan(options.bucket, options.prefix);
   console.log(JSON.stringify(result, null, 2));
 });

package/dist/commands/backup.d.ts

@@ -1,6 +1,21 @@
 import type { SetupResult } from "../types.js";
-export declare function buildBackupPlan(bucket: string, prefix?: string): SetupResult;
-export declare function runBackup(bucket: string, prefix?: string, options?: {
+export declare const MACHINES_BACKUP_BUCKET_ENV = "HASNA_MACHINES_S3_BUCKET";
+export declare const MACHINES_BACKUP_BUCKET_FALLBACK_ENV = "MACHINES_S3_BUCKET";
+export declare const MACHINES_BACKUP_PREFIX_ENV = "HASNA_MACHINES_S3_PREFIX";
+export declare const MACHINES_BACKUP_PREFIX_FALLBACK_ENV = "MACHINES_S3_PREFIX";
+export declare const DEFAULT_BACKUP_PREFIX = "machines";
+export interface BackupTarget {
+    bucket: string;
+    prefix: string;
+    bucketSource: "argument" | typeof MACHINES_BACKUP_BUCKET_ENV | typeof MACHINES_BACKUP_BUCKET_FALLBACK_ENV;
+    prefixSource: "argument" | typeof MACHINES_BACKUP_PREFIX_ENV | typeof MACHINES_BACKUP_PREFIX_FALLBACK_ENV | "default";
+}
+export declare function resolveBackupTarget(options?: {
+    bucket?: string;
+    prefix?: string;
+}): BackupTarget;
+export declare function buildBackupPlan(bucket?: string, prefix?: string): SetupResult;
+export declare function runBackup(bucket?: string, prefix?: string, options?: {
     apply?: boolean;
     yes?: boolean;
 }): SetupResult;

package/dist/commands/backup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backup.d.ts","sourceRoot":"","sources":["../../src/commands/backup.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAa,MAAM,aAAa,CAAC;AAe1D,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,SAAa,GAAG,WAAW,CAwBhF;AAED,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,SAAa,EAAE,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,WAAW,CA0B5H"}
+{"version":3,"file":"backup.d.ts","sourceRoot":"","sources":["../../src/commands/backup.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAa,MAAM,aAAa,CAAC;AAE1D,eAAO,MAAM,0BAA0B,6BAA6B,CAAC;AACrE,eAAO,MAAM,mCAAmC,uBAAuB,CAAC;AACxE,eAAO,MAAM,0BAA0B,6BAA6B,CAAC;AACrE,eAAO,MAAM,mCAAmC,uBAAuB,CAAC;AACxE,eAAO,MAAM,qBAAqB,aAAa,CAAC;AAEhD,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,UAAU,GAAG,OAAO,0BAA0B,GAAG,OAAO,mCAAmC,CAAC;IAC1G,YAAY,EAAE,UAAU,GAAG,OAAO,0BAA0B,GAAG,OAAO,mCAAmC,GAAG,SAAS,CAAC;CACvH;AA2BD,wBAAgB,mBAAmB,CAAC,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,YAAY,CAoBpG;AAWD,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,WAAW,CAyB7E;AAED,wBAAgB,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,WAAW,CA0BzH"}

package/dist/compatibility.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compatibility.d.ts","sourceRoot":"","sources":["../src/compatibility.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,KAAK,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAC3E,OAAO,EAAE,kCAAkC,EAAyB,KAAK,uBAAuB,EAAE,KAAK,4BAA4B,EAAE,MAAM,eAAe,CAAC;AAG3J,MAAM,MAAM,mBAAmB,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AACzD,MAAM,MAAM,mBAAmB,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAAC;AAEjE,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;IAC1C,MAAM,EAAE,mBAAmB,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,mBAAmB,CAAC;CAC7B;AAED,MAAM,WAAW,0BAA0B;IACzC,cAAc,EAAE,OAAO,kCAAkC,CAAC;IAC1D,OAAO,EAAE,uBAAuB,CAAC;IACjC,YAAY,EAAE,4BAA4B,CAAC;IAC3C,EAAE,EAAE,OAAO,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,mBAAmB,CAAC;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC7B,OAAO,EAAE;QACP,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;CACH;AAED,MAAM,MAAM,0BAA0B,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,oBAAoB,CAAC;AAEtG,MAAM,WAAW,2BAA2B;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,wBAAwB,EAAE,CAAC;IACtC,QAAQ,CAAC,EAAE,wBAAwB,EAAE,CAAC;IACtC,UAAU,CAAC,EAAE,0BAA0B,EAAE,CAAC;IAC1C,MAAM,CAAC,EAAE,0BAA0B,CAAC;IACpC,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAiQD,wBAAgB,yBAAyB,CAAC,OAAO,GAAE,2BAAgC,GAAG,0BAA0B,CAqC/G"}
+{"version":3,"file":"compatibility.d.ts","sourceRoot":"","sources":["../src/compatibility.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,KAAK,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAC3E,OAAO,EAAE,kCAAkC,EAA0D,KAAK,uBAAuB,EAAE,KAAK,4BAA4B,EAAE,MAAM,eAAe,CAAC;AAG5L,MAAM,MAAM,mBAAmB,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AACzD,MAAM,MAAM,mBAAmB,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAAC;AAEjE,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;IAC1C,MAAM,EAAE,mBAAmB,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,mBAAmB,CAAC;CAC7B;AAED,MAAM,WAAW,0BAA0B;IACzC,cAAc,EAAE,OAAO,kCAAkC,CAAC;IAC1D,OAAO,EAAE,uBAAuB,CAAC;IACjC,YAAY,EAAE,4BAA4B,CAAC;IAC3C,EAAE,EAAE,OAAO,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,mBAAmB,CAAC;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC7B,OAAO,EAAE;QACP,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;CACH;AAED,MAAM,MAAM,0BAA0B,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,oBAAoB,CAAC;AAEtG,MAAM,WAAW,2BAA2B;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,wBAAwB,EAAE,CAAC;IACtC,QAAQ,CAAC,EAAE,wBAAwB,EAAE,CAAC;IACtC,UAAU,CAAC,EAAE,0BAA0B,EAAE,CAAC;IAC1C,MAAM,CAAC,EAAE,0BAA0B,CAAC;IACpC,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAiQD,wBAAgB,yBAAyB,CAAC,OAAO,GAAE,2BAAgC,GAAG,0BAA0B,CAgC/G"}

package/dist/consumer.d.ts

@@ -1,5 +1,5 @@
-export { MACHINES_CONSUMER_CONTRACT_VERSION, MACHINES_PACKAGE_NAME, discoverMachineTopology, getLocalMachineTopology, resolveMachineRoute, } from "./topology.js";
-export type { MachineRouteConfidence, MachineRouteHint, MachineRouteKind, MachineRouteOptions, MachineRouteResolution, MachineTopology, MachineTopologyEntry, MachineTopologyOptions, MachinesConsumerCapabilities, MachinesContractPackage, TopologyCommandResult, TopologyCommandRunner, } from "./topology.js";
+export { MACHINES_CONSUMER_CAPABILITIES, MACHINES_CONSUMER_CONTRACT, MACHINES_CONSUMER_ENTRYPOINT, MACHINES_CONSUMER_CONTRACT_VERSION, MACHINES_PACKAGE_NAME, discoverMachineTopology, getMachinesConsumerCapabilities, getLocalMachineTopology, resolveMachineRoute, resolveMachineWorkspace, } from "./topology.js";
+export type { MachineRouteConfidence, MachineRouteHint, MachineRouteKind, MachineRouteOptions, MachineRouteResolution, MachineTopology, MachineTopologyEntry, MachineTopologyOptions, MachineWorkspaceAuthStatus, MachineWorkspaceOptions, MachineWorkspacePath, MachineWorkspacePathSource, MachineWorkspaceProject, MachineWorkspaceResolution, MachineWorkspaceTrustStatus, MachinesConsumerContract, MachinesConsumerEnvelope, MachinesConsumerCapabilities, MachinesContractPackage, TopologyCommandResult, TopologyCommandRunner, } from "./topology.js";
 export { checkMachineCompatibility, } from "./compatibility.js";
 export type { CompatibilityCheck, CompatibilityCommandRunner, CompatibilityCommandSpec, CompatibilityPackageSpec, CompatibilitySource, CompatibilityStatus, CompatibilityWorkspaceSpec, MachineCompatibilityOptions, MachineCompatibilityReport, } from "./compatibility.js";
 export { resolveMachineCommand, runMachineCommand, } from "./remote.js";

package/dist/consumer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"consumer.d.ts","sourceRoot":"","sources":["../src/consumer.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kCAAkC,EAClC,qBAAqB,EACrB,uBAAuB,EACvB,uBAAuB,EACvB,mBAAmB,GACpB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,sBAAsB,EACtB,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACnB,sBAAsB,EACtB,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACtB,4BAA4B,EAC5B,uBAAuB,EACvB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,yBAAyB,GAC1B,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,kBAAkB,EAClB,0BAA0B,EAC1B,wBAAwB,EACxB,wBAAwB,EACxB,mBAAmB,EACnB,mBAAmB,EACnB,0BAA0B,EAC1B,2BAA2B,EAC3B,0BAA0B,GAC3B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,oBAAoB,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,eAAe,EACf,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,iBAAiB,GAClB,MAAM,cAAc,CAAC"}
+{"version":3,"file":"consumer.d.ts","sourceRoot":"","sources":["../src/consumer.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,8BAA8B,EAC9B,0BAA0B,EAC1B,4BAA4B,EAC5B,kCAAkC,EAClC,qBAAqB,EACrB,uBAAuB,EACvB,+BAA+B,EAC/B,uBAAuB,EACvB,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,sBAAsB,EACtB,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACnB,sBAAsB,EACtB,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACtB,0BAA0B,EAC1B,uBAAuB,EACvB,oBAAoB,EACpB,0BAA0B,EAC1B,uBAAuB,EACvB,0BAA0B,EAC1B,2BAA2B,EAC3B,wBAAwB,EACxB,wBAAwB,EACxB,4BAA4B,EAC5B,uBAAuB,EACvB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,yBAAyB,GAC1B,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,kBAAkB,EAClB,0BAA0B,EAC1B,wBAAwB,EACxB,wBAAwB,EACxB,mBAAmB,EACnB,mBAAmB,EACnB,0BAA0B,EAC1B,2BAA2B,EAC3B,0BAA0B,GAC3B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,oBAAoB,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,eAAe,EACf,gBAAgB,GACjB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,iBAAiB,GAClB,MAAM,cAAc,CAAC"}