@fargowealth/fargo-ai-cli 0.7.1 → 0.7.2

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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,

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.1
+npm install -g @fargowealth/fargo-ai-cli@0.7.2
 fargo version
 ```
 
@@ -108,6 +108,18 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fargowealth/fargo-ai-cli",
-  "version": "0.7.1",
+  "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,6 +67,8 @@ 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);
@@ -68,7 +78,7 @@ export async function runCli(args, options = {}) {
       const result = await deployLocalLegoApp(store, {
         appId,
         assetsBinding: optionValue(args, "--assets-binding"),
-        assetsDirectory: optionValue(args, "--assets-dir"),
+        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"),
@@ -129,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, {

package/src/constants.mjs

@@ -1,4 +1,4 @@
-export const CLI_VERSION = "0.7.1";
+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";
 
@@ -38,6 +38,7 @@ 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);
@@ -45,12 +46,18 @@ export async function createDeploymentArtifact(deployDirectory, options = {}) {
   const candidates = [];
   const skippedSymlinks = [];
   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);
@@ -161,6 +168,26 @@ 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");

package/src/lego-deploy-artifacts.mjs

@@ -27,6 +27,10 @@ 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,
@@ -35,9 +39,13 @@ export function deploymentArtifactSummary(artifact) {
     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
   };
 }