@fargowealth/fargo-ai-cli 0.5.1 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.7.0
+
+- Added source-backup history metadata and Portal list/download support for
+  immutable source versions, including independent backup-only events.
+- Deployment now requires a version number, version name, and upgrade notes;
+  history records show the deployer and expandable notes.
+- Source backup remains the deploy default. Added explicit `--skip-source` for
+  deployments that intentionally omit a source archive.
+
+## 0.6.0
+
+- Added `fargo lego deploy` to create a source snapshot and deterministic
+  Pages/Worker deployment ZIP, upload both through authenticated binary data
+  paths, and create a ready deployment through the hosted MCP contract.
+- Deployment artifacts now preserve text and binary files, carry per-file and
+  aggregate SHA-256 provenance, support `.legodeployignore`, and are linked to
+  deployment records by `deployArtifactId`.
+- Added `fargo lego d1 migrate plan|apply` for ordered local SQL files with
+  server-verified hashes, idempotent retries, and content-drift protection.
+- Kept publication and migrations independent from deployment, and kept R2,
+  Cloudflare credentials, permission checks, and D1 execution server-side.
+
 ## 0.5.1
 
 - Exclude the conventional `.build` generated-output directory from LEGO

package/README.md

@@ -1,21 +1,20 @@
 # Fargo AI CLI
 
 `fargo` is the Agent-neutral command-line client for Fargo AI. Codex, Claude
-Code, Cursor, WorkBuddy, and any Agent that can execute shell commands share
-the same Fargo identity, hosted MCP contracts, and LEGO project operations.
+Code, Cursor, WorkBuddy, and future shell-capable Agents share the same Fargo
+identity, hosted MCP contracts, and deterministic LEGO project operations.
 
 Requires Node.js 20.19 or newer.
 
 ## Install or upgrade
 
 ```sh
-npm install -g @fargowealth/fargo-ai-cli@0.5.1
+npm install -g @fargowealth/fargo-ai-cli@0.7.0
 fargo version
 ```
 
-Use the native remote Fargo MCP connection as the default online tool surface.
-Authenticate the CLI separately only when an Agent needs to package or upload
-files from its local workspace:
+Use native hosted Fargo MCP for ordinary online tools. Authenticate the CLI
+only when an Agent first needs local files:
 
 ```sh
 fargo auth login --agent codex
@@ -26,20 +25,18 @@ fargo auth status
 
 Aliases `cc` and `claude` resolve to `claude-code`. Login uses OAuth
 Authorization Code + PKCE over an ephemeral IPv4 loopback callback. The CLI
-validates OAuth state, uses PKCE S256, closes the listener after callback, and
-never prints access or refresh credentials.
+validates state, uses PKCE S256, closes the listener, and never prints tokens.
 
 ## MCP boundary
 
-- MCP is the default for online Fargo resources, status, deployment,
-  publication, rollback, and other business operations.
-- CLI is used when the operation needs the Agent's local filesystem or binary
-  transfer: source walking, exclusions, ZIP creation, hashing, upload, and
-  download.
-- A future `fargo lego deploy --source .` command may compose the two, but it
-  will remain a client-side workflow over the same server deployment contract.
-
-Agents without native MCP support can use the CLI fallback:
+- Hosted MCP owns Fargo resources, permission checks, status, publication,
+  rollback, Cloudflare writes, and D1 execution.
+- CLI owns local walking, exclusions, ZIP creation, hashing, binary transfer,
+  deploy composition, and migration-file ordering.
+- CLI has no generic R2 or Cloudflare administration commands.
+- `fargo mcp serve` is the local stdio bridge for WorkBuddy.
+- `fargo mcp tools` and `fargo mcp call` are fallbacks for Agents without a
+  native remote MCP client.
 
 ```sh
 fargo mcp tools
@@ -47,28 +44,71 @@ fargo mcp call lego_get_app --args '{"appId":"app_xxx"}'
 fargo mcp call lego_get_app --args-file ./arguments.json
 ```
 
-`fargo mcp serve` remains the local stdio bridge for hosts such as WorkBuddy
-that require one. Codex, Claude Code, and Cursor should prefer the remote MCP
-URL and its native OAuth support.
-
 ## LEGO source snapshots
 
 ```sh
