@inneranimalmedia/agentsam-sdk 2.0.0 → 2.1.0

package/src/lib/deploy-receipt/index.js

@@ -0,0 +1,246 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { buildMerkleTree, diffTrees, readSnapshot, validateSnapshot } from '../merkle/index.js';
+import { normalizePolicy } from '../merkle/policy.js';
+
+export const DEFAULT_DEPLOY_EXCLUDES = Object.freeze([
+  '.agentsam/deploy-merkle',
+  '.wrangler',
+  'coverage',
+  '.cache',
+  '.turbo',
+  '.env',
+  '.env.local',
+  '.env.cloudflare',
+  '.env.cloudflare.local',
+  '.env.production',
+  '.env.production.local',
+  '.env.development',
+  '.env.development.local',
+  '.env.test',
+  '.env.test.local',
+  '.env.staging',
+  '.env.preview',
+  '.env.docker',
+  '.dev.vars',
+  '.npmrc',
+  '.deploy-dashboard-source-fingerprint.json',
+  '.deploy-pipeline-stats.json',
+  '.deploy-r2-delta-stats.json',
+  '.deploy-r2-static-hashes.json',
+  '.deploy-route-stats.json',
+  '.deploy-sw-tiered-manifest.json',
+  '.deploy-worker-fingerprint.json',
+  '.deploy-worker-stats.json',
+]);
+
+function git(root, args) {
+  try {
+    return execFileSync('git', ['-C', root, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } catch {
+    return '';
+  }
+}
+
+function portableRelative(root, target) {
+  const relative = path.relative(root, target).split(path.sep).join('/');
+  return relative && !relative.startsWith('../') && relative !== '..' ? relative : '';
+}
+
+function paths(root, stateDir) {
+  const state = path.resolve(stateDir || path.join(root, '.agentsam/deploy-merkle'));
+  return {
+    stateDir: state,
+    pendingSnapshot: path.join(state, 'pending.snapshot.json'),
+    pendingReceipt: path.join(state, 'pending.receipt.json'),
+    latestSnapshot: path.join(state, 'latest.snapshot.json'),
+    latestReceipt: path.join(state, 'latest.receipt.json'),
+    historyDir: path.join(state, 'history'),
+  };
+}
+
+async function atomicJson(filename, value) {
+  await fs.mkdir(path.dirname(filename), { recursive: true });
+  const temp = `${filename}.tmp-${randomBytes(8).toString('hex')}`;
+  try {
+    await fs.writeFile(temp, JSON.stringify(value, null, 2) + '\n', { flag: 'wx', mode: 0o600 });
+    await fs.rename(temp, filename);
+  } finally {
+    await fs.rm(temp, { force: true }).catch(() => {});
+  }
+}
+
+async function loadSnapshot(input) {
+  if (!input) return null;
+  if (typeof input === 'string') return readSnapshot(input);
+  return validateSnapshot(input);
+}
+
+function sourceDirty(root, stateDir) {
+  const raw = git(root, ['status', '--porcelain=v1', '--untracked-files=all']);
+  if (!raw) return false;
+  const stateRelative = portableRelative(root, stateDir);
+  return raw.split('\n').some((line) => {
+    const candidate = line.slice(3).replace(/^"|"$/g, '').replace(/\\/g, '/');
+    return !(stateRelative && (candidate === stateRelative || candidate.startsWith(`${stateRelative}/`)));
+  });
+}
+
+function gitMetadata(root) {
+  return {
+    git_sha: git(root, ['rev-parse', 'HEAD']),
+    git_branch: git(root, ['rev-parse', '--abbrev-ref', 'HEAD']),
+    repository: git(root, ['remote', 'get-url', 'origin']),
+  };
+}
+
+function truncateChanges(changes, maxChangedFiles) {
+  const files = changes.map((change) => change.path);
+  if (files.length <= maxChangedFiles) return files;
+  return [...files.slice(0, maxChangedFiles), `__truncated__:+${files.length - maxChangedFiles}_more`];
+}
+
+export async function captureDeployReceipt({
+  root = '.',
+  project,
+  stateDir,
+  baselineSnapshot,
+  baselineSource,
+  include = [],
+  exclude = [],
+  maxChangedFiles = 100,
+  metadata = {},
+} = {}) {
+  const rootPath = await fs.realpath(root);
+  const state = paths(rootPath, stateDir);
+  const dirty = sourceDirty(rootPath, state.stateDir);
+  const stateRelative = portableRelative(rootPath, state.stateDir);
+  const policy = normalizePolicy({
+    include,
+    exclude: [...new Set([
+      ...DEFAULT_DEPLOY_EXCLUDES,
+      ...(stateRelative ? [stateRelative] : []),
+      ...exclude,
+    ])],
+  });
+
+  await fs.mkdir(state.historyDir, { recursive: true });
+
+  let baseline = null;
+  let resolvedBaselineSource = baselineSource || 'none';
+  if (baselineSnapshot) {
+    try {
+      baseline = await loadSnapshot(baselineSnapshot);
+      resolvedBaselineSource = baselineSource || 'provided';
+    } catch {
+      resolvedBaselineSource = 'invalid';
+    }
+  } else {
+    try {
+      baseline = await readSnapshot(state.latestSnapshot);
+      resolvedBaselineSource = 'local';
+    } catch (error) {
+      if (error?.code !== 'ENOENT') resolvedBaselineSource = 'invalid';
+    }
+  }
+
+  const tree = await buildMerkleTree(rootPath, { policy });
+  await atomicJson(state.pendingSnapshot, tree);
+
+  let diff = null;
+  if (baseline) {
+    try {
+      diff = diffTrees(baseline, tree);
+    } catch {
+      baseline = null;
+      resolvedBaselineSource = 'invalid';
+    }
+  }
+
+  const gitInfo = gitMetadata(rootPath);
+  const receipt = {
+    format: 'agentsam-deploy-merkle',
+    version: 1,
+    engine: 'agentsam-merkle-v1',
+    status: 'captured',
+    project: project || path.basename(rootPath),
+    repository: gitInfo.repository || null,
+    git_sha: gitInfo.git_sha || null,
+    git_branch: gitInfo.git_branch || null,
+    captured_at: new Date().toISOString(),
+    root_hash: tree.rootHash,
+    previous_root_hash: baseline?.rootHash || null,
+    has_baseline: Boolean(baseline),
+    baseline_source: resolvedBaselineSource,
+    working_tree_dirty: dirty,
+    stats: tree.stats,
+    diff_stats: diff?.stats || null,
+    changed_files: diff ? truncateChanges(diff.changes, maxChangedFiles) : [],
+    ...metadata,
+  };
+  await atomicJson(state.pendingReceipt, receipt);
+  return { receipt, snapshot: tree, paths: state };
+}
+
+export async function finalizeDeployReceipt({
+  root = '.',
+  stateDir,
+  status,
+  deploymentId,
+  workerVersionId,
+  metadata = {},
+} = {}) {
+  if (!['success', 'failed'].includes(status)) throw new Error('Deploy receipt status must be success or failed.');
+  const rootPath = await fs.realpath(root);
+  const state = paths(rootPath, stateDir);
+  const [pendingReceipt, pendingSnapshot] = await Promise.all([
+    JSON.parse(await fs.readFile(state.pendingReceipt, 'utf8')),
+    readSnapshot(state.pendingSnapshot),
+  ]).catch((error) => {
+    if (error?.code === 'ENOENT') throw new Error('No pending deploy receipt capture exists.');
+    throw error;
+  });
+  if (pendingReceipt?.format !== 'agentsam-deploy-merkle' || pendingReceipt?.status !== 'captured') {
+    throw new Error('Pending deploy receipt is invalid or already finalized.');
+  }
+  if (pendingReceipt.root_hash !== pendingSnapshot.rootHash) throw new Error('Pending receipt/snapshot root mismatch.');
+
+  const completed = new Date().toISOString();
+  const receipt = {
+    ...pendingReceipt,
+    ...metadata,
+    status,
+    completed_at: completed,
+    deployment_id: deploymentId || null,
+    worker_version_id: workerVersionId || null,
+  };
+  const stamp = completed.replace(/[-:.]/g, '').replace('Z', 'Z');
+  const sha = (receipt.git_sha || 'unknown').replace(/[^A-Za-z0-9._-]/g, '-');
+  const rootSlug = receipt.root_hash.replace(/^sha256:/, '');
+  const historyReceipt = path.join(state.historyDir, `${stamp}-${sha}-${rootSlug.slice(0, 12)}-${status}.receipt.json`);
+  await atomicJson(historyReceipt, receipt);
+
+  if (status === 'success') {
+    await fs.copyFile(state.pendingSnapshot, state.latestSnapshot);
+    await atomicJson(state.latestReceipt, receipt);
+  }
+  return { receipt, snapshot: pendingSnapshot, paths: { ...state, historyReceipt } };
+}
+
+export async function showLatestDeployReceipt({ root = '.', stateDir } = {}) {
+  const rootPath = await fs.realpath(root);
+  const state = paths(rootPath, stateDir);
+  try {
+    return JSON.parse(await fs.readFile(state.latestReceipt, 'utf8'));
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+export const captureCheckpoint = captureDeployReceipt;
+export async function promoteCheckpoint(options = {}) {
+  return finalizeDeployReceipt({ ...options, status: 'success' });
+}

package/test/deploy-receipt.test.mjs

@@ -0,0 +1,91 @@
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import {
+  captureDeployReceipt,
+  finalizeDeployReceipt,
+  showLatestDeployReceipt,
+} from '../src/lib/deploy-receipt/index.js';
+
+const cli = fileURLToPath(new URL('../src/cli.js', import.meta.url));
+
+async function fixture(t) {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'agentsam-deploy-receipt-'));
+  t.after(() => fs.rm(root, { recursive: true, force: true }));
+  execFileSync('git', ['init', '-q', root]);
+  execFileSync('git', ['-C', root, 'config', 'user.email', 'receipt-test@example.invalid']);
+  execFileSync('git', ['-C', root, 'config', 'user.name', 'Receipt Test']);
+  await fs.mkdir(path.join(root, 'src'), { recursive: true });
+  await fs.writeFile(path.join(root, 'src/app.js'), 'export const value = 1;\n');
+  execFileSync('git', ['-C', root, 'add', '.']);
+  execFileSync('git', ['-C', root, 'commit', '-qm', 'fixture']);
+  return root;
+}
+
+function run(args, cwd) {
+  return spawnSync(process.execPath, [cli, 'deploy-receipt', ...args], { cwd, encoding: 'utf8', timeout: 15000 });
+}
+
+test('successful finalize advances baseline while failure preserves the last trusted tree', async (t) => {
+  const root = await fixture(t);
+  const first = await captureDeployReceipt({ root, project: 'fixture' });
+  assert.equal(first.receipt.has_baseline, false);
+  assert.equal(first.receipt.baseline_source, 'none');
+  assert.equal(first.receipt.working_tree_dirty, false);
+  assert.ok(!first.snapshot.entries.some((entry) => entry.path.startsWith('.agentsam/deploy-merkle')));
+
+  const promoted = await finalizeDeployReceipt({ root, status: 'success', deploymentId: 'dep_1' });
+  assert.equal(promoted.receipt.status, 'success');
+  assert.equal(promoted.receipt.deployment_id, 'dep_1');
+  assert.equal((await showLatestDeployReceipt({ root })).root_hash, first.receipt.root_hash);
+
+  const clean = await captureDeployReceipt({ root, project: 'fixture' });
+  assert.equal(clean.receipt.has_baseline, true);
+  assert.equal(clean.receipt.baseline_source, 'local');
+  assert.deepEqual(clean.receipt.diff_stats, { unchanged: 1, modified: 0, added: 0, removed: 0 });
+  assert.deepEqual(clean.receipt.changed_files, []);
+  assert.equal(clean.receipt.root_hash, first.receipt.root_hash);
+  assert.equal(clean.receipt.working_tree_dirty, false, 'runtime receipt state must not make the source tree dirty');
+
+  await fs.writeFile(path.join(root, 'src/app.js'), 'export const value = 2;\n');
+  const changed = await captureDeployReceipt({ root, project: 'fixture' });
+  assert.equal(changed.receipt.working_tree_dirty, true);
+  assert.deepEqual(changed.receipt.diff_stats, { unchanged: 0, modified: 1, added: 0, removed: 0 });
+  assert.deepEqual(changed.receipt.changed_files, ['src/app.js']);
+  assert.notEqual(changed.receipt.root_hash, first.receipt.root_hash);
+
+  await finalizeDeployReceipt({ root, status: 'failed', deploymentId: 'dep_2' });
+  assert.equal((await showLatestDeployReceipt({ root })).root_hash, first.receipt.root_hash, 'failed run must not advance baseline');
+
+  const retry = await captureDeployReceipt({ root, project: 'fixture' });
+  assert.deepEqual(retry.receipt.changed_files, ['src/app.js']);
+  await finalizeDeployReceipt({ root, status: 'success', deploymentId: 'dep_3' });
+  const settled = await captureDeployReceipt({ root, project: 'fixture' });
+  assert.deepEqual(settled.receipt.diff_stats, { unchanged: 1, modified: 0, added: 0, removed: 0 });
+  assert.deepEqual(settled.receipt.changed_files, []);
+});
+
+test('deploy-receipt CLI emits machine-readable capture/finalize/show receipts', async (t) => {
+  const root = await fixture(t);
+  const capture = run(['capture', '.', '--project', 'cli-fixture', '--json'], root);
+  assert.equal(capture.status, 0, capture.stderr);
+  const captured = JSON.parse(capture.stdout);
+  assert.equal(captured.format, 'agentsam-deploy-merkle');
+  assert.equal(captured.project, 'cli-fixture');
+  assert.equal(captured.status, 'captured');
+
+  const success = run(['success', '.', '--deployment-id', 'dep_cli', '--worker-version', 'worker_v1', '--json'], root);
+  assert.equal(success.status, 0, success.stderr);
+  const finalized = JSON.parse(success.stdout);
+  assert.equal(finalized.status, 'success');
+  assert.equal(finalized.deployment_id, 'dep_cli');
+  assert.equal(finalized.worker_version_id, 'worker_v1');
+
+  const show = run(['show', '.', '--json'], root);
+  assert.equal(show.status, 0, show.stderr);
+  assert.equal(JSON.parse(show.stdout).root_hash, finalized.root_hash);
+});