@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.5

package/src/lib/setup/recipes.js

@@ -0,0 +1,235 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { createRequire } from 'node:module';
+
+const execFileAsync = promisify(execFile);
+const require = createRequire(import.meta.url);
+
+async function which(bin) {
+  try {
+    const { stdout } = await execFileAsync(process.platform === 'win32' ? 'where' : 'which', [bin], { timeout: 5000 });
+    return String(stdout || '').trim().split(/\r?\n/)[0] || null;
+  } catch {
+    return null;
+  }
+}
+
+async function versionOf(bin, args) {
+  try {
+    const { stdout, stderr } = await execFileAsync(bin, args, { timeout: 8000 });
+    return `${stdout || ''}${stderr || ''}`.trim().split(/\n/)[0].slice(0, 80);
+  } catch {
+    return null;
+  }
+}
+
+/** @type {import('./contract.js').InstallableCapability} */
+export const imageRasterTransformCapability = {
+  id: 'image.raster.transform',
+  displayName: 'Raster image transforms',
+  description: 'Resize/convert PNG/JPEG/WebP/AVIF via Sharp (preferred) or ImageMagick (optional)',
+  risk: 'low',
+  requiresApproval: false,
+  capabilityProvided: ['image.raster.transform', 'image.raster.inspect'],
+  supportedPlatforms: ['darwin', 'linux', 'win32'],
+  dependencies: ['sharp'],
+  mutations: ['may npm-install sharp in the AgentSam package; optional ImageMagick via OS package manager'],
+  installPlans: {
+    darwin: {
+      provider: 'npm',
+      packages: ['sharp'],
+      notes: [
+        'Sharp is the portable default (declared dependency of @inneranimalmedia/agentsam-sdk-brand).',
+        'Optional enrichment: Homebrew imagemagick for ICNS / exotic formats.',
+        'Brand packs: agentsam brand promote → pack → preview → optional publish',
+        '  agentsam brand pack --brand acme --asset app-icon --source ./master.png --preset app-icon --out ./acme.zip',
+        '  agentsam brand preview --from ./acme.zip',
+      ],
+    },
+    linux: {
+      provider: 'npm',
+      packages: ['sharp'],
+      notes: ['Optional: apt/dnf/pacman imagemagick for extended tooling'],
+    },
+    win32: {
+      provider: 'npm',
+      packages: ['sharp'],
+      notes: ['Optional: winget install ImageMagick.ImageMagick'],
+    },
+  },
+  async detect() {
+    let sharpOk = false;
+    try {
+      require.resolve('sharp');
+      sharpOk = true;
+    } catch {
+      sharpOk = false;
+    }
+    const magick = (await which('magick')) || (await which('convert'));
+    const ok = sharpOk || Boolean(magick);
+    return {
+      ok,
+      detail: sharpOk
+        ? 'Sharp available'
+        : magick
+          ? 'ImageMagick available (Sharp preferred)'
+          : 'missing Sharp and ImageMagick',
+      version: sharpOk ? 'sharp' : magick ? await versionOf(magick, ['--version']) : null,
+      backends: { sharp: sharpOk, imagemagick: Boolean(magick) },
+    };
+  },
+  async verify() {
+    return this.detect();
+  },
+  uninstallHint() {
+    return 'Remove optional ImageMagick via your package manager; Sharp uninstalls with the npm package.';
+  },
+};
+
+/** @type {import('./contract.js').InstallableCapability} */
+export const imageVectorizeCapability = {
+  id: 'image.vectorize',
+  displayName: 'Vector image tooling',
+  description: 'Potrace (+ optional ImageMagick/SVGO) for raster→SVG workflows',
+  risk: 'low',
+  requiresApproval: true,
+  capabilityProvided: ['image.vectorize', 'image.optimize'],
+  supportedPlatforms: ['darwin', 'linux', 'win32'],
+  dependencies: ['potrace'],
+  mutations: ['installs OS packages via detected package manager — no shell profile edits'],
+  installPlans: {
+    darwin: {
+      provider: 'homebrew',
+      packages: ['potrace'],
+      notes: ['Optional: brew install imagemagick; npm i -g svgo'],
+    },
+    linux: {
+      provider: 'apt',
+      packages: ['potrace'],
+      notes: [
+        'Debian/Ubuntu: apt',
+        'Fedora: dnf install potrace',
+        'Arch: pacman -S potrace',
+      ],
+    },
+    win32: {
+      provider: 'winget',
+      packages: [],
+      notes: ['Install Potrace from https://potrace.sourceforge.net/ or chocolatey if available'],
+    },
+  },
+  async detect() {
+    const potrace = await which('potrace');
+    const magick = (await which('magick')) || (await which('convert'));
+    const ok = Boolean(potrace);
+    return {
+      ok,
+      detail: ok ? 'Potrace available' : 'missing potrace',
+      version: potrace ? await versionOf(potrace, ['-v']) : null,
+      backends: { potrace: Boolean(potrace), imagemagick: Boolean(magick) },
+    };
+  },
+  async verify() {
+    return this.detect();
+  },
+  uninstallHint() {
+    return 'Remove potrace with your platform package manager (brew/apt/dnf/winget) — AgentSam will not invent a command.';
+  },
+};
+
+/** @type {import('./contract.js').InstallableCapability} */
+export const googleCloudCapability = {
+  id: 'google.cloud',
+  displayName: 'Google Cloud connection',
+  description: 'gcloud CLI + Agent Sam Desktop/Web OAuth + connection preference',
+  risk: 'medium',
+  requiresApproval: true,
+  capabilityProvided: ['google.cloud.auth', 'google.cloud.doctor'],
+  supportedPlatforms: ['darwin', 'linux', 'win32'],
+  dependencies: ['gcloud'],
+  mutations: [
+    'may open browser for OAuth',
+    'writes ~/.agentsam/connections/google-cloud.json',
+    'may store google-cloud token in OS keychain / vault',
+  ],
+  installPlans: {
+    darwin: {
+      provider: 'homebrew',
+      packages: ['--cask', 'google-cloud-sdk'],
+      notes: [
+        'After gcloud: agentsam gcloud auth login',
+        'Then: agentsam google-cloud connection set --identity EMAIL --project PROJECT',
+        'Inspect: agentsam setup google.cloud --inventory',
+        'Doctor: agentsam google-cloud doctor --json',
+      ],
+    },
+    linux: {
+      provider: 'manual',
+      commands: ['# install Google Cloud SDK: https://cloud.google.com/sdk/docs/install'],
+      notes: ['Then agentsam gcloud auth login'],
+    },
+    win32: {
+      provider: 'winget',
+      packages: ['Google.CloudSDK'],
+      notes: ['Then agentsam gcloud auth login'],
+    },
+  },
+  async detect() {
+    const gcloud = await which('gcloud');
+    if (!gcloud) return { ok: false, detail: 'gcloud not on PATH' };
+    const version = await versionOf('gcloud', ['--version']);
+    return { ok: true, detail: 'gcloud available', version };
+  },
+  async verify() {
+    return this.detect();
+  },
+  uninstallHint() {
+    return 'brew uninstall --cask gcloud-cli   # or remove Google Cloud SDK';
+  },
+};
+
+/** @type {import('./contract.js').InstallableCapability} */
+export const cloudflareWranglerCapability = {
+  id: 'cloudflare.wrangler',
+  displayName: 'Cloudflare Wrangler',
+  description: 'Wrangler CLI for Workers / D1 / deploy',
+  risk: 'low',
+  requiresApproval: true,
+  capabilityProvided: ['cloudflare.wrangler'],
+  supportedPlatforms: ['darwin', 'linux', 'win32'],
+  dependencies: ['wrangler'],
+  mutations: ['npm/global or project-local install'],
+  installPlans: {
+    darwin: { provider: 'npm', packages: ['wrangler@latest'], notes: ['Prefer repo-local npx wrangler'] },
+    linux: { provider: 'npm', packages: ['wrangler@latest'] },
+    win32: { provider: 'npm', packages: ['wrangler@latest'] },
+  },
+  async detect() {
+    const wrangler = await which('wrangler');
+    if (wrangler) {
+      return { ok: true, detail: 'wrangler on PATH', version: await versionOf('wrangler', ['--version']) };
+    }
+    return { ok: false, detail: 'wrangler not on PATH (npx wrangler may still work in this repo)' };
+  },
+  async verify() {
+    return this.detect();
+  },
+  uninstallHint() {
+    return 'npm uninstall -g wrangler';
+  },
+};
+
+export const CAPABILITY_RECIPES = Object.freeze({
+  [imageRasterTransformCapability.id]: imageRasterTransformCapability,
+  [imageVectorizeCapability.id]: imageVectorizeCapability,
+  [googleCloudCapability.id]: googleCloudCapability,
+  [cloudflareWranglerCapability.id]: cloudflareWranglerCapability,
+});
+
+export function listCapabilityRecipes() {
+  return Object.values(CAPABILITY_RECIPES);
+}
+
+export function getCapabilityRecipe(id) {
+  return CAPABILITY_RECIPES[String(id || '').trim()] || null;
+}