-fargo lego snapshot upload --app app_xxx --source . --dry-run
-fargo lego snapshot upload --app app_xxx --source . --version v1
+fargo lego snapshot upload --app app_xxx --source . --version 1.4.0 --name "Pre-upgrade backup" --dry-run
+fargo lego snapshot upload --app app_xxx --source . --version 1.4.0 --name "Pre-upgrade backup" --notes "Before migration"
 fargo lego snapshot list --app app_xxx
 fargo lego snapshot download --app app_xxx --snapshot snap_xxx
 ```
 
 The CLI applies secure defaults plus `.legoignore`, skips symbolic links,
-creates a deterministic ZIP, calculates SHA-256 digests, and uploads the bytes
-over an authenticated HTTP data path. Archive bytes are not embedded in MCP
-JSON-RPC. The default archive limit is 50 MB.
+creates a deterministic ZIP, calculates SHA-256 digests, and uploads raw bytes
+over authenticated HTTP. The ZIP includes
+`.fargo-snapshot/manifest.json`; its default archive limit is 50 MB.
+An upload creates a downloadable source-backup history event without deploying
+or publishing the App.
+
+## LEGO local deploy
+
+Run the project build explicitly, then give Fargo CLI the completed output:
+
+```sh
+npm run build
+fargo lego deploy \
+  --app app_xxx \
+  --source . \
+  --deploy-dir dist \
+  --target pages \
+  --entrypoint index.html \
+  --version 1.4.0 \
+  --name "Navigation refresh" \
+  --notes-file CHANGELOG.md
+```
+
+For Workers use `--target worker`; the default entrypoint becomes `index.js`.
+The CLI does not install dependencies, infer a framework, or run the build.
+Version number, version name, and upgrade notes are required. Source upload is
+the default; `--skip-source` is the explicit exception for a deployment that
+must not retain a source archive.
+
+The command creates and uploads two immutable archives:
+
+1. a filtered source snapshot for recovery and provenance;
+2. a deterministic deployment ZIP from `--deploy-dir` using
+   `.legodeployignore`.
+
+It then sends only `sourceSnapshotId` and `deployArtifactId` through the hosted
+MCP deployment contract. The result is `ready`, never automatically published.
+Use `--dry-run` to validate both local packages without authentication or
+network writes.
+
+Deployment artifacts preserve binary bytes and include
+`.fargo-deploy/manifest.json`. Default limits are 1,000 files, 25 MB total,
+20 MB per file, and a 25 MB ZIP.
+
+## LEGO D1 migrations
+
+```sh
+fargo lego d1 migrate plan --app app_xxx --dir migrations
+fargo lego d1 migrate apply --app app_xxx --dir migrations
+```
 
-The ZIP includes `.fargo-snapshot/manifest.json`. Dependencies, VCS data,
-generated output, caches, secrets, previous archives, large video/audio, and
-design-source files are excluded by default. Add project-specific gitignore
-syntax to `.legoignore`.
+Migration files are top-level, lexically ordered `*.sql` files. The filename
+without `.sql` is the version. `plan` compares local SHA-256 values with the
+production registry; `apply` stops on content drift and submits only pending
+files. Migration execution remains server-side and is never coupled to deploy.
 
 ## WorkBuddy adapter
 
@@ -77,8 +117,7 @@ npx -y @fargowealth/fargo-ai-cli@latest workbuddy install --open-browser=always
 ```
 
 The installer preserves existing MCP servers and adds the local Fargo stdio
