@fargowealth/fargo-ai-cli 0.6.0 → 0.7.0

package/CHANGELOG.md

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

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.0
 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
 
@@ -70,11 +72,16 @@ fargo lego deploy \
   --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.
 
 The command creates and uploads two immutable archives:
 

package/package.json

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

package/src/cli.mjs

@@ -58,14 +58,23 @@ 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 result = await deployLocalLegoApp(store, {
-        appId: requiredOption(args, "--app"),
-        deployDir: requiredOption(args, "--deploy-dir"),
+        appId,
+        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")
+        target,
+        version,
+        versionName
       }, options);
       stdout.write(`${JSON.stringify(result)}\n`);
       return;
@@ -138,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;
@@ -160,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) {
@@ -192,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.6.0";
+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/lego-deploy.mjs

@@ -9,25 +9,34 @@ 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),
+    input.skipSource ? Promise.resolve(undefined) : createSourceSnapshot(input.source || ".", options.snapshotOptions),
     createDeploymentArtifact(input.deployDir, { ...options.artifactOptions, target, entrypoint })
   ]);
 
   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 +47,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,

package/src/lego-snapshots.mjs

@@ -5,11 +5,26 @@ import { createSourceSnapshot } from "./source-snapshot.mjs";
 export async function uploadLegoSourceSnapshot(store, input, options = {}) {
   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