@fargowealth/fargo-ai-cli 0.6.0 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.7.1
+
+- Added Worker Static Assets packaging with explicit asset directory, binding,
+  SPA/404 handling, HTML handling, and Worker-first routing metadata.
+- Deployment artifacts now preserve Worker code and browser assets separately
+  so the hosted LEGO publisher can upload both through Cloudflare's formal API.
+
+## 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

package/README.md

@@ -9,7 +9,7 @@ Requires Node.js 20.19 or newer.
 ## Install or upgrade
 
 ```sh
-npm install -g @fargowealth/fargo-ai-cli@0.6.0
+npm install -g @fargowealth/fargo-ai-cli@0.7.1
 fargo version
 ```
 
@@ -47,8 +47,8 @@ fargo mcp call lego_get_app --args-file ./arguments.json
 ## 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
 ```
@@ -57,6 +57,8 @@ The CLI applies secure defaults plus `.legoignore`, skips symbolic links,
 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
 
@@ -67,14 +69,49 @@ npm run build
 fargo lego deploy \
   --app app_xxx \
   --source . \
+  --source-exclude node_modules/ \
   --deploy-dir dist \
   --target pages \
   --entrypoint index.html \
-  --version v1
+  --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.
+
+Full-stack Workers can include Cloudflare Worker Static Assets without giving
+the local CLI Cloudflare credentials:
+
+```sh
+fargo lego deploy \
+  --app app_xxx \
+  --source . \
+  --deploy-dir .build/worker \
+  --target worker \
+  --entrypoint index.js \
+  --assets-dir dist \
+  --assets-binding ASSETS \
+  --assets-not-found-handling single-page-application \
+  --assets-run-worker-first \
+  --version 1.4.0 \
+  --name "Full-stack release" \
+  --notes-file CHANGELOG.md
+```
+
+Use repeated `--assets-run-worker-first-route <glob>` options instead of the
+boolean flag when only selected routes should invoke the Worker first. The
+hosted LEGO publisher uploads the assets and attaches the binding; Cloudflare
+credentials remain server-side.
+
+Pass `--source-exclude <gitignore-pattern>` once or multiple times when a
+release command must make additional source exclusions explicit. Secure
+defaults already exclude `node_modules/`, build output, credentials, and common
+generated directories; explicit rules are included in dry-run output.
 
 The command creates and uploads two immutable archives:
 
@@ -94,14 +131,37 @@ Deployment artifacts preserve binary bytes and include
 ## LEGO D1 migrations
 
 ```sh
+# Schema-only migrations keep the existing flow
 fargo lego d1 migrate plan --app app_xxx --dir migrations
 fargo lego d1 migrate apply --app app_xxx --dir migrations