-bridge. Device Authorization Grant remains available only as an explicit
-WorkBuddy fallback:
+bridge. Device Authorization Grant remains an explicit fallback:
 
 ```sh
 fargo auth device --open-browser=always --output=jsonl
@@ -89,12 +128,10 @@ fargo auth device --open-browser=always --output=jsonl
 - macOS and Linux: `~/.fargo/credentials.json`
 - Windows: `%APPDATA%\Fargo AI\credentials.json`
 
-On macOS and Linux, the directory is forced to `0700` and the credential file
-to `0600`. Windows inherits the current user's NTFS ACL from `%APPDATA%`.
-Writes use an `fsync`-backed temporary file followed by atomic replacement,
-symbolic-link reads are rejected, and refresh-token rotation is serialized
-across local CLI processes.
+macOS/Linux use a `0700` directory and `0600` file. Windows inherits the
+current user's NTFS ACL. Writes use an `fsync`-backed temporary file and atomic
+replacement, symbolic-link reads are rejected, and refresh-token rotation is
+serialized across CLI processes.
 
-The file contains an OAuth refresh credential. Never copy, upload, commit, or
-print it. Use `fargo auth logout` to remove it and revoke the Fargo connection
-when a device is no longer trusted.
+Never copy, upload, commit, or print the credential file. Use
+`fargo auth logout` when a device is no longer trusted.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fargowealth/fargo-ai-cli",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Agent-neutral Fargo AI CLI, MCP client, and LEGO project tooling",
   "type": "module",
   "bin": {

package/src/cli.mjs

@@ -4,6 +4,8 @@ import { createCredentialStore } from "./credential-store.mjs";
 import { authorizePkce, currentCredential, openBrowser, pollDeviceAuthorization, startDeviceAuthorization } from "./auth.mjs";
 import { CLI_VERSION } from "./constants.mjs";
 import { downloadLegoSourceSnapshot, listLegoSourceSnapshots, uploadLegoSourceSnapshot } from "./lego-snapshots.mjs";
+import { deployLocalLegoApp } from "./lego-deploy.mjs";
+import { applyLegoMigrations, planLegoMigrations } from "./lego-migrations.mjs";
 import { callMcpTool, listMcpTools } from "./mcp-client.mjs";
 import { runMcpProxy } from "./mcp-proxy.mjs";
 import { installWorkBuddyMcp } from "./workbuddy-install.mjs";
@@ -55,6 +57,45 @@ export async function runCli(args, options = {}) {
       await runLegoSnapshotCommand(args, stdout, store, options);
       return;
     }
+    if (args[0] === "lego" && args[1] === "deploy") {
+      const appId = requiredOption(args, "--app");
+      const deployDir = requiredOption(args, "--deploy-dir");
+      const target = requiredOption(args, "--target");
+      const version = requiredVersionOption(args, "--version", 80);
+      const versionName = requiredTextOption(args, "--name", 160);
+      const releaseNotes = await requiredNotesOption(args);
+      const result = await deployLocalLegoApp(store, {
+        appId,
+        deployDir,
+        dryRun: args.includes("--dry-run"),
+        entrypoint: optionValue(args, "--entrypoint"),
+        releaseNotes,
+        skipSource: args.includes("--skip-source"),
+        source: optionValue(args, "--source") ?? ".",
+        target,
+        version,
+        versionName
+      }, options);
+      stdout.write(`${JSON.stringify(result)}\n`);
+      return;
+    }
+    if (args[0] === "lego" && args[1] === "d1" && args[2] === "migrate") {
+      const action = args[3];
+      const input = {
+        appId: requiredOption(args, "--app"),
+        directory: optionValue(args, "--dir") ?? "migrations",
+        tablePrefix: optionValue(args, "--table-prefix")
+      };
+      if (action === "plan") {
+        stdout.write(`${JSON.stringify(await planLegoMigrations(store, input, options))}\n`);
+        return;
+      }
+      if (action === "apply") {
+        stdout.write(`${JSON.stringify(await applyLegoMigrations(store, input, options))}\n`);
+        return;
+      }
+      throw new Error("Usage: fargo lego d1 migrate plan|apply --app <appId> [--dir migrations]");
+    }
     if (args[0] === "workbuddy" && args[1] === "install") {
       let credential = await store.load();
       if (credential) {
@@ -72,7 +113,7 @@ export async function runCli(args, options = {}) {
       stdout.write(`${JSON.stringify(await installWorkBuddyMcp(options))}\n`);
       return;
     }
-    throw new Error("Usage: fargo auth login|device|status|logout | fargo mcp serve|tools|call | fargo lego snapshot upload|list|download | fargo workbuddy install | fargo version");
+    throw new Error("Usage: fargo auth login|device|status|logout | fargo mcp serve|tools|call | fargo lego snapshot upload|list|download | fargo lego deploy | fargo lego d1 migrate plan|apply | fargo workbuddy install | fargo version");
   } catch (error) {
     stderr.write(`fargo: ${error instanceof Error ? error.message : "unknown error"}\n`);
     if (options.throwOnError) throw error;
@@ -106,8 +147,11 @@ async function runLegoSnapshotCommand(args, stdout, store, options) {
     const result = await uploadLegoSourceSnapshot(store, {
       appId,
       dryRun: args.includes("--dry-run"),
+      notes: await optionalNotesOption(args),
+      purpose: "backup",
       source: optionValue(args, "--source") ?? ".",
-      version: optionValue(args, "--version")
+      version: requiredVersionOption(args, "--version", 120),
+      versionName: requiredTextOption(args, "--name", 160)
     }, options);
     stdout.write(`${JSON.stringify(result)}\n`);
     return;
@@ -128,7 +172,25 @@ async function runLegoSnapshotCommand(args, stdout, store, options) {
     stdout.write(`${JSON.stringify({ archiveSha256: result.archiveSha256, outputPath, sizeBytes: result.archive.byteLength, snapshotId })}\n`);
     return;
   }
-  throw new Error("Usage: fargo lego snapshot upload|list|download --app <appId>");
+  throw new Error("Usage: fargo lego snapshot upload --app <appId> --version <number> --name <name> [--notes TEXT | --notes-file PATH] | list|download --app <appId>");
+}
+
+async function requiredNotesOption(args) {
+  const notes = await optionalNotesOption(args);
+  if (!notes) throw new Error("Missing release notes; pass --notes <text> or --notes-file <path>");
+  if (notes.length > 4_000) throw new Error("Release notes must not exceed 4000 characters");
+  return notes;
+}
+
+async function optionalNotesOption(args) {
+  const inline = optionValue(args, "--notes");
+  const file = optionValue(args, "--notes-file");
+  if (inline !== undefined && file !== undefined) throw new Error("Use only one of --notes or --notes-file");
+  const notes = file !== undefined
+    ? (await readFile(resolve(file), "utf8")).trim()
+    : inline?.trim() ?? "";
+  if (notes.length > 4_000) throw new Error("Notes must not exceed 4000 characters");
+  return notes;
 }
 
 async function readToolArgs(args) {
@@ -160,7 +222,21 @@ async function pathExists(path) {
 
 function requiredOption(args, name) {
   const value = optionValue(args, name)?.trim();
-  if (!value) throw new Error(`Missing required option ${name}`);
+  if (!value || value.startsWith("--")) throw new Error(`Missing required option ${name}`);
+  return value;
+}
+
+function requiredTextOption(args, name, maxLength) {
+  const value = requiredOption(args, name);
+  if (value.length > maxLength) throw new Error(`${name} must not exceed ${maxLength} characters`);
+  return value;
+}
+
+function requiredVersionOption(args, name, maxLength) {
+  const value = requiredTextOption(args, name, maxLength);
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value)) {
+    throw new Error(`${name} must use letters, numbers, dot, underscore, or hyphen`);
+  }
   return value;
 }
 

package/src/constants.mjs

@@ -1,4 +1,4 @@
-export const CLI_VERSION = "0.5.1";
+export const CLI_VERSION = "0.7.0";
 export const DEVICE_CODE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
 export const DEFAULT_AUTH_URL = "https://auth.fargowealth.app";
 export const DEFAULT_API_URL = "https://mcp.fargowealth.app";

package/src/deployment-artifact.mjs

@@ -0,0 +1,207 @@
+import { createHash } from "node:crypto";
+import { lstat, opendir, readFile } from "node:fs/promises";
+import { basename, extname, join, resolve, sep } from "node:path";
+import { strToU8, zipSync } from "fflate";
+import ignore from "ignore";
+
+export const MAX_DEPLOY_ARCHIVE_BYTES = 25_000_000;
+export const MAX_DEPLOY_FILE_BYTES = 20_000_000;
+export const MAX_DEPLOY_FILE_COUNT = 1_000;
+export const MAX_DEPLOY_CONTENT_BYTES = 25_000_000;
+
+const FIXED_ZIP_DATE = new Date(1980, 0, 1, 0, 0, 0, 0);
+const MANIFEST_PATH = ".fargo-deploy/manifest.json";
+const DEFAULT_IGNORE_RULES = [
+  ".git/",
+  "node_modules/",
+  ".fargo-deploy/",
+  ".DS_Store",
+  "Thumbs.db",
+  ".env",
+  ".env.*",
+  ".npmrc",
+  ".pypirc",
+  "*.pem",
+  "*.key",
+  "id_rsa*",
+  "credentials*.json"
+];
+
+export async function createDeploymentArtifact(deployDirectory, options = {}) {
+  const root = resolve(deployDirectory || ".");
+  const rootStat = await lstat(root).catch(() => undefined);
+  if (!rootStat?.isDirectory()) {
+    throw new Error(`Deployment output is not a directory: ${root}`);
+  }
+
+  const target = deploymentTarget(options.target);
+  const entrypoint = normalizePath(options.entrypoint || (target === "pages" ? "index.html" : "index.js"));
+  const matcher = ignore().add(DEFAULT_IGNORE_RULES);
+  const customRules = await readOptionalText(join(root, ".legodeployignore"));
+  if (customRules) matcher.add(customRules);
+
+  const candidates = [];
+  const skippedSymlinks = [];
+  await walk(root, "");
+  candidates.sort((left, right) => compareText(left.path, right.path));
+  if (candidates.length === 0) {
+    throw new Error("No deployment files remain after applying deployment exclusions");
+  }
+  if (!candidates.some((file) => file.path === entrypoint)) {
+    throw new Error(`Deployment entrypoint is missing from output: ${entrypoint}`);
+  }
+
+  const files = [];
+  const archiveEntries = {};
+  const contentHash = createHash("sha256");
+  let contentSizeBytes = 0;
+  for (const file of candidates) {
+    const bytes = await readFile(file.absolutePath);
+    const sha256 = digest(bytes);
+    const contentType = contentTypeForPath(file.path);
+    contentSizeBytes += bytes.byteLength;
+    if (contentSizeBytes > (options.maxContentBytes ?? MAX_DEPLOY_CONTENT_BYTES)) {
+      throw new Error(`Deployment output exceeds ${formatBytes(options.maxContentBytes ?? MAX_DEPLOY_CONTENT_BYTES)}`);
+    }
+    const item = { path: file.path, sha256, sizeBytes: bytes.byteLength, contentType };
+    files.push(item);
+    contentHash
+      .update(item.path).update("\0")
+      .update(String(item.sizeBytes)).update("\0")
+      .update(item.sha256).update("\0")
+      .update(item.contentType).update("\n");
+    archiveEntries[item.path] = [bytes, { level: 6, mtime: FIXED_ZIP_DATE }];
+  }
+
+  const contentSha256 = contentHash.digest("hex");
+  const manifest = {
+    schemaVersion: 1,
+    kind: "fargo-lego-deployment-artifact",
+    archiveFormat: "zip",
+    target,
+    entrypoint,
+    contentSha256,
+    fileCount: files.length,
+    contentSizeBytes,
+    files
+  };
+  archiveEntries[MANIFEST_PATH] = [strToU8(`${JSON.stringify(manifest, null, 2)}\n`), { level: 6, mtime: FIXED_ZIP_DATE }];
+  const archive = zipSync(archiveEntries, { level: 6, mtime: FIXED_ZIP_DATE });
+  const maxArchiveBytes = options.maxArchiveBytes ?? MAX_DEPLOY_ARCHIVE_BYTES;
+  if (archive.byteLength > maxArchiveBytes) {
+    throw new Error(`Deployment artifact is ${formatBytes(archive.byteLength)}, above the ${formatBytes(maxArchiveBytes)} limit`);
+  }
+
+  return {
+    archive,
+    archiveName: `${safeFileName(basename(root))}-${contentSha256.slice(0, 12)}.zip`,
+    archiveSha256: digest(archive),
+    contentSha256,
+    contentSizeBytes,
+    entrypoint,
+    fileCount: files.length,
+    manifest,
+    root,
+    skippedSymlinkCount: skippedSymlinks.length,
+    target
+  };
+
+  async function walk(absoluteDirectory, relativeDirectory) {
+    const directory = await opendir(absoluteDirectory);
+    const entries = [];
+    for await (const entry of directory) entries.push(entry);
+    entries.sort((left, right) => compareText(left.name, right.name));
+
+    for (const entry of entries) {
+      const relativePath = normalizePath(relativeDirectory ? `${relativeDirectory}/${entry.name}` : entry.name);
+      const absolutePath = join(absoluteDirectory, entry.name);
+      if (entry.isSymbolicLink()) {
+        skippedSymlinks.push(relativePath);
+        continue;
+      }
+      if (entry.isDirectory()) {
+        if (!matcher.ignores(`${relativePath}/`)) await walk(absolutePath, relativePath);
+        continue;
+      }
+      if (!entry.isFile() || matcher.ignores(relativePath) || relativePath === ".legodeployignore") continue;
+      const stat = await lstat(absolutePath);
+      const maxFileBytes = options.maxFileBytes ?? MAX_DEPLOY_FILE_BYTES;
+      if (stat.size > maxFileBytes) {
+        throw new Error(`Deployment file '${relativePath}' is ${formatBytes(stat.size)}, above the ${formatBytes(maxFileBytes)} per-file limit`);
+      }
+      candidates.push({ absolutePath, path: relativePath });
+      if (candidates.length > (options.maxFileCount ?? MAX_DEPLOY_FILE_COUNT)) {
+        throw new Error(`Deployment output contains more than ${options.maxFileCount ?? MAX_DEPLOY_FILE_COUNT} files`);
+      }
+    }
+  }
+}
+
+export function contentTypeForPath(path) {
+  const extension = extname(path).toLowerCase();
+  const known = {
+    ".avif": "image/avif",
+    ".css": "text/css; charset=utf-8",
+    ".csv": "text/csv; charset=utf-8",
+    ".gif": "image/gif",
+    ".html": "text/html; charset=utf-8",
+    ".ico": "image/x-icon",
+    ".jpeg": "image/jpeg",
+    ".jpg": "image/jpeg",
+    ".js": "application/javascript; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".map": "application/json; charset=utf-8",
+    ".mjs": "application/javascript; charset=utf-8",
+    ".pdf": "application/pdf",
+    ".png": "image/png",
+    ".svg": "image/svg+xml; charset=utf-8",
+    ".txt": "text/plain; charset=utf-8",
+    ".wasm": "application/wasm",
+    ".webp": "image/webp",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+    ".xml": "application/xml; charset=utf-8"
+  };
+  return known[extension] ?? "application/octet-stream";
+}
+
+function deploymentTarget(value) {
+  const target = String(value || "").trim().toLowerCase();
+  if (target === "pages" || target === "worker") return target;
+  throw new Error("Deployment target must be 'pages' or 'worker'");
+}
+
+function digest(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function compareText(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function normalizePath(value) {
+  const path = String(value || "").split(sep).join("/").replace(/^\.\//, "").replace(/^\/+/, "");
+  if (!path || path.length > 240 || path.includes("\\") || path.split("/").some((part) => !part || part === "." || part === "..")) {
+    throw new Error(`Invalid deployment path: ${value}`);
+  }
+  return path;
+}
+
+async function readOptionalText(path) {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return "";
+    throw error;
+  }
+}
+
+function safeFileName(value) {
+  return value.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "deploy";
+}
+
+function formatBytes(value) {
+  if (value < 1_000) return `${value} B`;
+  if (value < 1_000_000) return `${(value / 1_000).toFixed(1)} KB`;
+  return `${(value / 1_000_000).toFixed(1)} MB`;
+}

package/src/lego-deploy-artifacts.mjs

@@ -0,0 +1,47 @@
+import { authenticatedRequest, responsePayload } from "./api-client.mjs";
+
+export async function uploadLegoDeployArtifact(store, input, options = {}) {
+  const artifact = input.artifact;
+  if (!artifact?.archive) throw new Error("Deployment artifact archive is required");
+  const url = deployArtifactCollectionUrl(input.appId, options);
+  if (input.version) url.searchParams.set("version", input.version);
+  const response = await authenticatedRequest(store, url, {
+    method: "POST",
+    headers: {
+      Accept: "application/json",
+      "Content-Type": "application/zip",
+      "Content-Length": String(artifact.archive.byteLength),
+      "X-Fargo-Deploy-Archive-Sha256": artifact.archiveSha256,
+      "X-Fargo-Deploy-Content-Sha256": artifact.contentSha256,
+      "X-Fargo-Deploy-Content-Size": String(artifact.contentSizeBytes),
+      "X-Fargo-Deploy-Entrypoint": artifact.entrypoint,
+      "X-Fargo-Deploy-File-Count": String(artifact.fileCount),
+      "X-Fargo-Deploy-Target": artifact.target
+    },
+    body: artifact.archive
+  }, options);
+  return {
+    ...(await responsePayload(response)),
+    local: deploymentArtifactSummary(artifact)
+  };
+}
+
+export function deploymentArtifactSummary(artifact) {
+  return {
+    archiveName: artifact.archiveName,
+    archiveSha256: artifact.archiveSha256,
+    archiveSizeBytes: artifact.archive.byteLength,
+    contentSha256: artifact.contentSha256,
+    contentSizeBytes: artifact.contentSizeBytes,
+    entrypoint: artifact.entrypoint,
+    fileCount: artifact.fileCount,
+    root: artifact.root,
+    skippedSymlinkCount: artifact.skippedSymlinkCount,
+    target: artifact.target
+  };
+}
+
+function deployArtifactCollectionUrl(appId, options) {
+  const apiUrl = (options.apiUrl ?? process.env.FARGO_API_URL ?? "https://mcp.fargowealth.app").replace(/\/+$/, "");
+  return new URL(`${apiUrl}/api/lego/apps/${encodeURIComponent(appId)}/deploy-artifacts`);
+}

package/src/lego-deploy.mjs

@@ -0,0 +1,90 @@
+import { createDeploymentArtifact } from "./deployment-artifact.mjs";
+import { uploadLegoDeployArtifact, deploymentArtifactSummary } from "./lego-deploy-artifacts.mjs";
+import { uploadLegoSourceSnapshot } from "./lego-snapshots.mjs";
+import { callMcpTool } from "./mcp-client.mjs";
+import { mcpToolPayload } from "./mcp-result.mjs";
+import { createSourceSnapshot } from "./source-snapshot.mjs";
+
+export async function deployLocalLegoApp(store, input, options = {}) {
+  const target = requiredTarget(input.target);
+  const entrypoint = input.entrypoint || (target === "pages" ? "index.html" : "index.js");
+  const [snapshot, artifact] = await Promise.all([
+    input.skipSource ? Promise.resolve(undefined) : createSourceSnapshot(input.source || ".", options.snapshotOptions),
+    createDeploymentArtifact(input.deployDir, { ...options.artifactOptions, target, entrypoint })
+  ]);
+
+  if (input.dryRun) {
+    return {
+      dryRun: true,
+      release: {
+        notes: input.releaseNotes,
+        version: input.version,
+        versionName: input.versionName
+      },
+      sourceSnapshot: snapshot ? sourceSnapshotSummary(snapshot) : undefined,
+      sourceSnapshotSkipped: !snapshot,
+      deployArtifact: deploymentArtifactSummary(artifact)
+    };
+  }
+
+  const uploadedSnapshot = snapshot ? await uploadLegoSourceSnapshot(store, {
+    appId: input.appId,
+    notes: input.releaseNotes,
+    purpose: "deployment",
+    source: input.source || ".",
+    version: input.version,
+    versionName: input.versionName
+  }, { ...options, snapshot }) : undefined;
+  const sourceSnapshotId = uploadedSnapshot?.sourceSnapshot?.id;
+  if (snapshot && !sourceSnapshotId) throw new Error("Source snapshot upload did not return sourceSnapshot.id");
+
+  const uploadedArtifact = await uploadLegoDeployArtifact(store, {
+    appId: input.appId,
+    artifact,
+    version: input.version
+  }, options);
+  const deployArtifactId = uploadedArtifact.deployArtifact?.id;
+  if (!deployArtifactId) throw new Error("Deployment artifact upload did not return deployArtifact.id");
+
+  const tool = target === "pages" ? "lego_pages_deploy" : "lego_worker_deploy";
+  const deploymentInput = {
+    appId: input.appId,
+    deployArtifactId,
+    entrypoint: artifact.entrypoint,
+    releaseNotes: input.releaseNotes,
+    version: input.version,
+    versionName: input.versionName,
+    ...(sourceSnapshotId ? { sourceSnapshotId } : {})
+  };
+  const deployment = mcpToolPayload(await callMcpTool(store, tool, deploymentInput, options));
+
+  return {
+    appId: input.appId,
+    target,
+    sourceSnapshot: uploadedSnapshot?.sourceSnapshot,
+    sourceSnapshotSkipped: !snapshot,
+    deployArtifact: uploadedArtifact.deployArtifact,
+    deployment: deployment.deployment,
+    sourceVersion: deployment.sourceVersion,
+    security: deployment.security
+  };
+}
+
+function sourceSnapshotSummary(snapshot) {
+  return {
+    archiveName: snapshot.archiveName,
+    archiveSha256: snapshot.archiveSha256,
+    archiveSizeBytes: snapshot.archive.byteLength,
+    contentSha256: snapshot.contentSha256,
+    fileCount: snapshot.fileCount,
+    root: snapshot.root,
+    skippedSymlinkCount: snapshot.skippedSymlinkCount,
+    sourceSizeBytes: snapshot.sourceSizeBytes
+  };
+}
+
+function requiredTarget(value) {
+  const target = String(value || "").trim().toLowerCase();
+  if (target === "pages" || target === "worker") return target;
+  throw new Error("Missing or invalid --target; use pages or worker");
+}

package/src/lego-migrations.mjs

@@ -0,0 +1,113 @@
+import { createHash } from "node:crypto";
+import { lstat, opendir, readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { callMcpTool } from "./mcp-client.mjs";
+import { mcpToolPayload } from "./mcp-result.mjs";
+
+const MAX_MIGRATION_BYTES = 80_000;
+const MAX_MIGRATION_FILES = 500;
+
+export async function planLegoMigrations(store, input, options = {}) {
+  return publicMigrationPlan(await buildMigrationPlan(store, input, options));
+}
+
+async function buildMigrationPlan(store, input, options) {
+  const local = await readMigrationDirectory(input.directory);
+  const remote = mcpToolPayload(await callMcpTool(store, "lego_d1_migrations_list", { appId: input.appId }, options));
+  const applied = new Map((remote.migrations ?? []).map((migration) => [String(migration.version), migration]));
+  const migrations = local.map((migration) => {
+    const existing = applied.get(migration.version);
+    if (!existing) return { ...migration, status: "pending" };
+    if (!existing.contentSha256) return { ...migration, status: "applied_unverified", remote: existing };
+    return existing.contentSha256 === migration.contentSha256
+      ? { ...migration, status: "applied", remote: existing }
+      : { ...migration, status: "drift", remote: existing };
+  });
+  return {
+    appId: input.appId,
+    directory: resolve(input.directory || "migrations"),
+    migrations,
+    summary: {
+      applied: migrations.filter((item) => item.status === "applied").length,
+      appliedUnverified: migrations.filter((item) => item.status === "applied_unverified").length,
+      drift: migrations.filter((item) => item.status === "drift").length,
+      pending: migrations.filter((item) => item.status === "pending").length
+    }
+  };
+}
+
+export async function applyLegoMigrations(store, input, options = {}) {
+  const plan = await buildMigrationPlan(store, input, options);
+  const drift = plan.migrations.filter((migration) => migration.status === "drift");
+  if (drift.length > 0) {
+    throw new Error(`Migration drift detected: ${drift.map((item) => item.fileName).join(", ")}`);
+  }
+
+  const applied = [];
+  for (const migration of plan.migrations.filter((item) => item.status === "pending")) {
+    const result = mcpToolPayload(await callMcpTool(store, "lego_d1_migrations_apply", {
+      appId: input.appId,
+      contentSha256: migration.contentSha256,
+      fileName: migration.fileName,
+      sql: migration.sql,
+      tablePrefix: input.tablePrefix,
+      version: migration.version
+    }, options));
+    applied.push(result.migration);
+  }
+
+  return {
+    appId: input.appId,
+    applied,
+    appliedCount: applied.length,
+    plan: {
+      directory: plan.directory,
+      summary: plan.summary
+    }
+  };
+}
+
+function publicMigrationPlan(plan) {
+  return {
+    ...plan,
+    migrations: plan.migrations.map(({ sql: _sql, ...migration }) => migration)
+  };
+}
+
+async function readMigrationDirectory(directory) {
+  const root = resolve(directory || "migrations");
+  const stat = await lstat(root).catch(() => undefined);
+  if (!stat?.isDirectory()) throw new Error(`Migration directory is not a directory: ${root}`);
+  const handle = await opendir(root);
+  const entries = [];
+  for await (const entry of handle) entries.push(entry);
+  const sqlFiles = entries.filter((entry) => entry.isFile() && entry.name.endsWith(".sql"));
+  const unexpectedLinks = entries.filter((entry) => entry.isSymbolicLink());
+  if (unexpectedLinks.length > 0) throw new Error(`Migration directory contains symbolic links: ${unexpectedLinks.map((entry) => entry.name).join(", ")}`);
+  sqlFiles.sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+  if (sqlFiles.length === 0) throw new Error(`Migration directory contains no .sql files: ${root}`);
+  if (sqlFiles.length > MAX_MIGRATION_FILES) throw new Error(`Migration directory contains more than ${MAX_MIGRATION_FILES} SQL files`);
+
+  const migrations = [];
+  const versions = new Set();
+  for (const entry of sqlFiles) {
+    const version = entry.name.slice(0, -4);
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/.test(version)) {
+      throw new Error(`Invalid migration filename: ${entry.name}`);
+    }
+    if (versions.has(version)) throw new Error(`Duplicate migration version: ${version}`);
+    versions.add(version);
+    const sql = await readFile(join(root, entry.name), "utf8");
+    const sizeBytes = Buffer.byteLength(sql);
+    if (sizeBytes === 0) throw new Error(`Migration file is empty: ${entry.name}`);
+    if (sizeBytes > MAX_MIGRATION_BYTES) throw new Error(`Migration file exceeds ${MAX_MIGRATION_BYTES} bytes: ${entry.name}`);
+    migrations.push({
+      contentSha256: createHash("sha256").update(sql).digest("hex"),
+      fileName: entry.name,
+      sizeBytes,
+      sql,
+      version
+    });
+  }
+  return migrations;
+}

package/src/lego-snapshots.mjs

@@ -3,13 +3,28 @@ import { authenticatedRequest, responsePayload } from "./api-client.mjs";
 import { createSourceSnapshot } from "./source-snapshot.mjs";
 
 export async function uploadLegoSourceSnapshot(store, input, options = {}) {
-  const snapshot = await createSourceSnapshot(input.source ?? ".", options.snapshotOptions);
+  const snapshot = options.snapshot ?? await createSourceSnapshot(input.source ?? ".", options.snapshotOptions);
   if (input.dryRun) {
-    return { dryRun: true, snapshot: snapshotSummary(snapshot) };
+    return {
+      dryRun: true,
+      metadata: {
+        notes: input.notes ?? "",
+        purpose: input.purpose ?? "backup",
+        version: input.version ?? "",
+        versionName: input.versionName ?? ""
+      },
+      snapshot: snapshotSummary(snapshot)
+    };
   }
 
   const url = snapshotCollectionUrl(input.appId, options);
   if (input.version) url.searchParams.set("version", input.version);
+  const metadata = Buffer.from(JSON.stringify({
+    notes: input.notes ?? "",
+    purpose: input.purpose ?? "backup",
+    version: input.version ?? "",
+    versionName: input.versionName ?? ""
+  }), "utf8").toString("base64url");
   const response = await authenticatedRequest(store, url, {
     method: "POST",
     headers: {
@@ -19,6 +34,7 @@ export async function uploadLegoSourceSnapshot(store, input, options = {}) {
       "X-Fargo-Source-Archive-Sha256": snapshot.archiveSha256,
       "X-Fargo-Source-Content-Sha256": snapshot.contentSha256,
       "X-Fargo-Source-File-Count": String(snapshot.fileCount),
+      "X-Fargo-Source-Metadata": metadata,
       "X-Fargo-Source-Size": String(snapshot.sourceSizeBytes)
     },
     body: snapshot.archive

package/src/mcp-result.mjs

@@ -0,0 +1,14 @@
+export function mcpToolPayload(result) {
+  if (result?.isError) {
+    const code = result.structuredContent?.error?.code;
+    const text = result.content?.map((item) => item?.text).filter(Boolean).join("\n");
+    throw new Error(code || text || "Fargo MCP tool failed");
+  }
+  const text = result?.content?.find((item) => item?.type === "text" && typeof item.text === "string")?.text;
+  if (!text) return result ?? {};
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { text };
+  }
+}