@fargowealth/fargo-ai-cli 0.7.0 → 0.7.2

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.7.2
+
+- Added `fargo lego deploy --help` with the complete Worker Static Assets
+  contract and an executable full-stack example.
+- Worker deploys now fail early for manual `.fargo-assets/`, frontend
+  `index.html` files inside `--deploy-dir`, overlapping module/assets
+  directories, and asset options missing `--assets-dir`.
+- Dry-run deployment summaries now show manifest schema version and separate
+  Worker-module and Static Asset file counts.
+
+## 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

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.7.0
+npm install -g @fargowealth/fargo-ai-cli@0.7.2
 fargo version
 ```
 
@@ -69,6 +69,7 @@ npm run build
 fargo lego deploy \
   --app app_xxx \
   --source . \
+  --source-exclude node_modules/ \
   --deploy-dir dist \
   --target pages \
   --entrypoint index.html \
@@ -83,6 +84,47 @@ 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.
+
+`.fargo-assets/` is an internal archive directory reserved for Fargo CLI. Do
+not create it, copy frontend files into it, or place browser output inside the
+Worker `--deploy-dir`. Always provide the original frontend build directory
+through `--assets-dir`; the CLI packages it under `.fargo-assets/` and emits the
+required schema v2 metadata. Worker deploys fail early when they contain a
+manual `.fargo-assets/`, a root `index.html`, overlapping deploy/assets
+directories, or asset options without `--assets-dir`.
+
+Run `fargo lego deploy --help` for the complete option list and a full-stack
+Worker example. A dry run reports the manifest schema version and separate
+Worker-module and Static Asset file counts.
+
+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:
 
 1. a filtered source snapshot for recovery and provenance;
@@ -101,14 +143,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.7.0",
+  "version": "0.7.2",
   "description": "Agent-neutral Fargo AI CLI, MCP client, and LEGO project tooling",
   "type": "module",
   "bin": {

package/src/cli.mjs

@@ -15,6 +15,14 @@ export async function runCli(args, options = {}) {
   const stderr = options.stderr ?? process.stderr;
   const store = options.store ?? createCredentialStore(options.storeOptions);
   try {
+    if (isHelpOption(args) && args[0] === "lego" && args[1] === "deploy") {
+      stdout.write(LEGO_DEPLOY_HELP);
+      return;
+    }
+    if ((isHelpOption(args) && args.length === 1) || (args[0] === "help" && args.length === 1)) {
+      stdout.write(ROOT_HELP);
+      return;
+    }
     if (args[0] === "version" || args[0] === "--version" || args[0] === "-v") {
       stdout.write(`fargo-cli version ${CLI_VERSION}\n`);
       return;
@@ -59,19 +67,28 @@ export async function runCli(args, options = {}) {
     }
     if (args[0] === "lego" && args[1] === "deploy") {
       const appId = requiredOption(args, "--app");
+      const assetsDirectory = optionValue(args, "--assets-dir")?.trim();
+      assertAssetsDirectoryProvided(args, assetsDirectory);
       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,
+        assetsBinding: optionValue(args, "--assets-binding"),
+        assetsDirectory,
+        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") ?? ".",
+        sourceExcludes: optionValues(args, "--source-exclude"),
         target,
         version,
         versionName
@@ -82,6 +99,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")
@@ -94,7 +112,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();
@@ -121,6 +139,82 @@ export async function runCli(args, options = {}) {
   }
 }
 
+const ROOT_HELP = `Usage: fargo <command> [options]
+
+Commands:
+  auth login|device|status|logout
+  mcp serve|tools|call
+  lego snapshot upload|list|download
+  lego deploy
+  lego d1 migrate plan|apply
+  workbuddy install
+  version
+
+Run "fargo lego deploy --help" for deployment options.
+`;
+
+const LEGO_DEPLOY_HELP = `Usage: fargo lego deploy [options]
+
+Required:
+  --app <appId>                 LEGO App ID
+  --deploy-dir <directory>      Built Pages files or Worker modules
+  --target <pages|worker>       Deployment target
+  --version <version>           Release version
+  --name <name>                 Release name
+  --notes <text>                Release notes (or --notes-file <path>)
+
+Source and execution:
+  --source <directory>          Source snapshot root (default: .)
+  --source-exclude <pattern>    Repeatable source exclusion
+  --entrypoint <path>           Default: index.html for Pages, index.js for Worker
+  --skip-source                 Do not upload a source snapshot
+  --dry-run                     Validate and summarize without network writes
+
+Worker Static Assets:
+  --assets-dir <directory>      Built browser assets; required for Worker frontends
+  --assets-binding <name>       Assets binding (default: ASSETS)
+  --assets-html-handling <mode> auto-trailing-slash, force-trailing-slash,
+                                drop-trailing-slash, or none
+  --assets-not-found-handling <mode>
+                                none, 404-page, or single-page-application
+  --assets-run-worker-first     Run the Worker before static asset routing
+  --assets-run-worker-first-route <glob>
+                                Repeatable Worker-first route
+
+Example:
+  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
+
+.fargo-assets/ is an internal archive directory reserved for Fargo CLI.
+Do not create or copy it manually; always pass browser output with --assets-dir.
+`;
+
+function isHelpOption(args) {
+  return args.includes("--help") || args.includes("-h");
+}
+
+function assertAssetsDirectoryProvided(args, assetsDirectory) {
+  const assetOptions = [
+    "--assets-binding",
+    "--assets-dir",
+    "--assets-html-handling",
+    "--assets-not-found-handling",
+    "--assets-run-worker-first",
+    "--assets-run-worker-first-route"
+  ];
+  if (!assetsDirectory && assetOptions.some((name) => hasOption(args, name))) {
+    throw new Error("Worker Static Assets options require --assets-dir <directory>; .fargo-assets/ is reserved for Fargo CLI and must not be created manually");
+  }
+}
+
+function hasOption(args, name) {
+  return args.some((value) => value === name || value.startsWith(`${name}=`));
+}
+
 async function authorizeWithPkce(args, stdout, store, options) {
   const browserMode = optionValue(args, "--open-browser") ?? "auto";
   await authorizePkce(store, {
@@ -150,6 +244,7 @@ async function runLegoSnapshotCommand(args, stdout, store, options) {
       notes: await optionalNotesOption(args),
       purpose: "backup",
       source: optionValue(args, "--source") ?? ".",
+      sourceExcludes: optionValues(args, "--source-exclude"),
       version: requiredVersionOption(args, "--version", 120),
       versionName: requiredTextOption(args, "--name", 160)
     }, options);
@@ -262,3 +357,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.7.0";
+export const CLI_VERSION = "0.7.2";
 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

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { lstat, opendir, readFile } from "node:fs/promises";
-import { basename, extname, join, resolve, sep } from "node:path";
+import { basename, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { strToU8, zipSync } from "fflate";
 import ignore from "ignore";
 
@@ -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,32 @@ 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);
+  await assertReservedArchiveDirectoryAbsent(root);
   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 (target === "worker" && candidates.some((file) => file.path === "index.html")) {
+    throw new Error("Worker deployment output contains browser entry file 'index.html'. Keep Worker modules in --deploy-dir and pass frontend output separately with --assets-dir <directory>");
+  }
+  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}`);
+    }
+    if (directoriesOverlap(root, assetsRoot)) {
+      throw new Error("--deploy-dir and --assets-dir must be separate, non-overlapping directories so browser assets are not uploaded as Worker modules");
+    }
+    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 +95,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 +103,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 +132,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 +145,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 +168,54 @@ export async function createDeploymentArtifact(deployDirectory, options = {}) {
   }
 }
 