+
+# Controlled data migrations: review the reported impact first
+fargo lego d1 migrate plan \
+  --app app_xxx \
+  --dir migrations \
+  --table-prefix app_code_
+
+# Run only after a separate explicit approval of that plan
+fargo lego d1 migrate apply \
+  --app app_xxx \
+  --dir migrations \
+  --table-prefix app_code_ \
+  --allow-data-migrations
 ```
 
 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.
+files. The plan reports statement types, data-mutation types, target tables,
+and whether separate data-migration approval is required.
+
+Schema DDL remains the default. The opt-in data mode accepts `INSERT ... VALUES`
+with optional `ON CONFLICT`, plus `UPDATE` and `DELETE` only when they contain a
+`WHERE` clause. Data targets must use the server-derived App table prefix;
+system tables, cross-table queries, `PRAGMA`, `ATTACH`, and `DROP` remain
+blocked. `--table-prefix` is a local assertion and the service rejects it if it
+does not match the App's authoritative prefix. Migration execution remains
+server-side and is never coupled to deploy.
 
 ## WorkBuddy adapter
 

package/package.json

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

package/src/cli.mjs

@@ -58,14 +58,30 @@ export async function runCli(args, 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 workerFirstRoutes = optionValues(args, "--assets-run-worker-first-route").filter(Boolean);
       const result = await deployLocalLegoApp(store, {
-        appId: requiredOption(args, "--app"),
-        deployDir: requiredOption(args, "--deploy-dir"),
+        appId,
+        assetsBinding: optionValue(args, "--assets-binding"),
+        assetsDirectory: optionValue(args, "--assets-dir"),
+        assetsHtmlHandling: optionValue(args, "--assets-html-handling"),
+        assetsNotFoundHandling: optionValue(args, "--assets-not-found-handling"),
+        assetsRunWorkerFirst: workerFirstRoutes.length > 0 ? workerFirstRoutes : args.includes("--assets-run-worker-first"),
+        deployDir,
         dryRun: args.includes("--dry-run"),
         entrypoint: optionValue(args, "--entrypoint"),
+        releaseNotes,
+        skipSource: args.includes("--skip-source"),
         source: optionValue(args, "--source") ?? ".",
-        target: requiredOption(args, "--target"),
-        version: optionValue(args, "--version")
+        sourceExcludes: optionValues(args, "--source-exclude"),
+        target,
+        version,
+        versionName
       }, options);
       stdout.write(`${JSON.stringify(result)}\n`);
       return;
@@ -73,6 +89,7 @@ export async function runCli(args, options = {}) {
     if (args[0] === "lego" && args[1] === "d1" && args[2] === "migrate") {
       const action = args[3];
       const input = {
+        allowDataMigrations: args.includes("--allow-data-migrations"),
         appId: requiredOption(args, "--app"),
         directory: optionValue(args, "--dir") ?? "migrations",
         tablePrefix: optionValue(args, "--table-prefix")
@@ -85,7 +102,7 @@ export async function runCli(args, options = {}) {
         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]");
+      throw new Error("Usage: fargo lego d1 migrate plan|apply --app <appId> [--dir migrations] [--table-prefix app_prefix_] [--allow-data-migrations]");
     }
     if (args[0] === "workbuddy" && args[1] === "install") {
       let credential = await store.load();
@@ -138,8 +155,12 @@ 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")
+      sourceExcludes: optionValues(args, "--source-exclude"),
+      version: requiredVersionOption(args, "--version", 120),
+      versionName: requiredTextOption(args, "--name", 160)
     }, options);
     stdout.write(`${JSON.stringify(result)}\n`);
     return;
@@ -160,7 +181,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) {
@@ -192,7 +231,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;
 }
 
@@ -218,3 +271,19 @@ function optionValue(args, name) {
   const index = args.indexOf(name);
   return index >= 0 ? args[index + 1] : undefined;
 }
+
+function optionValues(args, name) {
+  const values = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const value = args[index];
+    if (value.startsWith(`${name}=`)) {
+      values.push(value.slice(name.length + 1));
+      continue;
+    }
+    if (value === name) {
+      values.push(args[index + 1] ?? "");
+      index += 1;
+    }
+  }
+  return values;
+}

package/src/constants.mjs

@@ -1,4 +1,4 @@
-export const CLI_VERSION = "0.6.0";
+export const CLI_VERSION = "0.7.1";
 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

@@ -11,6 +11,7 @@ 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 WORKER_ASSET_ARCHIVE_DIRECTORY = ".fargo-assets";
 const DEFAULT_IGNORE_RULES = [
   ".git/",
   "node_modules/",
@@ -36,13 +37,25 @@ export async function createDeploymentArtifact(deployDirectory, options = {}) {
 
   const target = deploymentTarget(options.target);
   const entrypoint = normalizePath(options.entrypoint || (target === "pages" ? "index.html" : "index.js"));
+  const assets = normalizeWorkerAssets(options.assets, target);
   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, "");
+  await walk(root, "", matcher, "");
+  if (assets) {
+    const assetsRoot = resolve(assets.sourceDirectory);
+    const assetsRootStat = await lstat(assetsRoot).catch(() => undefined);
+    if (!assetsRootStat?.isDirectory()) {
+      throw new Error(`Worker assets output is not a directory: ${assetsRoot}`);
+    }
+    const assetsMatcher = ignore().add(DEFAULT_IGNORE_RULES);
+    const assetsIgnore = await readOptionalText(join(assetsRoot, ".assetsignore"));
+    if (assetsIgnore) assetsMatcher.add(assetsIgnore);
+    await walk(assetsRoot, "", assetsMatcher, WORKER_ASSET_ARCHIVE_DIRECTORY);
+  }
   candidates.sort((left, right) => compareText(left.path, right.path));
   if (candidates.length === 0) {
     throw new Error("No deployment files remain after applying deployment exclusions");
@@ -75,7 +88,7 @@ export async function createDeploymentArtifact(deployDirectory, options = {}) {
 
   const contentSha256 = contentHash.digest("hex");
   const manifest = {
-    schemaVersion: 1,
+    schemaVersion: assets ? 2 : 1,
     kind: "fargo-lego-deployment-artifact",
     archiveFormat: "zip",
     target,
@@ -83,7 +96,16 @@ export async function createDeploymentArtifact(deployDirectory, options = {}) {
     contentSha256,
     fileCount: files.length,
     contentSizeBytes,
-    files
+    files,
+    ...(assets ? {
+      assets: {
+        binding: assets.binding,
+        directory: WORKER_ASSET_ARCHIVE_DIRECTORY,
+        htmlHandling: assets.htmlHandling,
+        notFoundHandling: assets.notFoundHandling,
+        runWorkerFirst: assets.runWorkerFirst
+      }
+    } : {})
   };
   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 });
@@ -103,10 +125,11 @@ export async function createDeploymentArtifact(deployDirectory, options = {}) {
     manifest,
     root,
     skippedSymlinkCount: skippedSymlinks.length,
-    target
+    target,
+    assets: manifest.assets
   };
 
-  async function walk(absoluteDirectory, relativeDirectory) {
+  async function walk(absoluteDirectory, relativeDirectory, activeMatcher, archivePrefix) {
     const directory = await opendir(absoluteDirectory);
     const entries = [];
     for await (const entry of directory) entries.push(entry);
@@ -115,21 +138,22 @@ export async function createDeploymentArtifact(deployDirectory, options = {}) {
     for (const entry of entries) {
       const relativePath = normalizePath(relativeDirectory ? `${relativeDirectory}/${entry.name}` : entry.name);
       const absolutePath = join(absoluteDirectory, entry.name);
+      const archivePath = normalizePath(archivePrefix ? `${archivePrefix}/${relativePath}` : relativePath);
       if (entry.isSymbolicLink()) {
-        skippedSymlinks.push(relativePath);
+        skippedSymlinks.push(archivePath);
         continue;
       }
       if (entry.isDirectory()) {
-        if (!matcher.ignores(`${relativePath}/`)) await walk(absolutePath, relativePath);
+        if (!activeMatcher.ignores(`${relativePath}/`)) await walk(absolutePath, relativePath, activeMatcher, archivePrefix);
         continue;
       }
-      if (!entry.isFile() || matcher.ignores(relativePath) || relativePath === ".legodeployignore") continue;
+      if (!entry.isFile() || activeMatcher.ignores(relativePath) || relativePath === ".legodeployignore" || relativePath === ".assetsignore") 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 });
+      candidates.push({ absolutePath, path: archivePath });
       if (candidates.length > (options.maxFileCount ?? MAX_DEPLOY_FILE_COUNT)) {
         throw new Error(`Deployment output contains more than ${options.maxFileCount ?? MAX_DEPLOY_FILE_COUNT} files`);
       }
@@ -137,6 +161,34 @@ export async function createDeploymentArtifact(deployDirectory, options = {}) {
   }
 }
 
+function normalizeWorkerAssets(value, target) {
+  if (!value?.sourceDirectory) return undefined;
+  if (target !== "worker") throw new Error("Static assets are supported only for Worker deployments");
+  const binding = String(value.binding || "ASSETS").trim();
+  if (!/^[A-Za-z_][A-Za-z0-9_]{0,63}$/.test(binding)) throw new Error("Invalid Worker assets binding");
+  const notFoundHandling = String(value.notFoundHandling || "none").trim();
+  if (!["none", "404-page", "single-page-application"].includes(notFoundHandling)) {
+    throw new Error("Invalid Worker assets not-found handling");
+  }
+  const htmlHandling = String(value.htmlHandling || "auto-trailing-slash").trim();
+  if (!["auto-trailing-slash", "force-trailing-slash", "drop-trailing-slash", "none"].includes(htmlHandling)) {
+    throw new Error("Invalid Worker assets HTML handling");
+  }
+  const runWorkerFirst = Array.isArray(value.runWorkerFirst)
+    ? value.runWorkerFirst.map((route) => String(route).trim()).filter(Boolean)
+    : value.runWorkerFirst === true;
+  if (Array.isArray(runWorkerFirst) && runWorkerFirst.length === 0) {
+    throw new Error("Worker-first asset routes must not be empty");
+  }
+  return {
+    binding,
+    htmlHandling,
+    notFoundHandling,
+    runWorkerFirst,
+    sourceDirectory: value.sourceDirectory
+  };
+}
+
 export function contentTypeForPath(path) {
   const extension = extname(path).toLowerCase();
   const known = {

package/src/lego-deploy-artifacts.mjs

@@ -31,6 +31,7 @@ export function deploymentArtifactSummary(artifact) {
     archiveName: artifact.archiveName,
     archiveSha256: artifact.archiveSha256,
     archiveSizeBytes: artifact.archive.byteLength,
+    assets: artifact.assets,
     contentSha256: artifact.contentSha256,
     contentSizeBytes: artifact.contentSizeBytes,
     entrypoint: artifact.entrypoint,

package/src/lego-deploy.mjs

@@ -9,25 +9,48 @@ 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([
-    createSourceSnapshot(input.source || ".", options.snapshotOptions),
-    createDeploymentArtifact(input.deployDir, { ...options.artifactOptions, target, entrypoint })
+    input.skipSource ? Promise.resolve(undefined) : createSourceSnapshot(input.source || ".", {
+      ...options.snapshotOptions,
+      ignoreRules: [...(options.snapshotOptions?.ignoreRules ?? []), ...(input.sourceExcludes ?? [])]
+    }),
+    createDeploymentArtifact(input.deployDir, {
+      ...options.artifactOptions,
+      target,
+      entrypoint,
+      assets: input.assetsDirectory ? {
+        sourceDirectory: input.assetsDirectory,
+        binding: input.assetsBinding,
+        htmlHandling: input.assetsHtmlHandling,
+        notFoundHandling: input.assetsNotFoundHandling,
+        runWorkerFirst: input.assetsRunWorkerFirst
+      } : undefined
+    })
   ]);
 
   if (input.dryRun) {
     return {
       dryRun: true,
-      sourceSnapshot: sourceSnapshotSummary(snapshot),
+      release: {
+        notes: input.releaseNotes,
+        version: input.version,
+        versionName: input.versionName
+      },
+      sourceSnapshot: snapshot ? sourceSnapshotSummary(snapshot) : undefined,
+      sourceSnapshotSkipped: !snapshot,
       deployArtifact: deploymentArtifactSummary(artifact)
     };
   }
 
-  const uploadedSnapshot = await uploadLegoSourceSnapshot(store, {
+  const uploadedSnapshot = snapshot ? await uploadLegoSourceSnapshot(store, {
     appId: input.appId,
+    notes: input.releaseNotes,
+    purpose: "deployment",
     source: input.source || ".",
-    version: input.version
-  }, { ...options, snapshot });
-  const sourceSnapshotId = uploadedSnapshot.sourceSnapshot?.id;
-  if (!sourceSnapshotId) throw new Error("Source snapshot upload did not return sourceSnapshot.id");
+    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,
@@ -38,18 +61,22 @@ export async function deployLocalLegoApp(store, input, options = {}) {
   if (!deployArtifactId) throw new Error("Deployment artifact upload did not return deployArtifact.id");
 
   const tool = target === "pages" ? "lego_pages_deploy" : "lego_worker_deploy";
-  const deployment = mcpToolPayload(await callMcpTool(store, tool, {
+  const deploymentInput = {
     appId: input.appId,
     deployArtifactId,
     entrypoint: artifact.entrypoint,
-    sourceSnapshotId,
-    version: input.version
-  }, options));
+    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,
+    sourceSnapshot: uploadedSnapshot?.sourceSnapshot,
+    sourceSnapshotSkipped: !snapshot,
     deployArtifact: uploadedArtifact.deployArtifact,
     deployment: deployment.deployment,
     sourceVersion: deployment.sourceVersion,
@@ -66,6 +93,7 @@ function sourceSnapshotSummary(snapshot) {
     fileCount: snapshot.fileCount,
     root: snapshot.root,
     skippedSymlinkCount: snapshot.skippedSymlinkCount,
+    sourceExcludes: snapshot.sourceExcludes,
     sourceSizeBytes: snapshot.sourceSizeBytes
   };
 }

package/src/lego-migrations.mjs

@@ -12,7 +12,7 @@ export async function planLegoMigrations(store, input, options = {}) {
 }
 
 async function buildMigrationPlan(store, input, options) {
-  const local = await readMigrationDirectory(input.directory);
+  const local = await readMigrationDirectory(input.directory, { tablePrefix: input.tablePrefix });
   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) => {
@@ -23,6 +23,7 @@ async function buildMigrationPlan(store, input, options) {
       ? { ...migration, status: "applied", remote: existing }
       : { ...migration, status: "drift", remote: existing };
   });
+  const pendingDataMigrations = migrations.filter((item) => item.status === "pending" && item.impact.dataStatementCount > 0);
   return {
     appId: input.appId,
     directory: resolve(input.directory || "migrations"),
@@ -30,8 +31,13 @@ async function buildMigrationPlan(store, input, options) {
     summary: {
       applied: migrations.filter((item) => item.status === "applied").length,
       appliedUnverified: migrations.filter((item) => item.status === "applied_unverified").length,
+      dataMigrationCount: migrations.filter((item) => item.impact.dataStatementCount > 0).length,
+      dataMutationTypes: Array.from(new Set(migrations.flatMap((item) => item.impact.dataMutationTypes))).sort(),
+      dataStatementCount: migrations.reduce((total, item) => total + item.impact.dataStatementCount, 0),
       drift: migrations.filter((item) => item.status === "drift").length,
-      pending: migrations.filter((item) => item.status === "pending").length
+      pending: migrations.filter((item) => item.status === "pending").length,
+      pendingDataMigrationCount: pendingDataMigrations.length,
+      requiresDataMigrationApproval: pendingDataMigrations.length > 0
     }
   };
 }
@@ -42,11 +48,22 @@ export async function applyLegoMigrations(store, input, options = {}) {
   if (drift.length > 0) {
     throw new Error(`Migration drift detected: ${drift.map((item) => item.fileName).join(", ")}`);
   }
+  const pendingDataMigrations = plan.migrations.filter((migration) => migration.status === "pending" && migration.impact.dataStatementCount > 0);
+  if (pendingDataMigrations.length > 0 && !input.allowDataMigrations) {
+    throw new Error(
+      `Pending data migrations require separate approval: ${pendingDataMigrations.map((item) => item.fileName).join(", ")}. ` +
+      "Review the plan, obtain explicit approval, then rerun apply with --allow-data-migrations."
+    );
+  }
+  if (pendingDataMigrations.length > 0 && !String(input.tablePrefix ?? "").trim()) {
+    throw new Error("Data migrations require an explicit --table-prefix so App-owned table targets can be verified locally and by MCP");
+  }
 
   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,
+      allowDataMigrations: migration.impact.dataStatementCount > 0 && input.allowDataMigrations === true,
       contentSha256: migration.contentSha256,
       fileName: migration.fileName,
       sql: migration.sql,
@@ -74,7 +91,7 @@ function publicMigrationPlan(plan) {
   };
 }
 
-async function readMigrationDirectory(directory) {
+async function readMigrationDirectory(directory, options = {}) {
   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}`);