package/src/lib/setup/runtime-persist.js

@@ -0,0 +1,197 @@
+/**
+ * Platform persistence for agentsamd (LaunchAgent / Windows Scheduled Task).
+ * Pure builders are exported for tests; side-effect helpers call OS tools.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { runtimeStateDir, ensureRuntimeStateDir } from './runtime.js';
+
+const execFileAsync = promisify(execFile);
+
+export const DARWIN_LAUNCH_LABEL = 'com.inneranimalmedia.agentsamd';
+export const WINDOWS_TASK_NAME = 'InnerAnimalMedia\\agentsamd';
+export const WINDOWS_TASK_FOLDER = 'InnerAnimalMedia';
+
+/**
+ * @param {{ binary: string, listen: string, stdoutLog: string, stderrLog: string, label?: string }} opts
+ */
+export function buildLaunchAgentPlist(opts) {
+  const label = opts.label || DARWIN_LAUNCH_LABEL;
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${label}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${opts.binary}</string>
+    <string>--listen</string>
+    <string>${opts.listen}</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>${opts.stdoutLog}</string>
+  <key>StandardErrorPath</key><string>${opts.stderrLog}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>AGENTSAMD_ROLE</key><string>machine</string>
+  </dict>
+</dict>
+</plist>
+`;
+}
+
+/**
+ * User-level Scheduled Task XML (InteractiveToken, at logon, restart on failure).
+ * @param {{ binary: string, listen: string, workingDirectory: string, author?: string }} opts
+ */
+export function buildWindowsScheduledTaskXml(opts) {
+  const author = opts.author || 'Inner Animal Media';
+  const bin = String(opts.binary).replace(/&/g, '&amp;').replace(/"/g, '&quot;');
+  const cwd = String(opts.workingDirectory).replace(/&/g, '&amp;').replace(/"/g, '&quot;');
+  const listen = String(opts.listen).replace(/&/g, '&amp;').replace(/"/g, '&quot;');
+  // Arguments must not include the executable path — Command contains the .exe.
+  return `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.4" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Author>${author}</Author>
+    <Description>AgentSam machine runtime daemon (agentsamd). Protocol agentsam.runtime.v1.</Description>
+  </RegistrationInfo>
+  <Triggers>
+    <LogonTrigger>
+      <Enabled>true</Enabled>
+    </LogonTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <AllowHardTerminate>true</AllowHardTerminate>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable>
+    <AllowStartOnDemand>true</AllowStartOnDemand>
+    <Enabled>true</Enabled>
+    <Hidden>false</Hidden>
+    <RunOnlyIfIdle>false</RunOnlyIfIdle>
+    <WakeToRun>false</WakeToRun>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <Priority>7</Priority>
+    <RestartOnFailure>
+      <Interval>PT1M</Interval>
+      <Count>3</Count>
+    </RestartOnFailure>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>${bin}</Command>
+      <Arguments>--listen ${listen}</Arguments>
+      <WorkingDirectory>${cwd}</WorkingDirectory>
+    </Exec>
+  </Actions>
+</Task>
+`;
+}
+
+/**
+ * @returns {{ kind: 'launch_agent', label: string, plist: string } | null}
+ */
+export function writeLaunchAgent(home, binary, listen) {
+  if (process.platform !== 'darwin') return null;
+  const label = DARWIN_LAUNCH_LABEL;
+  const plistDir = path.join(home, 'Library', 'LaunchAgents');
+  fs.mkdirSync(plistDir, { recursive: true });
+  const plist = path.join(plistDir, `${label}.plist`);
+  const logDir = path.join(runtimeStateDir(home), 'logs');
+  fs.mkdirSync(logDir, { recursive: true });
+  const contents = buildLaunchAgentPlist({
+    binary,
+    listen,
+    label,
+    stdoutLog: path.join(logDir, 'agentsamd.stdout.log'),
+    stderrLog: path.join(logDir, 'agentsamd.stderr.log'),
+  });
+  fs.writeFileSync(plist, contents);
+  return { kind: 'launch_agent', label, plist };
+}
+
+/**
+ * Write task XML under ~/.agentsam/runtime/ and register via schtasks.
+ * @returns {Promise<{ kind: 'scheduled_task', taskName: string, xmlPath: string, registered: boolean, error?: string } | null>}
+ */
+export async function writeWindowsScheduledTask(home, binary, listen, options = {}) {
+  if (process.platform !== 'win32' && options.forcePlatform !== 'win32') return null;
+  ensureRuntimeStateDir(home);
+  const xmlPath = path.join(runtimeStateDir(home), 'agentsamd.scheduled-task.xml');
+  const workingDirectory = path.dirname(binary);
+  const xml = buildWindowsScheduledTaskXml({ binary, listen, workingDirectory });
+  // Node writes UTF-8; schtasks accepts UTF-8 when /XML is used on modern Windows.
+  fs.writeFileSync(xmlPath, xml, 'utf8');
+
+  const taskName = WINDOWS_TASK_NAME;
+  const execImpl = options.execFileAsync || execFileAsync;
+  if (options.skipRegister === true) {
+    return { kind: 'scheduled_task', taskName, xmlPath, registered: false };
+  }
+  try {
+    await execImpl('schtasks', ['/Create', '/TN', taskName, '/XML', xmlPath, '/F'], {
+      timeout: 30000,
+      windowsHide: true,
+    });
+    return { kind: 'scheduled_task', taskName, xmlPath, registered: true };
+  } catch (err) {
+    return {
+      kind: 'scheduled_task',
+      taskName,
+      xmlPath,
+      registered: false,
+      error: String(err?.message || err),
+    };
+  }
+}
+
+export async function startWindowsScheduledTask(options = {}) {
+  const execImpl = options.execFileAsync || execFileAsync;
+  const taskName = options.taskName || WINDOWS_TASK_NAME;
+  await execImpl('schtasks', ['/Run', '/TN', taskName], { timeout: 15000, windowsHide: true });
+  return { ok: true, taskName };
+}
+
+export async function stopWindowsScheduledTask(options = {}) {
+  const execImpl = options.execFileAsync || execFileAsync;
+  const taskName = options.taskName || WINDOWS_TASK_NAME;
+  try {
+    await execImpl('schtasks', ['/End', '/TN', taskName], { timeout: 15000, windowsHide: true });
+  } catch {
+    /* task may not be running */
+  }
+  return { ok: true, taskName };
+}
+
+export async function bootstrapDarwinLaunchAgent(plist, label = DARWIN_LAUNCH_LABEL) {
+  if (process.platform !== 'darwin' || !plist) return { ok: false };
+  try {
+    await execFileAsync('launchctl', ['unload', plist], { timeout: 10000 }).catch(() => {});
+    await execFileAsync('launchctl', ['load', plist], { timeout: 10000 });
+    return { ok: true, label, plist };
+  } catch (err) {
+    return { ok: false, error: String(err?.message || err), label, plist };
+  }
+}
+
+export async function unloadDarwinLaunchAgent(plist) {
+  if (process.platform !== 'darwin' || !plist) return { ok: false };
+  try {
+    await execFileAsync('launchctl', ['unload', plist], { timeout: 10000 });
+    return { ok: true, plist };
+  } catch (err) {
+    return { ok: false, error: String(err?.message || err), plist };
+  }
+}