+async function assertReservedArchiveDirectoryAbsent(root) {
+  const reservedPath = join(root, WORKER_ASSET_ARCHIVE_DIRECTORY);
+  const reservedStat = await lstat(reservedPath).catch((error) => {
+    if (error?.code === "ENOENT") return undefined;
+    throw error;
+  });
+  if (reservedStat) {
+    throw new Error("Deployment output contains reserved path '.fargo-assets'. Do not create it manually; pass browser output with --assets-dir <directory> and Fargo CLI will package it");
+  }
+}
+
+function directoriesOverlap(left, right) {
+  return isSameOrInside(left, right) || isSameOrInside(right, left);
+}
+
+function isSameOrInside(parent, candidate) {
+  const path = relative(parent, candidate);
+  return path === "" || (!path.startsWith("..") && !isAbsolute(path));
+}
+
+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

@@ -27,16 +27,25 @@ export async function uploadLegoDeployArtifact(store, input, options = {}) {
 }
 
 export function deploymentArtifactSummary(artifact) {
+  const assetPrefix = artifact.assets ? `${artifact.assets.directory}/` : undefined;
+  const staticAssetFileCount = assetPrefix
+    ? artifact.manifest.files.filter((file) => file.path.startsWith(assetPrefix)).length
+    : 0;
   return {
     archiveName: artifact.archiveName,
     archiveSha256: artifact.archiveSha256,
     archiveSizeBytes: artifact.archive.byteLength,
+    assets: artifact.assets,
     contentSha256: artifact.contentSha256,
     contentSizeBytes: artifact.contentSizeBytes,
     entrypoint: artifact.entrypoint,
+    fileBreakdown: artifact.target === "worker"
+      ? { staticAssets: staticAssetFileCount, workerModules: artifact.fileCount - staticAssetFileCount }
+      : { pagesFiles: artifact.fileCount },
     fileCount: artifact.fileCount,
     root: artifact.root,
     skippedSymlinkCount: artifact.skippedSymlinkCount,
+    schemaVersion: artifact.manifest.schemaVersion,
     target: artifact.target
   };
 }

package/src/lego-deploy.mjs

@@ -9,8 +9,22 @@ 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 })
+    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) {
@@ -79,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,7 +3,10 @@ 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,
@@ -81,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");
 }