@@ -101,9 +118,11 @@ async function readMigrationDirectory(directory) {
     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}`);
+    const impact = analyzeLegoMigrationSql(sql, entry.name, options);
     migrations.push({
       contentSha256: createHash("sha256").update(sql).digest("hex"),
       fileName: entry.name,
+      impact,
       sizeBytes,
       sql,
       version
@@ -111,3 +130,199 @@ async function readMigrationDirectory(directory) {
   }
   return migrations;
 }
+
+export function analyzeLegoMigrationSql(sql, fileName = "migration.sql", options = {}) {
+  const statements = parseMigrationStatements(sql);
+  if (statements.length === 0) throw new Error(`Migration file contains no SQL statements: ${fileName}`);
+  const analyses = [];
+  for (let index = 0; index < statements.length; index += 1) {
+    const statement = statements[index];
+    try {
+      analyses.push(analyzeMigrationStatement(statement, options));
+    } catch (error) {
+      const kind = statement.replace(/^\s+/, "").match(/^([A-Za-z]+)/)?.[1]?.toUpperCase() ?? "UNKNOWN";
+      throw new Error(
+        `Unsupported App D1 migration statement in ${fileName} at statement ${index + 1} (${kind}). ` +
+        `${error instanceof Error ? error.message : "Statement failed validation"}. ` +
+        "Allowed schema statements are CREATE TABLE IF NOT EXISTS, CREATE INDEX IF NOT EXISTS, and ALTER TABLE ADD COLUMN. " +
+        "Controlled data statements are INSERT ... VALUES [ON CONFLICT], plus UPDATE or DELETE with WHERE.",
+        { cause: error }
+      );
+    }
+  }
+  const data = analyses.filter((item) => item.category === "data");
+  return {
+    dataMutationTypes: Array.from(new Set(data.map((item) => item.type))).sort(),
+    dataStatementCount: data.length,
+    dataTables: Array.from(new Set(data.map((item) => item.table))).sort(),
+    requiresDataMigrationApproval: data.length > 0,
+    schemaStatementCount: analyses.length - data.length,
+    statementCount: analyses.length,
+    statementTypes: analyses.map((item) => item.type)
+  };
+}
+
+export const validateLegoMigrationSql = analyzeLegoMigrationSql;
+
+function parseMigrationStatements(sql) {
+  const statements = [];
+  let current = "";
+  let quote;
+  let blockComment = false;
+  let lineComment = false;
+
+  for (let index = 0; index < sql.length; index += 1) {
+    const char = sql[index];
+    const next = sql[index + 1];
+    if (blockComment) {
+      if (char === "*" && next === "/") {
+        blockComment = false;
+        index += 1;
+      }
+      continue;
+    }
+    if (lineComment) {
+      if (char === "\n") lineComment = false;
+      continue;
+    }
+    if (!quote && char === "/" && next === "*") {
+      blockComment = true;
+      current += " ";
+      index += 1;
+      continue;
+    }
+    if (!quote && char === "-" && next === "-") {
+      lineComment = true;
+      current += " ";
+      index += 1;
+      continue;
+    }
+    if ((char === "'" || char === '"') && sql[index - 1] !== "\\") {
+      quote = quote === char ? undefined : quote ?? char;
+    }
+    if (!quote && char === ";") {
+      const statement = current.trim();
+      if (statement) statements.push(statement);
+      current = "";
+      continue;
+    }
+    current += char;
+  }
+  if (blockComment) throw new Error("Migration SQL contains an unterminated block comment");
+
+  const trailing = current.trim();
+  if (trailing) statements.push(trailing);
+  return statements;
+}
+
+function analyzeMigrationStatement(statement, options = {}) {
+  const normalized = statement.replace(/\s+/g, " ").trim();
+  const createTable = normalized.match(/^CREATE\s+TABLE\s+IF\s+NOT\s+EXISTS\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*\(/i);
+  if (createTable?.[1]) {
+    assertMigrationIdentifier(createTable[1]);
+    assertOwnedReferences(normalized, options.tablePrefix);
+    return { category: "schema", table: createTable[1], type: "create_table" };
+  }
+
+  const createIndex = normalized.match(/^CREATE\s+INDEX\s+IF\s+NOT\s+EXISTS\s+([a-zA-Z_][a-zA-Z0-9_]*)\s+ON\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*\(/i);
+  if (createIndex?.[1] && createIndex[2]) {
+    assertMigrationIdentifier(createIndex[1]);
+    assertMigrationIdentifier(createIndex[2]);
+    return { category: "schema", table: createIndex[2], type: "create_index" };
+  }
+
+  const alterTable = normalized.match(/^ALTER\s+TABLE\s+([a-zA-Z_][a-zA-Z0-9_]*)\s+ADD\s+COLUMN\s+([a-zA-Z_][a-zA-Z0-9_]*)\b/i);
+  if (alterTable?.[1]) {
+    assertMigrationIdentifier(alterTable[1]);
+    assertOwnedReferences(normalized, options.tablePrefix);
+    return { category: "schema", table: alterTable[1], type: "alter_table" };
+  }
+
+  const structure = stripQuotedSql(normalized);
+  if (/^(?:INSERT\s+INTO|UPDATE|DELETE\s+FROM)\s+[a-zA-Z_][a-zA-Z0-9_]*\s*\./i.test(structure)) {
+    throw new Error("Data migrations cannot use qualified table names");
+  }
+  const insert = structure.match(/^INSERT\s+INTO\s+([a-zA-Z_][a-zA-Z0-9_]*)\b/i);
+  if (insert?.[1]) {
+    assertOwnedDataTable(insert[1], options.tablePrefix);
+    assertNoCrossResourceDataQuery(structure, "insert");
+    if (!/\bVALUES\s*\(/i.test(structure)) throw new Error("INSERT data migrations must use VALUES");
+    if (/\bON\s+CONFLICT\b/i.test(structure) && !/\bDO\s+(?:NOTHING|UPDATE\s+SET)\b/i.test(structure)) {
+      throw new Error("INSERT ON CONFLICT must use DO NOTHING or DO UPDATE SET");
+    }
+    return { category: "data", table: insert[1], type: "insert" };
+  }
+
+  const update = structure.match(/^UPDATE\s+([a-zA-Z_][a-zA-Z0-9_]*)\s+SET\s+/i);
+  if (update?.[1]) {
+    assertOwnedDataTable(update[1], options.tablePrefix);
+    if (!/\bWHERE\b/i.test(structure)) throw new Error("UPDATE data migrations must include WHERE");
+    assertNoCrossResourceDataQuery(structure, "update");
+    return { category: "data", table: update[1], type: "update" };
+  }
+
+  const deleteFrom = structure.match(/^DELETE\s+FROM\s+([a-zA-Z_][a-zA-Z0-9_]*)\b/i);
+  if (deleteFrom?.[1]) {
+    assertOwnedDataTable(deleteFrom[1], options.tablePrefix);
+    if (!/\bWHERE\b/i.test(structure)) throw new Error("DELETE data migrations must include WHERE");
+    assertNoCrossResourceDataQuery(structure, "delete");
+    return { category: "data", table: deleteFrom[1], type: "delete" };
+  }
+  throw new Error("Statement type is not allowed");
+}
+
+function assertMigrationIdentifier(identifier) {
+  if (identifier.toLowerCase().startsWith("sqlite_")) {
+    throw new Error("reserved_migration_identifier");
+  }
+}
+
+function assertOwnedDataTable(identifier, tablePrefix) {
+  assertMigrationIdentifier(identifier);
+  const prefix = String(tablePrefix ?? "").trim().toLowerCase();
+  if (prefix && !identifier.toLowerCase().startsWith(prefix)) {
+    throw new Error(`Data table ${identifier} is outside App prefix ${prefix}`);
+  }
+}
+
+function assertOwnedReferences(statement, tablePrefix) {
+  for (const match of statement.matchAll(/\bREFERENCES\s+([a-zA-Z_][a-zA-Z0-9_]*)\b/gi)) {
+    if (match[1]) assertOwnedDataTable(match[1], tablePrefix);
+  }
+}
+
+function assertNoCrossResourceDataQuery(statement, kind) {
+  const forbidden = kind === "delete"
+    ? /\b(?:SELECT|WITH|JOIN|ATTACH|DETACH|PRAGMA|DROP)\b/i
+    : /\b(?:SELECT|WITH|JOIN|FROM|ATTACH|DETACH|PRAGMA|DROP)\b/i;
+  if (forbidden.test(statement)) {
+    throw new Error("Data migrations cannot query other tables or use administrative SQL");
+  }
+}
+
+function stripQuotedSql(value) {
+  let result = "";
+  let quote;
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index];
+    if (quote) {
+      if (char === quote) {
+        if (value[index + 1] === quote) {
+          result += "  ";
+          index += 1;
+          continue;
+        }
+        quote = undefined;
+      }
+      result += " ";
+      continue;
+    }
+    if (char === "'" || char === '"') {
+      quote = char;
+      result += " ";
+      continue;
+    }
+    result += char;
+  }
+  return result;
+}

package/src/lego-snapshots.mjs

@@ -3,13 +3,31 @@ import { authenticatedRequest, responsePayload } from "./api-client.mjs";
 import { createSourceSnapshot } from "./source-snapshot.mjs";
 
 export async function uploadLegoSourceSnapshot(store, input, options = {}) {
-  const snapshot = options.snapshot ?? await createSourceSnapshot(input.source ?? ".", options.snapshotOptions);
+  const snapshot = options.snapshot ?? await createSourceSnapshot(input.source ?? ".", {
+    ...options.snapshotOptions,
+    ignoreRules: [...(options.snapshotOptions?.ignoreRules ?? []), ...(input.sourceExcludes ?? [])]
+  });
   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 +37,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
@@ -65,6 +84,7 @@ function snapshotSummary(snapshot) {
     fileCount: snapshot.fileCount,
     root: snapshot.root,
     skippedSymlinkCount: snapshot.skippedSymlinkCount,
+    sourceExcludes: snapshot.sourceExcludes,
     sourceSizeBytes: snapshot.sourceSizeBytes
   };
 }

package/src/source-snapshot.mjs

@@ -62,7 +62,8 @@ export async function createSourceSnapshot(sourceDirectory, options = {}) {
     throw new Error(`Snapshot source is not a directory: ${root}`);
   }
 
-  const matcher = ignore().add(DEFAULT_IGNORE_RULES);
+  const sourceExcludes = normalizeAdditionalIgnoreRules(options.ignoreRules);
+  const matcher = ignore().add(DEFAULT_IGNORE_RULES).add(sourceExcludes);
   const customRules = await readOptionalText(join(root, ".legoignore"));
   if (customRules) matcher.add(customRules);
 
@@ -117,6 +118,7 @@ export async function createSourceSnapshot(sourceDirectory, options = {}) {
     manifest,
     root,
     skippedSymlinkCount: skippedSymlinks.length,
+    sourceExcludes,
     sourceSizeBytes
   };
 
@@ -153,6 +155,19 @@ export async function createSourceSnapshot(sourceDirectory, options = {}) {
   }
 }
 
+function normalizeAdditionalIgnoreRules(value) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) throw new Error("Source exclusions must be an array");
+  if (value.length > 100) throw new Error("No more than 100 --source-exclude rules are allowed");
+  return value.map((item) => {
+    const rule = String(item ?? "").trim();
+    if (!rule || rule.length > 256 || rule.includes("\0") || rule.includes("\n") || rule.includes("\r")) {
+      throw new Error("Each --source-exclude rule must be a non-empty single-line pattern of at most 256 characters");
+    }
+    return rule;
+  });
+}
+
 function digest(value) {
   return createHash("sha256").update(value).digest("hex");
 }