@hasna/machines 0.0.34 → 0.0.36

package/README.md

@@ -36,9 +36,18 @@ machines manifest validate
 machines manifest list
 ```
 
+Public packages should keep private fleet state behind an opaque source/ref
+boundary. `HASNA_MACHINES_PRIVATE_MANIFEST_REF` (or
+`MACHINES_PRIVATE_MANIFEST_REF`) may point at a private backend, but
+open-machines only reports the redacted ref and falls back to the local
+`machines.json` unless a caller supplies a manifest adapter. The adapter
+contract is backend-agnostic and lives in the package root exports; it does not
+pull in secrets managers, storage SDKs, or org-specific fleet internals.
+
 ## Provision and reconcile
 
 ```bash
+machines setup --machine linux-dev-01
 machines setup --machine linux-dev-01 --json
 machines setup --machine linux-dev-01 --apply --yes
 machines sync --machine linux-dev-01 --json
@@ -47,6 +56,25 @@ machines doctor --machine linux-dev-01
 machines self-test
 ```
 
+`machines setup` is a dry-run plan by default. The generated playbook favors
+idempotent operations (`mkdir -p`, command-existence guards, package-manager
+installs) and only executes when both `--apply` and `--yes` are provided.
+The default plan also adds update-check/download settings without enabling
+automatic OS installation: Linux uses apt periodic download-only settings, and
+macOS uses `softwareupdate`/`defaults` with `AutomaticallyInstallMacOSUpdates`
+left disabled.
+`doctor --json` includes public-safe source/ref diagnostics plus optional
+adapter hook results for secrets, configs, monitors, repos, MCPs, and shield
+checks. When no adapter is configured, those checks report a skipped fallback
+instead of importing private dependencies.
+It also reports noninteractive sudo readiness, SSH certificate support, and
+GitHub App secret-reference readiness without printing credentials or private
+keys.
+
+Apple device management belongs in the private deployment layer. The public
+setup plan can report enrollment status with `profiles status -type enrollment`,
+but it does not enroll devices, install profiles, or publish team identifiers.
+
 ## Topology SDK
 
 `@hasna/machines` exposes a compact consumer SDK for other open-core packages
@@ -151,6 +179,11 @@ machines defaults to
 `machines/screen-sharing/screen-<machine>-vnc-password`, or the namespace set in
 `HASNA_MACHINES_SCREEN_SECRET_NAMESPACE`. The user comes from the manifest
 (`metadata.user`) when present, or `--user`.
+
+For GitHub automation, prefer GitHub App installation tokens over personal user
+tokens. Public manifests and docs should store only opaque secret references
+for the app id/private key material; private adapters or `open-secrets` should
+resolve those references at runtime.
 `screen-credentials` verifies the resolved user and secret key for a machine or
 the full fleet without printing secret values.
 

package/dist/cli/index.js

@@ -7092,6 +7092,104 @@ var coerce = {
 var NEVER = INVALID;
 // src/manifests.ts
 init_paths();
+
+// src/redaction.ts
+var REDACTED_VALUE = "[redacted]";
+var SENSITIVE_KEY_PATTERN = /(password|passwd|token|credential|private[_-]?key|privateKey|api[_-]?key|github.*key|pem|secret)/i;
+var SECRET_REFERENCE_KEY_PATTERN = /(secret(ref(erence)?|key)?|secretRef|secretKey)$/i;
+var SENSITIVE_VALUE_PATTERNS = [
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----/,
+  /\bghp_[A-Za-z0-9_]{20,}\b/,
+  /\bgithub_pat_[A-Za-z0-9_]{20,}\b/,
+  /\bxox[baprs]-[A-Za-z0-9-]{20,}\b/,
+  /\bAKIA[0-9A-Z]{16}\b/,
+  /\bsk-[A-Za-z0-9_-]{20,}\b/
+];
+function isSensitiveKey(key) {
+  return SENSITIVE_KEY_PATTERN.test(key);
+}
+function isSecretReferenceKey(key) {
+  return SECRET_REFERENCE_KEY_PATTERN.test(key);
+}
+function looksSensitiveString(value) {
+  return SENSITIVE_VALUE_PATTERNS.some((pattern) => pattern.test(value));
+}
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function redactPath(value) {
+  return value.replace(/\/home\/[^/\s]+/g, "/home/<user>").replace(/\/Users\/[^/\s]+/g, "/Users/<user>").replace(/[A-Za-z]:\\Users\\[^\\\s]+/g, "C:\\Users\\<user>");
+}
+function redactPrivateRef(value) {
+  const trimmed = value.trim();
+  const scheme = trimmed.match(/^([a-z][a-z0-9+.-]*:\/\/)/i);
+  if (scheme)
+    return `${scheme[1]}<redacted>`;
+  const colon = trimmed.match(/^([a-z][a-z0-9+.-]*):/i);
+  if (colon)
+    return `${colon[1]}:<redacted>`;
+  return "<private-manifest-ref:redacted>";
+}
+function redactIdentifier(value) {
+  return value.replace(/[^a-zA-Z0-9_.-]/g, "_").slice(0, 80) || "adapter";
+}
+function redactSensitiveValue(value, key = "") {
+  if (typeof value === "string") {
+    if (isSensitiveKey(key) && !(isSecretReferenceKey(key) && !looksSensitiveString(value))) {
+      return REDACTED_VALUE;
+    }
+    if (looksSensitiveString(value))
+      return REDACTED_VALUE;
+    return redactPath(value);
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => redactSensitiveValue(entry, key));
+  }
+  if (isRecord(value)) {
+    const redacted = {};
+    for (const [entryKey, entryValue] of Object.entries(value)) {
+      redacted[entryKey] = redactSensitiveValue(entryValue, entryKey);
+    }
+    return redacted;
+  }
+  return value;
+}
+function publicMetadataKeys(metadata) {
+  return Object.keys(metadata ?? {}).filter((key) => !isSensitiveKey(key)).sort();
+}
+function redactMetadata(metadata) {
+  return redactSensitiveValue(metadata ?? {});
+}
+function redactManifestForDiagnostics(machine) {
+  const metadata = redactMetadata(machine.metadata);
+  for (const key of ["user", "username", "login"]) {
+    if (typeof metadata[key] === "string")
+      metadata[key] = REDACTED_VALUE;
+  }
+  return {
+    id: machine.id,
+    hostname: machine.hostname ? REDACTED_VALUE : undefined,
+    sshAddress: machine.sshAddress ? REDACTED_VALUE : undefined,
+    tailscaleName: machine.tailscaleName ? REDACTED_VALUE : undefined,
+    platform: machine.platform,
+    connection: machine.connection,
+    workspacePath: redactPath(machine.workspacePath),
+    bunPath: machine.bunPath ? redactPath(machine.bunPath) : undefined,
+    tags: machine.tags ?? [],
+    metadata,
+    packages: machine.packages?.map((pkg) => ({ ...pkg })),
+    apps: machine.apps?.map((app) => ({ ...app })),
+    files: machine.files?.map((file) => ({
+      ...file,
+      source: redactPath(file.source),
+      target: redactPath(file.target)
+    }))
+  };
+}
+
+// src/manifests.ts
+var PRIVATE_MANIFEST_REF_ENV = "HASNA_MACHINES_PRIVATE_MANIFEST_REF";
+var PRIVATE_MANIFEST_BACKEND_ENV = "HASNA_MACHINES_PRIVATE_MANIFEST_BACKEND";
 var packageSchema = exports_external.object({
   name: exports_external.string(),
   manager: exports_external.enum(["bun", "brew", "apt", "custom"]).optional(),
@@ -7144,6 +7242,42 @@ function normalizePlatform() {
 function normalizeMachines(machines) {
   return [...machines].sort((left, right) => left.id.localeCompare(right.id));
 }
+function inferPrivateBackend(rawRef, explicitBackend) {
+  if (explicitBackend?.trim())
+    return explicitBackend.trim();
+  const scheme = rawRef.trim().match(/^([a-z][a-z0-9+.-]*)(?::\/\/|:)/i);
+  return scheme?.[1] ?? null;
+}
+function fileSourceRef(path) {
+  return {
+    kind: "file",
+    ref: redactPath(path),
+    backend: "file",
+    private: false,
+    publicSafe: true
+  };
+}
+function privateSourceRef(rawRef, backend) {
+  return {
+    kind: "private-ref",
+    ref: redactPrivateRef(rawRef),
+    backend: inferPrivateBackend(rawRef, backend),
+    private: true,
+    publicSafe: true
+  };
+}
+function privateRefFromOptions(options) {
+  const env2 = options.env ?? process.env;
+  return options.privateRef?.trim() || env2[PRIVATE_MANIFEST_REF_ENV]?.trim() || env2["MACHINES_PRIVATE_MANIFEST_REF"]?.trim() || null;
+}
+function getManifestSourceRef(options = {}) {
+  const rawPrivateRef = privateRefFromOptions(options);
+  if (rawPrivateRef) {
+    const env2 = options.env ?? process.env;
+    return privateSourceRef(rawPrivateRef, options.privateBackend ?? env2[PRIVATE_MANIFEST_BACKEND_ENV]);
+  }
+  return fileSourceRef(options.path ?? getManifestPath());
+}
 function getDefaultManifest() {
   return {
     version: 1,
@@ -7158,6 +7292,53 @@ function readManifest(path = getManifestPath()) {
   const raw = JSON.parse(readFileSync2(path, "utf8"));
   return fleetSchema.parse(raw);
 }
+function readManifestWithSource(options = {}) {
+  const path = options.path ?? getManifestPath();
+  const source = getManifestSourceRef(options);
+  const warnings = [];
+  if (source.kind === "private-ref") {
+    const rawRef = privateRefFromOptions(options);
+    if (rawRef && options.adapter) {
+      try {
+        const manifest2 = options.adapter.readManifest({ source, rawRef });
+        if (manifest2) {
+          return {
+            manifest: fleetSchema.parse(manifest2),
+            info: {
+              source,
+              loadedFrom: "private-ref",
+              warnings
+            }
+          };
+        }
+        warnings.push(`private_manifest_adapter_empty:${redactIdentifier(options.adapter.id)}`);
+      } catch (error) {
+        warnings.push(`private_manifest_adapter_failed:${redactIdentifier(options.adapter.id)}`);
+      }
+    } else {
+      warnings.push("private_manifest_ref_without_adapter");
+    }
+    const fallbackSource = fileSourceRef(path);
+    const manifest = readManifest(path);
+    return {
+      manifest,
+      info: {
+        source,
+        loadedFrom: existsSync3(path) ? "fallback" : "default",
+        fallbackSource,
+        warnings
+      }
+    };
+  }
+  return {
+    manifest: readManifest(path),
+    info: {
+      source,
+      loadedFrom: existsSync3(path) ? "file" : "default",
+      warnings
+    }
+  };
+}
 function validateManifest(path = getManifestPath()) {
   return readManifest(path);
 }
@@ -7444,7 +7625,7 @@ function buildEntry(input) {
     },
     route_hints: hints,
     tags: manifest?.tags ?? [],
-    metadata: manifest?.metadata ?? {}
+    metadata: redactMetadata(manifest?.metadata)
   };
 }
 function discoverMachineTopology(options = {}) {
@@ -7682,7 +7863,7 @@ function resolveMachineRoute(machineId, options = {}) {
     warnings
   };
 }
-function isRecord(value) {
+function isRecord2(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function metadataString(metadata, keys) {
@@ -7712,13 +7893,13 @@ function metadataStringArray(metadata, keys) {
 function readMappedPath(input) {
   for (const containerName of input.containers) {
     const container = input.metadata[containerName];
-    if (!isRecord(container))
+    if (!isRecord2(container))
       continue;
     for (const key of input.keys) {
       const value = container[key];
       if (typeof value === "string" && value.trim())
         return value.trim();
-      if (isRecord(value)) {
+      if (isRecord2(value)) {
         const path = metadataString(value, ["path", "root", "workspacePath", "workspace_path"]);
         if (path)
           return path;
@@ -7972,7 +8153,7 @@ function primaryMachine(machine, projectId, primaryMachineId) {
   return machine.tags.includes("primary");
 }
 function metadataKeysForDiagnostics(metadata) {
-  return Object.keys(metadata).filter((key) => !/(secret|token|key|password|credential)/i.test(key)).sort();
+  return publicMetadataKeys(metadata);
 }
 function resolveMachineWorkspace(options) {
   const now = options.now ?? new Date;
@@ -8205,6 +8386,13 @@ function buildBaseSteps(machine) {
       manager: "apt",
       privileged: true
     });
+    steps.push({
+      id: "linux-update-downloads",
+      title: "Enable Linux package list refresh and download-only upgrades",
+      command: `printf '%s\\n' 'APT::Periodic::Update-Package-Lists "1";' 'APT::Periodic::Download-Upgradeable-Packages "1";' 'APT::Periodic::Unattended-Upgrade "0";' | sudo tee /etc/apt/apt.conf.d/20auto-upgrades >/dev/null`,
+      manager: "apt",
+      privileged: true
+    });
   } else if (machine.platform === "macos") {
     steps.push({
       id: "brew-base",
@@ -8218,7 +8406,26 @@ function buildBaseSteps(machine) {
       command: "brew install git coreutils",
       manager: "brew"
     });
+    steps.push({
+      id: "macos-update-downloads",
+      title: "Enable macOS update checks and downloads without automatic install",
+      command: "sudo softwareupdate --schedule on && sudo defaults write /Library/Preferences/com.apple.SoftwareUpdate AutomaticCheckEnabled -bool true && sudo defaults write /Library/Preferences/com.apple.SoftwareUpdate AutomaticDownload -int 1 && sudo defaults write /Library/Preferences/com.apple.SoftwareUpdate AutomaticallyInstallMacOSUpdates -int 0",
+      manager: "custom",
+      privileged: true
+    });
+    steps.push({
+      id: "macos-management-readiness",
+      title: "Report Apple management readiness without enrolling devices",
+      command: "profiles status -type enrollment 2>/dev/null || true",
+      manager: "custom"
+    });
   }
+  steps.push({
+    id: "github-app-auth-readiness",
+    title: "Check GitHub CLI/App auth readiness without printing credentials",
+    command: "command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1 || true",
+    manager: "custom"
+  });
   return steps;
 }
 function buildPackageSteps(machine) {
@@ -9578,20 +9785,20 @@ function getStatus() {
 
 // src/commands/workspace.ts
 init_paths();
-function isRecord2(value) {
+function isRecord3(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
 function cloneMetadata(metadata) {
-  return isRecord2(metadata) ? { ...metadata } : {};
+  return isRecord3(metadata) ? { ...metadata } : {};
 }
 function mappedPath(metadata, field, key) {
   const container = metadata[field];
-  if (!isRecord2(container))
+  if (!isRecord3(container))
     return null;
   const value = container[key];
   if (typeof value === "string" && value.trim())
     return value.trim();
-  if (isRecord2(value)) {
+  if (isRecord3(value)) {
     const nested = value["path"] ?? value["root"] ?? value["workspacePath"] ?? value["workspace_path"];
     if (typeof nested === "string" && nested.trim())
       return nested.trim();
@@ -9600,7 +9807,7 @@ function mappedPath(metadata, field, key) {
 }
 function writeMappedPath(metadata, field, key, path) {
   const existing = metadata[field];
-  const container = isRecord2(existing) ? { ...existing } : {};
+  const container = isRecord3(existing) ? { ...existing } : {};
   container[key] = path;
   metadata[field] = container;
 }
@@ -9970,12 +10177,28 @@ function checkMachineCompatibility(options = {}) {
 
 // src/commands/doctor.ts
 init_db();
-function makeCheck2(id, status, summary, detail) {
-  return { id, status, summary, detail };
+var DOCTOR_OPTIONAL_ADAPTER_DOMAINS = ["secrets", "configs", "monitor", "repos", "mcps", "shield"];
+function makeCheck2(id, status, summary, detail, extra = {}) {
+  const { data, ...rest } = extra;
+  return {
+    ...rest,
+    id,
+    status,
+    summary,
+    detail,
+    data: data ? redactSensitiveValue(data) : undefined
+  };
 }
 function parseKeyValueOutput(stdout) {
-  return Object.fromEntries(stdout.trim().split(`
-`).map((line) => line.split("=")).filter((parts) => parts.length === 2).map(([key, value]) => [key, value]));
+  const result = {};
+  for (const line of stdout.trim().split(`
+`)) {
+    const index = line.indexOf("=");
+    if (index <= 0)
+      continue;
+    result[line.slice(0, index)] = line.slice(index + 1);
+  }
+  return result;
 }
 function buildDoctorCommand() {
   return [
@@ -9983,9 +10206,11 @@ function buildDoctorCommand() {
     'manifest_path="${HASNA_MACHINES_MANIFEST_PATH:-$data_dir/machines.json}"',
     'db_path="${HASNA_MACHINES_DB_PATH:-$data_dir/machines.db}"',
     'notifications_path="${HASNA_MACHINES_NOTIFICATIONS_PATH:-$data_dir/notifications.json}"',
+    `printf 'data_dir=%s\\n' "$data_dir"`,
     `printf 'manifest_path=%s\\n' "$manifest_path"`,
     `printf 'db_path=%s\\n' "$db_path"`,
     `printf 'notifications_path=%s\\n' "$notifications_path"`,
+    `printf 'data_dir_exists=%s\\n' "$(test -d "$data_dir" && printf yes || printf no)"`,
     `printf 'manifest_exists=%s\\n' "$(test -e "$manifest_path" && printf yes || printf no)"`,
     `printf 'db_exists=%s\\n' "$(test -e "$db_path" && printf yes || printf no)"`,
     `printf 'notifications_exists=%s\\n' "$(test -e "$notifications_path" && printf yes || printf no)"`,
@@ -9993,31 +10218,139 @@ function buildDoctorCommand() {
     `printf 'ssh=%s\\n' "$(command -v ssh >/dev/null 2>&1 && printf ok || printf missing)"`,
     `printf 'machines=%s\\n' "$(command -v machines 2>/dev/null || printf missing)"`,
     `printf 'machines_agent=%s\\n' "$(command -v machines-agent 2>/dev/null || printf missing)"`,
-    `printf 'machines_mcp=%s\\n' "$(command -v machines-mcp 2>/dev/null || printf missing)"`
+    `printf 'machines_mcp=%s\\n' "$(command -v machines-mcp 2>/dev/null || printf missing)"`,
+    `printf 'sudo_noninteractive=%s\\n' "$(sudo -n true >/dev/null 2>&1 && printf ok || printf unavailable)"`,
+    `printf 'ssh_cert_support=%s\\n' "$(ssh -Q key-cert 2>/dev/null | grep -q 'ssh-ed25519-cert-v01@openssh.com' && printf ok || printf unavailable)"`,
+    `printf 'gh_cli=%s\\n' "$(command -v gh 2>/dev/null || printf missing)"`,
+    `printf 'gh_auth=%s\\n' "$(gh auth status >/dev/null 2>&1 && printf ok || printf unavailable)"`,
+    "printf 'github_app_ref=%s\\n' \"$(test -n \\\"${HASNA_GITHUB_APP_ID:-}\\\" -a -n \\\"${HASNA_GITHUB_APP_PRIVATE_KEY_REF:-}\\\" && printf configured || printf missing)\""
   ].join("; ");
 }
-function runDoctor(machineId = getLocalMachineId()) {
-  const manifest = readManifest();
+function fallbackAdapterCheck(domain) {
+  return makeCheck2(`${domain}-adapter`, "ok", `Optional ${domain} adapter`, `No ${domain} adapter configured; skipped optional private integration check.`, {
+    optional: true,
+    source: "open-machines",
+    data: { configured: false, fallback: true }
+  });
+}
+function sanitizeAdapterCheck(check, domain, adapterId) {
+  const safeAdapterId = redactIdentifier(adapterId);
+  return makeCheck2(check.id.startsWith(`${domain}-`) || check.id.startsWith(`${domain}:`) ? check.id : `${domain}:${check.id}`, check.status, check.summary, String(redactSensitiveValue(check.detail)), {
+    ...check,
+    optional: check.optional ?? true,
+    source: check.source ? String(redactSensitiveValue(check.source)) : `adapter:${safeAdapterId}`,
+    data: check.data ? redactSensitiveValue(check.data) : undefined
+  });
+}
+function runOptionalAdapterChecks(context, adapters) {
+  const checks = [];
+  for (const domain of DOCTOR_OPTIONAL_ADAPTER_DOMAINS) {
+    const adapter2 = adapters.find((candidate) => candidate.checks?.[domain]);
+    const hook = adapter2?.checks?.[domain];
+    if (!adapter2 || !hook) {
+      checks.push(fallbackAdapterCheck(domain));
+      continue;
+    }
+    try {
+      const result = hook(context);
+      const domainChecks = Array.isArray(result) ? result : result ? [result] : [fallbackAdapterCheck(domain)];
+      checks.push(...domainChecks.map((check) => sanitizeAdapterCheck(check, domain, adapter2.id)));
+    } catch {
+      const safeAdapterId = redactIdentifier(adapter2.id);
+      checks.push(makeCheck2(`${domain}-adapter`, "warn", `Optional ${domain} adapter failed`, "Adapter failed; details are intentionally hidden to avoid leaking private refs or credentials.", {
+        optional: true,
+        source: `adapter:${safeAdapterId}`,
+        data: { adapter: safeAdapterId, fallback: true }
+      }));
+    }
+  }
+  return checks;
+}
+function runDoctor(machineId = getLocalMachineId(), options = {}) {
+  const now = options.now ?? new Date;
+  const { manifest, info: manifestSource } = readManifestWithSource({ adapter: options.manifestAdapter ?? null });
   const commandChecks = runMachineCommand(machineId, buildDoctorCommand());
   const details = parseKeyValueOutput(commandChecks.stdout);
   const machineInManifest = manifest.machines.find((machine) => machine.id === machineId);
+  const optionalAdapterChecks = options.includeOptionalAdapters === false ? [] : runOptionalAdapterChecks({
+    machineId,
+    manifest,
+    manifestSource,
+    commandDetails: details,
+    now
+  }, options.adapters ?? []);
   const checks = [
-    makeCheck2("manifest-entry", machineInManifest ? "ok" : "warn", machineInManifest ? "Machine exists in manifest" : "Machine missing from manifest", machineInManifest ? JSON.stringify(machineInManifest) : `No manifest entry for ${machineId}`),
-    makeCheck2("manifest-path", details["manifest_exists"] === "yes" ? "ok" : "warn", "Manifest path check", `${details["manifest_path"] || "unknown"} ${details["manifest_exists"] === "yes" ? "exists" : "missing"}`),
-    makeCheck2("db-path", details["db_exists"] === "yes" ? "ok" : "warn", "DB path check", `${details["db_path"] || "unknown"} ${details["db_exists"] === "yes" ? "exists" : "missing"}`),
-    makeCheck2("notifications-path", details["notifications_exists"] === "yes" ? "ok" : "warn", "Notifications path check", `${details["notifications_path"] || "unknown"} ${details["notifications_exists"] === "yes" ? "exists" : "missing"}`),
+    makeCheck2("manifest-source", manifestSource.warnings.length > 0 ? "warn" : "ok", "Manifest source boundary", `${manifestSource.source.kind}:${manifestSource.source.ref} loaded from ${manifestSource.loadedFrom}`, {
+      data: {
+        source: manifestSource.source,
+        loadedFrom: manifestSource.loadedFrom,
+        fallbackSource: manifestSource.fallbackSource,
+        warnings: manifestSource.warnings
+      },
+      remediation: manifestSource.warnings.length > 0 ? ["Provide a private manifest adapter or unset the private manifest ref to use the local manifest only."] : undefined
+    }),
+    makeCheck2("manifest-entry", machineInManifest ? "ok" : "warn", machineInManifest ? "Machine exists in manifest" : "Machine missing from manifest", machineInManifest ? JSON.stringify(redactManifestForDiagnostics(machineInManifest)) : `No manifest entry for ${machineId}`, {
+      data: {
+        declared: Boolean(machineInManifest),
+        machine: machineInManifest ? redactManifestForDiagnostics(machineInManifest) : null
+      }
+    }),
+    makeCheck2("data-dir", details["data_dir_exists"] === "yes" ? "ok" : "warn", "Data directory check", `${redactPath(details["data_dir"] || "unknown")} ${details["data_dir_exists"] === "yes" ? "exists" : "missing"}`, {
+      data: {
+        path: redactPath(details["data_dir"] || "unknown"),
+        exists: details["data_dir_exists"] === "yes"
+      }
+    }),
+    makeCheck2("manifest-path", details["manifest_exists"] === "yes" ? "ok" : "warn", "Manifest path check", `${redactPath(details["manifest_path"] || "unknown")} ${details["manifest_exists"] === "yes" ? "exists" : "missing"}`, {
+      data: {
+        path: redactPath(details["manifest_path"] || "unknown"),
+        exists: details["manifest_exists"] === "yes"
+      }
+    }),
+    makeCheck2("db-path", details["db_exists"] === "yes" ? "ok" : "warn", "DB path check", `${redactPath(details["db_path"] || "unknown")} ${details["db_exists"] === "yes" ? "exists" : "missing"}`, {
+      data: {
+        path: redactPath(details["db_path"] || "unknown"),
+        exists: details["db_exists"] === "yes"
+      }
+    }),
+    makeCheck2("notifications-path", details["notifications_exists"] === "yes" ? "ok" : "warn", "Notifications path check", `${redactPath(details["notifications_path"] || "unknown")} ${details["notifications_exists"] === "yes" ? "exists" : "missing"}`, {
+      data: {
+        path: redactPath(details["notifications_path"] || "unknown"),
+        exists: details["notifications_exists"] === "yes"
+      }
+    }),
     makeCheck2("bun", details["bun"] && details["bun"] !== "missing" ? "ok" : "fail", "Bun availability", details["bun"] || "missing"),
     makeCheck2("machines-cli", details["machines"] && details["machines"] !== "missing" ? "ok" : "warn", "machines CLI availability", details["machines"] || "missing"),
     makeCheck2("machines-agent-cli", details["machines_agent"] && details["machines_agent"] !== "missing" ? "ok" : "warn", "machines-agent availability", details["machines_agent"] || "missing"),
     makeCheck2("machines-mcp-cli", details["machines_mcp"] && details["machines_mcp"] !== "missing" ? "ok" : "warn", "machines-mcp availability", details["machines_mcp"] || "missing"),
-    makeCheck2("ssh", details["ssh"] === "ok" ? "ok" : "warn", "SSH availability", details["ssh"] || "missing")
+    makeCheck2("ssh", details["ssh"] === "ok" ? "ok" : "warn", "SSH availability", details["ssh"] || "missing"),
+    makeCheck2("sudo-noninteractive", details["sudo_noninteractive"] === "ok" ? "ok" : "warn", "Noninteractive sudo availability", details["sudo_noninteractive"] === "ok" ? "sudo -n is available" : "sudo -n unavailable; setup may require user-provided approval or password handling.", {
+      data: { available: details["sudo_noninteractive"] === "ok" },
+      remediation: details["sudo_noninteractive"] === "ok" ? undefined : ["Configure explicit sudo policy or run setup commands manually; do not store sudo passwords in public manifests."]
+    }),
+    makeCheck2("ssh-cert-support", details["ssh_cert_support"] === "ok" ? "ok" : "warn", "SSH certificate support", details["ssh_cert_support"] === "ok" ? "OpenSSH reports ed25519 certificate support" : "OpenSSH certificate support not detected.", {
+      data: { supported: details["ssh_cert_support"] === "ok" },
+      remediation: details["ssh_cert_support"] === "ok" ? undefined : ["Install or update OpenSSH before adopting SSH certificate auth for this machine."]
+    }),
+    makeCheck2("github-app-auth", details["github_app_ref"] === "configured" ? "ok" : "warn", "GitHub App auth references", details["github_app_ref"] === "configured" ? "GitHub App id and private-key reference are configured" : "GitHub App id/private-key reference missing; use secret references, not user tokens or raw private keys.", {
+      data: {
+        gh_cli: details["gh_cli"] && details["gh_cli"] !== "missing",
+        gh_auth: details["gh_auth"] === "ok",
+        app_ref_configured: details["github_app_ref"] === "configured"
+      },
+      remediation: details["github_app_ref"] === "configured" ? undefined : ["Set HASNA_GITHUB_APP_ID plus HASNA_GITHUB_APP_PRIVATE_KEY_REF or provide an equivalent open-secrets adapter."]
+    }),
+    ...optionalAdapterChecks
   ];
   return {
     machineId,
     source: commandChecks.source,
-    manifestPath: details["manifest_path"],
-    dbPath: details["db_path"],
-    notificationsPath: details["notifications_path"],
+    schemaVersion: 1,
+    generatedAt: now.toISOString(),
+    manifestSource,
+    manifestPath: details["manifest_path"] ? redactPath(details["manifest_path"]) : undefined,
+    dbPath: details["db_path"] ? redactPath(details["db_path"]) : undefined,
+    notificationsPath: details["notifications_path"] ? redactPath(details["notifications_path"]) : undefined,
     checks
   };
 }

package/dist/commands/doctor.d.ts

@@ -1,3 +1,24 @@
-import type { DoctorReport } from "../types.js";
-export declare function runDoctor(machineId?: string): DoctorReport;
+import { type ManifestSourceAdapter } from "../manifests.js";
+import type { DoctorCheck, DoctorReport, FleetManifest, ManifestLoadInfo } from "../types.js";
+export declare const DOCTOR_OPTIONAL_ADAPTER_DOMAINS: readonly ["secrets", "configs", "monitor", "repos", "mcps", "shield"];
+export type DoctorOptionalAdapterDomain = typeof DOCTOR_OPTIONAL_ADAPTER_DOMAINS[number];
+export interface DoctorAdapterContext {
+    machineId: string;
+    manifest: FleetManifest;
+    manifestSource: ManifestLoadInfo;
+    commandDetails: Record<string, string>;
+    now: Date;
+}
+export type DoctorAdapterHook = (context: DoctorAdapterContext) => DoctorCheck | DoctorCheck[] | null | undefined;
+export interface DoctorAdapter {
+    id: string;
+    checks?: Partial<Record<DoctorOptionalAdapterDomain, DoctorAdapterHook>>;
+}
+export interface DoctorOptions {
+    now?: Date;
+    manifestAdapter?: ManifestSourceAdapter | null;
+    adapters?: DoctorAdapter[];
+    includeOptionalAdapters?: boolean;
+}
+export declare function runDoctor(machineId?: string, options?: DoctorOptions): DoctorReport;
 //# sourceMappingURL=doctor.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAe,YAAY,EAAE,MAAM,aAAa,CAAC;AAqC7D,wBAAgB,SAAS,CAAC,SAAS,SAAsB,GAAG,YAAY,CAuEvE"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AACA,OAAO,EAA0B,KAAK,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAGrF,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE9F,eAAO,MAAM,+BAA+B,uEAAwE,CAAC;AAErH,MAAM,MAAM,2BAA2B,GAAG,OAAO,+BAA+B,CAAC,MAAM,CAAC,CAAC;AAEzF,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,aAAa,CAAC;IACxB,cAAc,EAAE,gBAAgB,CAAC;IACjC,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,GAAG,EAAE,IAAI,CAAC;CACX;AAED,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,EAAE,oBAAoB,KAAK,WAAW,GAAG,WAAW,EAAE,GAAG,IAAI,GAAG,SAAS,CAAC;AAElH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,2BAA2B,EAAE,iBAAiB,CAAC,CAAC,CAAC;CAC1E;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,eAAe,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAC/C,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;IAC3B,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACnC;AAuHD,wBAAgB,SAAS,CAAC,SAAS,SAAsB,EAAE,OAAO,GAAE,aAAkB,GAAG,YAAY,CAwLpG"}

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

@@ -1 +1 @@
-{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/commands/setup.ts"],"names":[],"mappings":"AAGA,OAAO,EAAoD,KAAK,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAC3G,OAAO,KAAK,EAAmB,WAAW,EAAa,MAAM,aAAa,CAAC;AAsE3E,wBAAgB,cAAc,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,WAAW,CAyB9D;AAED,wBAAgB,QAAQ,CACtB,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,OAAO,CAAA;CAAO,EAChD,MAAM,GAAE,oBAAwC,GAC/C,WAAW,CAmCb"}
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/commands/setup.ts"],"names":[],"mappings":"AAGA,OAAO,EAAoD,KAAK,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAC3G,OAAO,KAAK,EAAmB,WAAW,EAAa,MAAM,aAAa,CAAC;AAiG3E,wBAAgB,cAAc,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,WAAW,CAyB9D;AAED,wBAAgB,QAAQ,CACtB,SAAS,CAAC,EAAE,MAAM,EAClB,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,OAAO,CAAA;CAAO,EAChD,MAAM,GAAE,oBAAwC,GAC/C,WAAW,CAmCb"}